Conversation Events
conversation.created and conversation.updated - the inbox row above the channel threads
A conversation is the inbox row for a contact; a chat is one channel thread inside it. Conversation events fire on the row, not on the threads.
Subscribe with CONVERSATION_CREATED, CONVERSATION_UPDATED.
Today a conversation holds exactly one thread, so these events are close to redundant with chat events. They become the useful level once a conversation can span several channels - then one conversation row covers a contact's WhatsApp and Telegram threads together, and only these events describe it.
conversation.created
type: conversation.created
A new conversation row was created.
data
type Data = { conversation: ConversationPayload };See ConversationPayload.
Example
{
"id": "evt_b4c5d6e7-f809-1223-3445-566778899001",
"type": "conversation.created",
"timestamp": "2026-09-30T17:59:58.000Z",
"data": {
"conversation": {
"id": "6804f4d5a6f9f35f6e66f1c4",
"contactId": "6804f4d5a6f9f35f6e66f1a2",
"createdAt": "2026-09-30T17:59:58.000Z",
"updatedAt": "2026-09-30T17:59:58.000Z"
}
},
"meta": {
"eventId": "evt_b4c5d6e7-f809-1223-3445-566778899001",
"event": "conversation.created",
"occurredAt": "2026-09-30T17:59:58.000Z",
"organisationId": "6716b2f0a1c34d0012ab89ef",
"externalId": "crmco-client-5541",
"partnerId": "6716b1001c34d0012ab89abc",
"apiVersion": "2026-04-01",
"attempt": 1
}
}conversation.updated
type: conversation.updated
The conversation row changed - new activity, a status change, a rollup recalculation.
data
type Data = {
conversation: ConversationPayload;
previous?: Partial<ConversationPayload>;
};Example
{
"id": "evt_c5d6e7f8-0912-2334-4556-677889900112",
"type": "conversation.updated",
"timestamp": "2026-09-30T18:00:00.000Z",
"data": {
"conversation": {
"id": "6804f4d5a6f9f35f6e66f1c4",
"contactId": "6804f4d5a6f9f35f6e66f1a2",
"createdAt": "2026-09-30T17:59:58.000Z",
"updatedAt": "2026-09-30T18:00:00.000Z"
}
},
"meta": {
"eventId": "evt_c5d6e7f8-0912-2334-4556-677889900112",
"event": "conversation.updated",
"occurredAt": "2026-09-30T18:00:00.000Z",
"organisationId": "6716b2f0a1c34d0012ab89ef",
"externalId": "crmco-client-5541",
"partnerId": "6716b1001c34d0012ab89abc",
"apiVersion": "2026-04-01",
"attempt": 1
}
}The payload is deliberately lean, and channels and primaryThreadChatId appear only when the emitting code already had them at hand. Do not treat their absence as "no channels". When you need the current threads for certain, read searchConversations.
Chats or Conversations?
| You want to… | Subscribe to |
|---|---|
| Mirror messages and reply | message events - the chat payload comes with them |
| React to thread-level changes (archive, rename, identity) | chat events |
| Track the inbox row a contact occupies, across channels | conversation events |
Subscribing to all three is fine, but expect overlap: one inbound message can produce message.inbound.created, chat.updated, and conversation.updated. Deduplicate on id and reconcile by timestamp, never by arrival order.