Create a conversation
Create a conversation record. Use it for AI assistant playground threads (test an assistant through the API). To write to a contact on WhatsApp use Start a WhatsApp conversation instead: it picks the WhatsApp number and fills the channel identifiers for you.
Endpoint
POST/conversations
Body
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | Yes | Your organization ID. |
contact_id | integer | Yes | Contact of the thread. |
channel | string | Yes | playground for AI testing. Other values: whatsapp, instagram, messenger, webchat, sms. |
assigned_ai_assistant_id | integer | No | AI assistant that answers the thread. Must belong to the organization. |
assigned_user_id | integer | No | Human owner. Must be a member of the organization. |
meta_contact_first_name | string | No | Contact first name shown in the inbox and used by search. |
meta_contact_last_name | string | No | Contact last name. |
meta_contact_avatar_url | string | null | No | Contact avatar URL. |
pipeline_id / pipeline_stage_id | integer | No | Place the thread in a conversation pipeline. |
status | string | No | open (default) or closed. |
Any other writable conversation field is accepted. meta_contact_tags is always copied from the contact.
Request
Then send a message as the contact with POST/conversation-messages-playground (see Send a message) and the assistant replies in the same thread.
Response
json
Behavior
- Duplicates: for SMS, when a conversation with the same
contact_phoneandour_phone_numberalready exists, that conversation is updated with the body and returned instead of creating a new one. The same applies to WhatsApp and Instagram when the channel identifiers match. - Creating a conversation can start automations with a "conversation created" trigger.
Errors
| Status | When |
|---|---|
400 Bad Request | A required field is missing, channel is not one of the allowed values, or assigned_user_id / assigned_ai_assistant_id does not belong to the organization. |
Report an issue with this documentation
Please log in to report issues with our documentation.