# Conversations and messages

> Conversation status, assignment and lifecycle; message channels, direction and threading; notes and drafts.

Source: https://developer.kustomer.com/docs/concepts/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.

```mermaid
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

_Interactive state machine of conversation status with three states: open, snoozed and done. A new conversation starts as open when created or when a customer message arrives, and can also be created as done through the API. An agent snoozing moves open to snoozed; the snooze ending or the customer replying moves it back to open; marking it done moves open to done; and a customer reply reopens a done conversation. Alongside, a timeline of inbound and outbound messages with their channels shows how messageCount, outboundMessageCount, channels, lastMessageIn and the snooze status and time change with each event._

| 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](https://developer.kustomer.com/api/core-resources/get-snoozes). |
| `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**

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` ([reference](https://developer.kustomer.com/api/core-resources/create-conversation-for-customer))

`PUT /v1/conversations/{id}` ([reference](https://developer.kustomer.com/api/core-resources/update-conversation))

`POST /v1/conversations/{id}/tags` ([reference](https://developer.kustomer.com/api/core-resources/append-tags-to-conversation))

## Messages

**Message**

### Two ways to create a message

**Into an existing conversation**

`POST /v1/conversations/{id}/messages` ([reference](https://developer.kustomer.com/api/core-resources/create-message-from-conversation))

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

**Through the customer**

`POST /v1/customers/{id}/messages` ([reference](https://developer.kustomer.com/api/core-resources/create-message-by-customer-id))

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

```json title="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"
}
```

> **Messages created by the API don't send anything:** Creating a message records it on the timeline. An outbound message created through the API is **not** delivered to the customer by Kustomer's email, SMS or chat channels. It's a record of something your system sent. To let agents reply through your channel, see [Bring messages from a custom channel](https://developer.kustomer.com/docs/guides/custom-channel-messages).

## 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` ([reference](https://developer.kustomer.com/api/core-resources/create-note-within-conversation))

```json title="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` ([reference](https://developer.kustomer.com/api/core-resources/create-draft-for-customer))

## 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](https://developer.kustomer.com/docs/concepts/rate-limits) for the full picture.