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

NameTypeRequiredDescription
organization_idintegerYesYour organization ID.
contact_idintegerYesContact of the thread.
channelstringYesplayground for AI testing. Other values: whatsapp, instagram, messenger, webchat, sms.
assigned_ai_assistant_idintegerNoAI assistant that answers the thread. Must belong to the organization.
assigned_user_idintegerNoHuman owner. Must be a member of the organization.
meta_contact_first_namestringNoContact first name shown in the inbox and used by search.
meta_contact_last_namestringNoContact last name.
meta_contact_avatar_urlstring | nullNoContact avatar URL.
pipeline_id / pipeline_stage_idintegerNoPlace the thread in a conversation pipeline.
statusstringNoopen (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_phone and our_phone_number already 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

StatusWhen
400 Bad RequestA 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.