# The live chat inbox

> Read conversations, take them over from the AI agent, reply, hand back, and organise them through the API.

- Canonical page: https://synconone.com/docs/api-live-chat
- Section: Developers
- Updated: 2026-10-22

Everything a teammate does in the live chat inbox can be done through the API: read the queue and a conversation, take it over from the AI agent, reply to the visitor, hand it back, and organise it. It uses the same rules as the inbox in the app.

> **Replies reach real people** A reply is read by a visitor at once and cannot be unsent. Replies are made as the person the key stands for (its creator, or the teammate it acts as), so the visitor sees that person's name. Keys need the `conversations:write` scope and a role that can write in the inbox, and are limited to 30 replies a minute.

## Read the queue and a thread

```bash
# the queue (conversations:read)
curl "https://synconone.com/api/v1/conversations?view=needs_person&limit=25" -H "Authorization: Bearer $KEY"

# one conversation: who is answering, and whether you may reply
curl https://synconone.com/api/v1/conversations/conv_… -H "Authorization: Bearer $KEY"

# its thread, oldest first; pass the last cursor as "after" to follow it live
curl "https://synconone.com/api/v1/conversations/conv_…/messages?after=0" -H "Authorization: Bearer $KEY"
```

`responder` is `ai` while the agent is answering and `human` once a teammate has taken over. Reading never marks a conversation read. Messages carry a `role` of `visitor`, `agent`, `human` or `system` (a join, a hand-back, a booking).

## Take over and reply

1. `POST /conversations/{id}/join`. The visitor sees a teammate arrive. If another teammate already has it, you get `409`.
2. `POST /conversations/{id}/reply` with `{ "text": "…" }`. Replying before joining is a `409`.

```bash
curl -X POST https://synconone.com/api/v1/conversations/conv_…/reply -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Yes, we ship to Perth.", "client_message_id": "case-88-reply-1"}'
```

Send your own `client_message_id` so a retry after a dropped connection posts the message once, not twice.

## Hand back to the AI agent

`POST /conversations/{id}/return-to-ai` returns the conversation to the agent. Only the teammate who holds it can.

## Owner, priority, tags and notes

- `PATCH /conversations/{id}` sets `assignee` (a teammate from `GET /team/members`, or `null`), `priority`, and `add_tags` / `remove_tags`.
- `POST /conversations/{id}/notes` adds a note only your team sees; the visitor never does. `GET` lists them.
- There is no separate close. A conversation is resolved by resolving its ticket, with `PATCH /tickets/{number}`.

See the [inbox reference](https://synconone.com/docs/api-reference/inbox) for every field.