Overview
Contacts represent customers or users who interact with your business through Chatwoot. Each contact can have multiple conversations and be associated with different inboxes.
Retrieve a paginated list of contacts in your account.
GET /api/v1/accounts/{account_id}/contacts
Path Parameters
Query Parameters
Page number for pagination
Sort field: email, name, phone_number, last_activity_at, created_at, company, city, country
Include contact inbox information
Response
Unique identifier for the contact
Whether the contact is blocked
Custom attributes for the contact
Additional contact information
Unix timestamp of last activity
Unix timestamp of creation
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/contacts?page=1 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Example Response
{
"payload": [
{
"id": 1,
"name": "John Doe",
"email": "[email protected]",
"phone_number": "+1234567890",
"identifier": "user_123",
"thumbnail": "https://example.com/avatar.jpg",
"blocked": false,
"custom_attributes": {
"plan": "premium",
"signup_date": "2024-01-15"
},
"additional_attributes": {
"city": "New York",
"country": "USA"
},
"last_activity_at": 1704067200,
"created_at": 1672531200,
"contact_inboxes": [
{
"id": 1,
"inbox_id": 1,
"source_id": "external_123"
}
]
}
]
}
GET /api/v1/accounts/{account_id}/contacts/{id}
Path Parameters
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/contacts/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
POST /api/v1/accounts/{account_id}/contacts
Path Parameters
Request Body
Contact phone number with country code
Unique identifier from your system
Inbox ID to associate the contact with
External source ID for the contact inbox
Whether to block the contact
Custom attributes as key-value pairs
Additional attributes as key-value pairs
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/contacts \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "[email protected]",
"phone_number": "+1987654321",
"identifier": "user_456",
"inbox_id": 1,
"custom_attributes": {
"plan": "basic",
"signup_date": "2024-02-01"
},
"additional_attributes": {
"city": "San Francisco",
"country": "USA",
"company": "Tech Corp"
}
}'
Example Response
{
"id": 2,
"name": "Jane Smith",
"email": "[email protected]",
"phone_number": "+1987654321",
"identifier": "user_456",
"blocked": false,
"custom_attributes": {
"plan": "basic",
"signup_date": "2024-02-01"
},
"additional_attributes": {
"city": "San Francisco",
"country": "USA",
"company": "Tech Corp"
},
"created_at": 1706745600
}
PATCH /api/v1/accounts/{account_id}/contacts/{id}
Path Parameters
The ID of the contact to update
Request Body
Accepts the same parameters as Create Contact.
Example Request
curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1/contacts/2 \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith Updated",
"custom_attributes": {
"plan": "premium"
}
}'
Custom attributes are merged with existing attributes. To remove an attribute, use the delete custom attributes endpoint.
DELETE /api/v1/accounts/{account_id}/contacts/{id}
Path Parameters
The ID of the contact to delete
Example Request
curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/contacts/2 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
You cannot delete a contact who is currently online. Wait for them to go offline before deleting.
GET /api/v1/accounts/{account_id}/contacts/search
Path Parameters
Query Parameters
Example Request
curl -X GET "https://app.chatwoot.com/api/v1/accounts/1/contacts/search?q=john" \
-H "api_access_token: YOUR_ACCESS_TOKEN"
POST /api/v1/accounts/{account_id}/contacts/filter
Path Parameters
Request Body
Array of filter conditions
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/contacts/filter \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"payload": [
{
"attribute_key": "email",
"filter_operator": "contains",
"values": ["@example.com"]
}
]
}'
GET /api/v1/accounts/{account_id}/contacts/active
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/contacts/active \
-H "api_access_token: YOUR_ACCESS_TOKEN"
GET /api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes
Path Parameters
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/contacts/1/contactable_inboxes \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Delete Custom Attributes
Remove specific custom attributes from a contact.
POST /api/v1/accounts/{account_id}/contacts/{id}/destroy_custom_attributes
Path Parameters
Request Body
Array of custom attribute keys to remove
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/contacts/1/destroy_custom_attributes \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"custom_attributes": ["old_attribute", "unused_field"]
}'
Delete Avatar
Remove the contact’s avatar image.
DELETE /api/v1/accounts/{account_id}/contacts/{id}/avatar
Path Parameters
Example Request
curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/contacts/1/avatar \
-H "api_access_token: YOUR_ACCESS_TOKEN"
POST /api/v1/accounts/{account_id}/contacts/import
Path Parameters
Request Body
CSV file containing contact data
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/contacts/import \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-F "[email protected]"
POST /api/v1/accounts/{account_id}/contacts/export
Path Parameters
Request Body
Array of column names to export
Filter conditions for export
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/contacts/export \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"column_names": ["name", "email", "phone_number"]
}'
The export is processed asynchronously. You’ll receive the CSV file via email when ready.
Error Responses
{
"error": "Contact not found"
}
{
"message": "Cannot delete John while they are online"
}
Validation Errors
{
"error": "Validation failed",
"message": "Email is invalid"
}
