Overview
Messages are the individual communications within a conversation. They can be sent by agents, contacts, or agent bots.
List Messages
Retrieve messages from a conversation.
GET /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages
Path Parameters
The display ID of the conversation
Query Parameters
Page number for pagination
Response
Message type: 0 (incoming), 1 (outgoing), 2 (activity)
Content type: text, input_text, input_textarea, cards, form, article
Delivery status: sent, delivered, read, failed
Unix timestamp of creation
Whether the message is a private note
Array of attachment objects
Example Request
curl -X GET https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Example Response
{
"payload": [
{
"id": 1,
"content": "Hello, how can I help you?",
"message_type": 1,
"content_type": "text",
"status": "sent",
"created_at": 1704067200,
"private": false,
"sender": {
"id": 1,
"name": "John Doe",
"type": "User"
},
"attachments": []
},
{
"id": 2,
"content": "I need help with my order",
"message_type": 0,
"content_type": "text",
"status": "sent",
"created_at": 1704067260,
"private": false,
"sender": {
"id": 1,
"name": "Customer Name",
"type": "Contact"
},
"attachments": []
}
],
"meta": {
"contact_last_seen_at": 1704067260
}
}
Create Message
Send a new message in a conversation.
POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages
Path Parameters
The display ID of the conversation
Request Body
Message type: incoming or outgoing
Whether this is a private note (only visible to agents)
Content type: text, input_text, input_textarea, cards, form, article
Additional content attributes
Array of attachment objects or file uploads
Example Request (Text Message)
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Thank you for contacting us. I will help you with your order.",
"message_type": "outgoing",
"private": false
}'
Example Request (Private Note)
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Customer seems frustrated. Handle with care.",
"message_type": "outgoing",
"private": true
}'
Example Request (With Attachment)
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-F "content=Please find the document attached" \
-F "message_type=outgoing" \
-F "attachments[]=@/path/to/file.pdf"
Example Response
{
"id": 3,
"content": "Thank you for contacting us. I will help you with your order.",
"message_type": 1,
"content_type": "text",
"status": "sent",
"created_at": 1704067320,
"private": false,
"sender": {
"id": 1,
"name": "John Doe",
"type": "User"
},
"conversation_id": 1
}
Update Message
Update message status (API inbox only).
PATCH /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}
Path Parameters
The display ID of the conversation
Request Body
New status: sent, delivered, read, failed
Error message if status is failed
Example Request
curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages/3 \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "delivered"
}'
Message status updates are only allowed for API inboxes. This is typically used for external messaging channels.
Delete Message
Delete a message from a conversation.
DELETE /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}
Path Parameters
The display ID of the conversation
The ID of the message to delete
Example Request
curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages/3 \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Deleting a message replaces its content with “This message was deleted” and removes all attachments. This action cannot be undone.
Retry Message
Retry sending a failed message.
POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/retry
Path Parameters
The display ID of the conversation
The ID of the message to retry
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages/3/retry \
-H "api_access_token: YOUR_ACCESS_TOKEN"
Translate Message
Translate a message to a different language.
POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{id}/translate
Path Parameters
The display ID of the conversation
The ID of the message to translate
Request Body
Target language code (e.g., “en”, “es”, “fr”, “de”)
Example Request
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages/2/translate \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target_language": "es"
}'
Example Response
{
"content": "Necesito ayuda con mi pedido"
}
Translations are cached. Subsequent requests for the same language will return the cached translation.
Message Types
Incoming (0)
Messages received from contacts.
Outgoing (1)
Messages sent by agents or bots to contacts.
Activity (2)
System-generated activity messages (e.g., status changes, assignments).
Content Types
text
Plain text message.
input_text
Single-line text input form.
input_textarea
Multi-line text input form.
cards
Rich card layout with images, titles, and buttons.
Interactive form with multiple fields.
article
Knowledge base article.
Message Status
sent
Message has been sent.
delivered
Message has been delivered to recipient.
read
Message has been read by recipient.
failed
Message delivery failed.
Private Notes
Private notes are messages that are only visible to agents. They are useful for:
- Internal communication about conversations
- Recording important information
- Leaving notes for other team members
To create a private note, set private: true in the message payload.
Attachments
Messages can include attachments such as:
- Images (JPEG, PNG, GIF)
- Documents (PDF, DOC, DOCX)
- Audio files
- Video files
Upload Attachments
Use multipart/form-data to upload files:
curl -X POST https://app.chatwoot.com/api/v1/accounts/1/conversations/1/messages \
-H "api_access_token: YOUR_ACCESS_TOKEN" \
-F "content=Check out this document" \
-F "message_type=outgoing" \
-F "attachments[][email protected]" \
-F "attachments[][email protected]"
Error Responses
Message Not Found
{
"error": "Message not found"
}
Invalid Message Type
{
"error": "Invalid message type"
}
API Inbox Required
{
"error": "Message status update is only allowed for API inboxes"
}
Translation Failed
{
"error": "Translation service unavailable"
}
Content Attributes
The content_attributes field can contain additional metadata:
{
"content": "Message content",
"content_attributes": {
"items": [
{
"title": "Card Title",
"description": "Card description",
"actions": [
{
"text": "Button Text",
"uri": "https://example.com"
}
]
}
]
}
}
