Skip to main content

​
Overview

Agents are team members who can access the Chatwoot dashboard and respond to conversations. Use the Agents API to manage your team.

​
List All Agents

Retrieve a list of all agents in the account. 
GET /api/v1/accounts/{account_id}/agents

​
Path Parameters

​
account_id
integer
required
The ID of the account

​
Response

​
id
integer
Agent ID
​
name
string
Agent full name
​
email
string
Agent email address
​
role
string
Agent role: agent or administrator
​
availability
string
Availability status: available, busy, or offline
​
auto_offline
boolean
Whether agent automatically goes offline
​
confirmed
boolean
Whether the agent has confirmed their email

​
Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/agents \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

​
Example Response

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "role": "administrator",
    "availability": "available",
    "auto_offline": true,
    "confirmed": true,
    "avatar_url": "https://example.com/avatar.jpg"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "[email protected]",
    "role": "agent",
    "availability": "busy",
    "auto_offline": false,
    "confirmed": true,
    "avatar_url": null
  }
]

​
Create Agent

Invite a new agent to your account. 
POST /api/v1/accounts/{account_id}/agents

​
Path Parameters

​
account_id
integer
required
The ID of the account

​
Request Body

​
agent[email]
string
required
Agent email address
​
agent[name]
string
required
Agent full name
​
agent[role]
string
default:"agent"
Agent role: agent or administrator
​
agent[availability]
string
default:"available"
Initial availability: available, busy, or offline
​
agent[auto_offline]
boolean
default:"true"
Whether agent automatically goes offline

​
Example Request

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/agents \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "email": "[email protected]",
      "name": "New Agent",
      "role": "agent",
      "availability": "available",
      "auto_offline": true
    }
  }'

​
Example Response

{
  "id": 3,
  "name": "New Agent",
  "email": "[email protected]",
  "role": "agent",
  "availability": "available",
  "auto_offline": true,
  "confirmed": false
}
An invitation email will be sent to the agent’s email address. The agent must confirm their email before they can access the account.

​
Update Agent

Update an existing agent’s information. 
PATCH /api/v1/accounts/{account_id}/agents/{id}

​
Path Parameters

​
account_id
integer
required
The ID of the account
​
id
integer
required
The ID of the agent to update

​
Request Body

​
agent[name]
string
Agent full name
​
agent[role]
string
Agent role: agent or administrator
​
agent[availability]
string
Availability: available, busy, or offline
​
agent[auto_offline]
boolean
Whether agent automatically goes offline

​
Example Request

curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1/agents/2 \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "Jane Smith (Updated)",
      "role": "administrator",
      "availability": "available"
    }
  }'

​
Example Response

{
  "id": 2,
  "name": "Jane Smith (Updated)",
  "email": "[email protected]",
  "role": "administrator",
  "availability": "available",
  "auto_offline": false,
  "confirmed": true
}

​
Delete Agent

Remove an agent from the account. 
DELETE /api/v1/accounts/{account_id}/agents/{id}

​
Path Parameters

​
account_id
integer
required
The ID of the account
​
id
integer
required
The ID of the agent to delete

​
Example Request

curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/agents/3 \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

​
Response

Returns 200 OK with no body.
Deleting an agent will remove their access to the account. If the user is not a member of any other accounts, their user record will also be deleted.

​
Bulk Create Agents

Invite multiple agents at once using email addresses. 
POST /api/v1/accounts/{account_id}/agents/bulk_create

​
Path Parameters

​
account_id
integer
required
The ID of the account

​
Request Body

​
emails
array
required
Array of email addresses to invite

​
Example Request

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/agents/bulk_create \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ]
  }'

​
Response

Returns 200 OK with no body.
Agents created through bulk create will:
  • Have their name derived from their email address
  • Be assigned the default agent role
  • Receive invitation emails
  • Any duplicate or invalid emails will be skipped

​
Agent Roles

​
Agent

Standard team member with permissions to:
  • View and respond to assigned conversations
  • Access contacts and conversation history
  • Use reports and analytics
  • Manage personal settings

​
Administrator

Full access to all account features including:
  • All agent permissions
  • Manage team members and agents
  • Configure inboxes and channels
  • Set up automations and workflows
  • Access account settings
  • Manage integrations and webhooks

​
Agent Availability Status

​
Available

Agent is online and can receive new conversations.

​
Busy

Agent is online but should not receive new automatic assignments.

​
Offline

Agent is not available to receive conversations.

​
Auto Offline Mode

When auto_offline is enabled, agents are automatically set to offline when they:
  • Close the browser tab
  • Are inactive for an extended period
  • Log out of the application

​
Account Limits

Accounts have a maximum number of agents based on their plan. Creating agents beyond this limit will result in a 402 Payment Required error.
Error response when limit is exceeded: 
{
  "error": "Account limit exceeded. Please purchase more licenses"
}

​
Error Responses

​
Agent Not Found

{
  "error": "Agent not found"
}

​
Validation Errors

{
  "error": "Validation failed",
  "message": "Email has already been taken"
}

​
Insufficient Permissions

{
  "error": "Access denied"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us