Overview
Accounts are the top-level resource in Chatwoot. Each account contains inboxes, agents, contacts, and conversations.
Get Account Details
Retrieve information about a specific account.
GET /api/v1/accounts/{account_id}
Path Parameters
Response
Account default locale (e.g., “en”)
Custom domain for the account
Custom attributes for the account
Account settings configuration
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Example Response
{
"id": 1,
"name": "Acme Corporation",
"locale": "en",
"domain": "acme.chatwoot.com",
"support_email": "[email protected]",
"custom_attributes": {
"industry": "technology",
"company_size": "50-100",
"timezone": "America/New_York"
},
"settings": {
"auto_resolve_after": 30,
"audio_transcriptions": true
}
}
Create Account
Create a new Chatwoot account with a user.
Account creation must be enabled by the system administrator. Check the ENABLE_ACCOUNT_SIGNUP environment variable.
Request Body
Email address for the account owner
Full name of the account owner
Password for the account owner
Preferred locale (language code)
h_captcha_client_response
Captcha response token (if captcha is enabled)
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts \
-H "Content-Type: application/json" \
-d '{
"account_name": "Acme Corporation",
"email": "[email protected]",
"user_full_name": "John Doe",
"password": "securePassword123",
"locale": "en"
}'
Example Response
{
"id": 1,
"uid": "[email protected]",
"email": "[email protected]",
"name": "John Doe",
"account_id": 1,
"accounts": [
{
"id": 1,
"name": "Acme Corporation",
"locale": "en"
}
]
}
Update Account
Update account information and settings.
PATCH /api/v1/accounts/{account_id}
Path Parameters
The ID of the account to update
Request Body
Account locale (e.g., “en”, “es”, “fr”)
Industry type (stored in custom_attributes)
Company size range (stored in custom_attributes)
Timezone (stored in custom_attributes)
Number of days to auto-resolve conversations
Message sent when conversation is auto-resolved
auto_resolve_ignore_waiting
Ignore waiting status when auto-resolving
Enable audio transcriptions
Label to apply when auto-resolving
Example Request
curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"support_email": "[email protected]",
"auto_resolve_after": 30,
"industry": "Technology",
"timezone": "America/Los_Angeles"
}'
Example Response
{
"id": 1,
"name": "Acme Corp",
"locale": "en",
"support_email": "[email protected]",
"custom_attributes": {
"industry": "Technology",
"timezone": "America/Los_Angeles"
},
"settings": {
"auto_resolve_after": 30
}
}
Update Active Status
Update the last active timestamp for the current user in the account.
POST /api/v1/accounts/{account_id}/update_active_at
Path Parameters
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/update_active_at \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Response
Returns 200 OK with no body.
Get Cache Keys
Retrieve cache keys for labels, inboxes, and teams in the account.
GET /api/v1/accounts/{account_id}/cache_keys
Path Parameters
Response
Cache keys for account resources
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/cache_keys \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Example Response
{
"cache_keys": {
"label": "1234567890",
"inbox": "0987654321",
"team": "1357924680"
}
}
Error Responses
Account Not Found
{
"error": "Account not found"
}
Signup Disabled
{
"error": "Account signup is disabled"
}
Invalid Parameters
{
"error": "Invalid parameters",
"message": "account_name and user_full_name are required"
}
User Already Exists
{
"error": "User with this email already exists"
}
Account Scoped Resources
All resources in Chatwoot are scoped to an account:
Use the account ID in the URL path to access these resources:
/api/v1/accounts/{account_id}/contacts
/api/v1/accounts/{account_id}/conversations
/api/v1/accounts/{account_id}/inboxes
