> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaisupport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read and assign conversations

> Show a contact's threads in your own system, and route a conversation to a teammate.

This guide reads the conversations of one contact, and assigns a
conversation to a teammate. Use it to show a "Conversations" panel on a
customer page in your CRM, or to route work from your own rules.

Reading needs the `conversations:read` permission. Assignment needs
`conversations:write`.

## Read the conversations of a contact

```bash theme={null}
curl "https://kaisupport.com/api/v1/contacts/4f1d6f2a-.../conversations?status=open" \
  -H "Authorization: Bearer $KAI_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "9d2b1c44-...",
      "channel_id": "7c1f4a80-...",
      "status": "human",
      "assigned_member_id": "2c9a0d51-...",
      "assigned_via": "member",
      "last_message_preview": "Yarın 14:00 uygun mu?",
      "last_message_at": "2026-08-11T10:44:12.000Z",
      "created_at": "2026-08-09T08:15:00.000Z"
    }
  ]
}
```

The list is newest first. `status=open` returns the live threads. `closed`
and `archived` return those states. Omit the parameter for all of them.

A conversation holds one of five states:

| `status` | Meaning |
| - | - |
| `open` | The thread is live. Neither Kai nor a person answered it yet. |
| `ai` | Kai answered this thread. |
| `human` | A person holds this thread, or the thread waits for a person. |
| `closed` | The thread rests. A new message from the customer opens it again. |
| `archived` | The thread is history. A new message from the customer starts a new thread. |

`open`, `ai` and `human` are the live states. The `status=open` filter
returns all three.

`assigned_via` tells you who made the current assignment. `member` is a
person in Kai. `api` is a call to this API. `null` is Kai's own routing.

<Note>
  Read the list with `status=open` before your send button fires. When a
  live thread exists and a teammate holds it, a template from your system
  can arrive in the middle of their conversation.
</Note>

## Assign a conversation

```bash theme={null}
curl -X PUT https://kaisupport.com/api/v1/conversations/9d2b1c44-.../assignee \
  -H "Authorization: Bearer $KAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member": "baran@example.com" }'
```

The response is the updated conversation, with `assigned_via` set to `api`.

Kai does not answer on an assigned conversation. The thread appears in the
inbox of the teammate, and Kai invites them to the Matrix room of the
thread.

<Warning>
  This call moves a conversation that another teammate already holds. Read
  `assigned_member_id` first when that matters for your flow.
</Warning>

## Release a conversation

```bash theme={null}
curl -X DELETE https://kaisupport.com/api/v1/conversations/9d2b1c44-.../assignee \
  -H "Authorization: Bearer $KAI_API_KEY"
```

The conversation returns to the shared queue. Kai's own routing does not
pick it up again: a released thread waits for a person.

## Assignment and account owners

This endpoint moves one conversation. It does not change the account owner
of the contact. To route the future conversations of a customer to one
teammate, set the account owner instead. See
[Sync account owners](/guides/assignments).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.