Overview
Conversations represent the communication threads between your team and contacts. Each conversation belongs to an inbox and can contain multiple messages.
List Conversations
Retrieve a list of conversations with filtering options.
GET /api/v1/accounts/{account_id}/conversations
Path Parameters
Query Parameters
Filter by status: open, pending, resolved, snoozed
Filter by assignee: me, unassigned, all
Page number for pagination
Response
Conversation status: open, pending, resolved, snoozed
Priority level: low, medium, high, urgent, or null
Assigned agent information
Number of unread messages
Unix timestamp of last activity
Example Request
curl -X GET "https://app.chatwoot.com/api/v1/accounts/1/conversations?status=open&page=1" \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Example Response
{
"data": {
"payload": [
{
"id": 1,
"display_id": 1,
"inbox_id": 1,
"status": "open",
"priority": "high",
"muted": false,
"assignee": {
"id": 1,
"name": "John Doe",
"email": "[email protected]"
},
"contact": {
"id": 1,
"name": "Customer Name",
"email": "[email protected]"
},
"unread_count": 3,
"last_activity_at": 1704067200,
"created_at": 1704060000
}
],
"meta": {
"count": 25,
"current_page": 1
}
}
}
Get Conversation
Retrieve details of a specific conversation.
GET /api/v1/accounts/{account_id}/conversations/{id}
Path Parameters
The display ID of the conversation
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/conversations/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Create Conversation
Create a new conversation with a contact.
POST /api/v1/accounts/{account_id}/conversations
Path Parameters
Request Body
External source identifier
Initial status: open, pending, resolved
Agent ID to assign the conversation to
Message type: incoming or outgoing
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"contact_id": 1,
"inbox_id": 1,
"status": "open",
"assignee_id": 1,
"message": {
"content": "Hello, I need help with my order",
"message_type": "incoming"
}
}'
Example Response
{
"id": 1,
"display_id": 1,
"inbox_id": 1,
"status": "open",
"priority": null,
"assignee": {
"id": 1,
"name": "John Doe"
},
"contact": {
"id": 1,
"name": "Customer Name"
},
"created_at": 1704067200
}
Update Conversation
Update conversation properties.
PATCH /api/v1/accounts/{account_id}/conversations/{id}
Path Parameters
The display ID of the conversation
Request Body
Priority: low, medium, high, urgent, or null
Example Request
curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1/conversations/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"priority": "high"
}'
Delete Conversation
Delete a conversation permanently.
DELETE /api/v1/accounts/{account_id}/conversations/{id}
Path Parameters
The display ID of the conversation
Example Request
curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/conversations/1 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Deleting a conversation is permanent and cannot be undone. All messages and metadata will be removed.
Toggle Status
Change the conversation status.
POST /api/v1/accounts/{account_id}/conversations/{id}/toggle_status
Path Parameters
The display ID of the conversation
Request Body
New status: open, pending, resolved, snoozed
ISO 8601 timestamp when to unsnooze (required if status is snoozed)
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/toggle_status \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "resolved"
}'
Toggle Priority
Change the conversation priority.
POST /api/v1/accounts/{account_id}/conversations/{id}/toggle_priority
Path Parameters
The display ID of the conversation
Request Body
Priority: low, medium, high, urgent, or null
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/toggle_priority \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"priority": "urgent"
}'
Mute Conversation
Mute notifications for a conversation.
POST /api/v1/accounts/{account_id}/conversations/{id}/mute
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/mute \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Unmute Conversation
Unmute notifications for a conversation.
POST /api/v1/accounts/{account_id}/conversations/{id}/unmute
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/unmute \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Mark as Unread
Mark conversation as unread.
POST /api/v1/accounts/{account_id}/conversations/{id}/unread
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/unread \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Update Last Seen
Update agent’s last seen timestamp.
POST /api/v1/accounts/{account_id}/conversations/{id}/update_last_seen
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/update_last_seen \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Update Custom Attributes
Update conversation custom attributes.
POST /api/v1/accounts/{account_id}/conversations/{id}/custom_attributes
Request Body
Custom attributes as key-value pairs
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/custom_attributes \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"custom_attributes": {
"order_id": "ORD-12345",
"product_type": "subscription"
}
}'
Get Conversation Transcript
Send conversation transcript via email.
POST /api/v1/accounts/{account_id}/conversations/{id}/transcript
Request Body
Email address to send transcript to
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/transcript \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]"
}'
Email transcripts may be rate-limited based on your account plan.
Get Attachments
Retrieve all attachments in a conversation.
GET /api/v1/accounts/{account_id}/conversations/{id}/attachments
Query Parameters
Page number (100 attachments per page)
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/conversations/1/attachments \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Search Conversations
Search conversations by content.
GET /api/v1/accounts/{account_id}/conversations/search
Query Parameters
Example Request
curl -X GET "https://app.chatwoot.com/api/v1/accounts/1/conversations/search?q=order" \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Filter Conversations
Filter conversations using advanced filters.
POST /api/v1/accounts/{account_id}/conversations/filter
Request Body
Array of filter conditions
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/filter \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"payload": [
{
"attribute_key": "status",
"filter_operator": "equal_to",
"values": ["open"]
},
{
"attribute_key": "priority",
"filter_operator": "equal_to",
"values": ["high"]
}
]
}'
GET /api/v1/accounts/{account_id}/conversations/meta
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/conversations/meta \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Conversation Status Types
Open
Active conversations requiring attention.
Pending
Conversations waiting for customer response.
Resolved
Closed conversations that are resolved.
Snoozed
Conversations temporarily hidden until a specific time.
Priority Levels
- Low: Non-urgent matters
- Medium: Standard priority
- High: Important issues
- Urgent: Critical issues requiring immediate attention
- null: No priority set
