Create a conversation
POST/conversations
Open a conversation in an inbox.
inbox_id is enough on its own — the channel type is read from the inbox, so
you never have to keep the two in sync. Get the ids from GET /v1/inboxes.
Identify the contact either by contact_id, or by a contact object carrying a
phone or an email. The second form is what an integration usually wants: an
unknown phone number creates the contact rather than failing.
Pass a message object to send the first message in the same call — the same
body POST /v1/conversations/{id}/messages takes, including
{"type": "template", …} for WhatsApp. The created message comes back under
initial_message.
Which inboxes can start a conversation? Live chat, the API inbox, Instagram DM, Facebook Messenger and TikTok are inbound-only: the customer must write first, because there is no way to address them until they do.
Request
Responses
- 201
- 400
- 401
- 402
- 403
- 409
Conversation created.
Response Headers
Correlation id for this request. Quote it when reporting a problem.
The request was malformed, or a parameter was rejected.
Response Headers
Correlation id for this request. Quote it when reporting a problem.
No token, an expired token, or a credential that has been revoked.
Response Headers
Correlation id for this request. Quote it when reporting a problem.
A plan ceiling or a locked feature stopped an otherwise valid request.
Response Headers
Correlation id for this request. Quote it when reporting a problem.
Refused. Either the credential does not hold the scope this endpoint needs (code: insufficient_scope), or the account's IP allow-list does not include the calling address (code: ip_not_allowed).
Response Headers
Correlation id for this request. Quote it when reporting a problem.
The request was valid but conflicts with the current state.
Response Headers
Correlation id for this request. Quote it when reporting a problem.