Agents
Agents are team members who can access Inbox, handle conversations, and collaborate on customer communication. An agent is created for a user automatically when the user is invited to the workspace and he accepts the invitation and accessed the portal. However that agent is created with default name, if you want to change the name you can do it in the portal. You can manage agents directly from the Agents page.
What you can do in Agents
- View all agents in your workspace.
- Edit existing agent details.
- Create API key agents for programmatic access, without a portal login.
- Remove agents who no longer need access to inbox.
Editable agent properties
When you create or edit an agent in the portal, you can configure:
| Property | Description |
|---|---|
| Name / Surname | Display name shown in Inbox and assignment lists. |
| Eligible for automatic assignment | When enabled (default), the agent can be picked by Auto Assign and load-balanced routing on channels. Turn this off for supervisors or bots that should only receive manual assignments. |
| Greeting message | Optional message sent automatically to the customer when a new conversation is assigned to this agent. Available when editing an existing agent. Leave blank to send no greeting. |
API key agents
In addition to agents linked to workspace users, you can create API key agents for programmatic access.
Use API key agents when:
- A backend service sends or receives messages on behalf of a logical agent identity.
- You need API access tied to a specific agent without a portal login.
- You integrate Bread Crumbs with external systems that act as automated responders.
API key agents do not sign in to the portal. They authenticate using the generated API key. You can still assign conversations to them manually or include them in channel routing where applicable.
Create an agent together with its API key
- Open the Agents page and click Add New Agent.
- Choose API key agent instead of Link to workspace user. If every workspace user already has an agent, this option is selected for you and Link to workspace user is unavailable.
- Fill in Name and, optionally, Surname.
- Optionally set an API key label. Leave it empty to get a default label built from the agent name, for example
API key · Support Bot. - Click Save. Bread Crumbs creates the agent and its API key in one step, then shows Your API key is ready with the key and the workspace ID.
- Click Copy details and store the key securely. The secret is shown once and cannot be retrieved again — if you lose it, delete the key and generate a new one.
The new agent appears in the agents list like any other agent. Open it with Edit to change the name, the greeting message, or to turn off Eligible for automatic assignment.
Create an API key for an agent that already exists
If the agent is already in your workspace — including agents created for portal users — you can attach a key to it without creating a new agent:
- Open the API Keys page and click Add New API Key.
- Type a Label for the key.
- Pick the agent in Linked agent. Keep None (workspace-wide key) if you want a key with full workspace access instead.
- Click Save, then Copy details to store the key and the workspace ID.
The Linked agent column in the API Keys list shows which agent each key acts as, and a dash for workspace-wide keys. An agent can have more than one key, which is handy when you rotate keys or give separate keys to separate integrations. Deleting a key does not delete the agent, so when you retire an integration delete its keys from the API Keys page and remove the agent from the Agents page if it is no longer needed.
What an agent API key can do
Requests made with an agent API key act as that agent and are limited to the Agent+ role:
- They read and act on conversations assigned to that agent, plus unassigned ones.
- Messages they send are attributed to that agent in Inbox, in the conversation timeline, and in reports.
- They cannot manage the workspace, so they cannot create agents, generate other API keys, or change workspace settings.
For the GraphQL mutations, fields, and request examples, see Agent API keys and Create agent with API key in the API reference.
Why agent setup matters
Only configured agents can work conversations in Inbox. So the system can do assignments and track the agent’s performance and activity.
Best practices
- Keep the agent list up to date as your team changes.
- Remove access quickly for users who leave the team.
- Confirm each active support user is configured as an agent to avoid Inbox access issues.
Troubleshooting
- User cannot access Inbox: Check that the user is created as an agent.
- Agent not found in list: Use search and verify workspace context.
- Wrong assignment behavior: Review agent setup and conversation assignment rules.