Conversations and messages

A conversation is a thread of communication with one customer. It holds the workflow state agents care about: status, priority, assignment, queue, tags and SLA. A message is one communication inside it: an email, a chat line, an SMS, a call, or a message from your own system.

Diagram source

flowchart LR
  C[Customer] --> CV1[Conversation<br/>status: open]
  C --> CV2[Conversation<br/>status: done]
  CV1 --> M1[Message<br/>in · email]
  CV1 --> M2[Message<br/>out · email]
  CV1 --> N1[Note<br/>internal]
  CV1 --> D1[Draft<br/>unsent]
  CV2 --> M3[Message<br/>in · chat]

Conversation lifecycle

InteractiveConversation status, event by event

createdcreated as doneagent snoozessnooze ends or customer repliesmarked donecustomer replies

No conversation yet. A customer message creates one as open; through the API you can also create it as done.

Events

Last event

waiting for the first event…

Conversation changed by the last event

status—

snooze.status—

snooze.time—

messageCount0

outboundMessageCount0

channels[]

lastMessageIn.sentAt—

Timeline

No messages yet.

One conversation, simulated. Status moves only on the documented events. Counters and timestamps are read-only and come back in responses. The snooze fields are shown while a snooze is scheduled and at the moment it elapses. Orgs can also add sub-statuses (subStatus) inside each status.

Status	Meaning
`open`	Needs attention. Counts toward queues and SLAs.
`snoozed`	Parked until a time or event. Set with `status: "snoozed"` and a `snooze` object, using an option from your org's snooze settings.
`done`	Resolved. A new inbound message usually reopens it.

New conversations can be created as open or done. Orgs can also define sub-statuses (subStatus) to add detail inside a status, such as "Waiting on warehouse".

Key conversation attributes

Conversation

customerstringrequired: ID of the customer. Set on create; it can't be blank.
namestring: Subject line shown to agents.
statusstring: open, snoozed or done.
priorityinteger: 1 (lowest) to 5 (highest).
directionstring: in if the customer started it, out if your team did.
assignedUsersstring[]: User IDs. Up to 10.
assignedTeamsstring[]: Team IDs. Up to 10.
queueobject: The routing queue, for orgs using queues and routing.
tagsstring[]: Tags. Sending tags sets the whole list; the append and remove endpoints change one tag at a time and accept tag names, creating tags that don't exist yet.
customobject: Custom attributes.
externalIdstring: Your ID for the thread, up to 256 characters.

Read-only counters and timestamps come back in responses: messageCount, noteCount, outboundMessageCount, firstResponse, lastMessageIn, sla, satisfaction and channels (every channel used in the thread).

post/v1/customers/{id}/conversations put/v1/conversations/{id} post/v1/conversations/{id}/tags

Messages

Message

channelstringrequired: email, sms, chat, facebook, twitter-dm, twitter-tweet, voice, instagram or whatsapp.
appstringrequired: Identifies the integration that produced the message, for example acme-messenger. Use a stable value per integration.
directionstring: in from the customer, out to the customer.
previewstring: The message text, up to 10,240 characters.
subjectstring: Subject, for channels that have one. Up to 256 characters.
conversationstring: Conversation ID. If you omit it when creating through a customer, Kustomer creates a new conversation.
metaobject: Channel-specific details, such as from and to for email.
sentAtdate-time: When the message was sent in the source system.
externalIdstring: Your ID for the message, up to 256 characters. Lets you look it up later.
attachmentsobject[]: Attachments created with the attachments API.
importedAtdate-time: Marks a historical import and skips the per-customer create limit.

Two ways to create a message

post/v1/conversations/{id}/messages

Use this when you already track the conversation, for example because you stored its ID or externalId.

post/v1/customers/{id}/messages

Pass conversation to thread the message into an existing conversation. Leave it out and Kustomer creates a new conversation for the message.

Request body

{
  "channel": "chat",
  "app": "acme-messenger",
  "direction": "in",
  "preview": "Can I change the delivery address on order #4417?",
  "externalId": "msg_01HF3Q8Y2V",
  "sentAt": "2026-10-21T14:02:11Z"
}

Notes

Notes are internal comments on a conversation. Customers never see them. They support @mentions of users or teams through userMentions (up to 20), and attachments.

post/v1/conversations/{id}/notes

Request body

{
  "body": "Warehouse confirmed the replacement shipped today.",
  "userMentions": [{ "user": "58190b991f2932100010d683" }]
}

Drafts

Drafts are outbound messages that haven't been sent. Integrations use them to prepare replies, such as an AI-suggested answer, for an agent to review and send.

post/v1/customers/{id}/drafts

Rate limits that apply

A single client can create up to 120 messages, conversations, notes, drafts or custom objects per customer per minute. Records with importedAt are exempt.
A conversation or message can be updated 100 times in 10 minutes.

See Rate limits for the full picture.