Conversations API

Conversations are the unified inbox over the crm.activities timeline. One activity row exists per touchpoint (SMS, email, call, note), deduped by provider_message_id. All endpoints are org-scoped via X-Org-Id.

Caution

POST /conversations/{conversation_id}/messages can send real outbound SMS or email. Treat send endpoints as live actions and confirm intent before calling them.

Threads and messages

Method	Path	Description
GET	/conversations	List conversations. Supports ?scope=mine|team, ?archived=, and ?overdue=.
GET	/conversations/{conversation_id}	Get a thread.
GET	/conversations/{conversation_id}/messages	List messages in a thread (calls render inline with their AI summary).
POST	/conversations/{conversation_id}/messages	Send a message (SMS/email) in the thread.
POST	/conversations/media	Upload media for an outbound message.
POST	/contacts/{contact_id}/conversations	Open a conversation for a contact.

State actions

Method	Path	Description
POST	/conversations/{conversation_id}/star	Star a conversation.
DELETE	/conversations/{conversation_id}/star	Unstar.
POST	/conversations/{conversation_id}/read	Mark read.
POST	/conversations/{conversation_id}/unread	Mark unread.
POST	/conversations/{conversation_id}/assign	Assign to a staff member ({ "assigned_to": "<uuid>|null" }; 422 if not an org member).
POST	/conversations/{conversation_id}/archive	Archive / unarchive ({ "archived": true|false }).

Views and SLA

Method	Path	Description
GET	/conversations/views	List saved inbox views.
PUT	/conversations/views	Save inbox views (Unread / Recents / Starred / All are non-deletable).
GET	/conversations/views/counts	Per-view unread/total counts.
GET	/conversations/sla	Get the conversation SLA config.
GET	/conversations/overdue/count	Count of SLA-overdue threads.

Setter suggestions

When the AI setter is enabled in suggestive mode, it writes draft replies a human sends:

Method	Path	Description
POST	/conversations/{conversation_id}/suggestions/{activity_id}/send	Send a suggested draft (one-click).
POST	/conversations/{conversation_id}/suggestions/{activity_id}/dismiss	Dismiss a suggested draft.

When a human sends while a pending suggestion existed, the AI draft and the human-sent message are captured as one labelled training pair. See Setter.