# Conversations

List conversations, read one, subscribe to its new events, and write an internal note on it. The shared rules for authentication, rate limits and errors are in [Authentication and conventions](api-overview.md). IDs and content in the examples are made up.

## List conversations

::: endpoint GET /api/tenants/{tenant_id}/conversations
:::

Returns conversations by latest activity, newest first, 50 per page. Minimum role: Specialist.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | string | No | Defaults to `all`; values below |
| `from`, `to` | string | No | ISO times with a time zone, on latest activity; includes `from`, excludes `to` |
| `served_by` | string | No | IDs of members who served, comma-separated, up to 20; `ai` means Ailo |
| `channels` | string | No | `web`, `telegram`, comma-separated |
| `channel_ids` | string | No | Channel IDs, comma-separated, up to 50 |
| `outcome` | string | No | `done`, `answered`, `unresolved`, `not_needed`, comma-separated |
| `rating` | string | No | Customer rating: `1`, `2`, `3` or `unrated`, comma-separated |
| `cursor` | string | No | The `next_cursor` from the previous page |

| `filter` | Returns |
| --- | --- |
| `all` | Every conversation |
| `mine` | Ones you serve, and ones transferred to you and waiting for you |
| `queued` | Transfers in the queue that nobody has started serving |
| `waiting` | Conversations waiting for the team |
| `needs_help` | Follow-ups: a transfer that didn't go through and needs a later reply from the team |
| `needs_support` | Conversations that need support |
| `ailo` | Ones Ailo is serving with no transfer request |
| `specialist` | Ones a specialist is serving |
| `ended` | Resolved or closed |

Returns `rows`, `has_more`, `next_cursor` and `total`. `total` is given only on the first page and is `null` on later ones. The main fields of each row:

| Field | Description |
| --- | --- |
| `conversation_id` | Conversation ID |
| `site_id`, `channel`, `channel_id` | Site and channel |
| `lifecycle` | `open` ongoing, `inactive`, `resolved` or `closed` |
| `owner`, `owner_agent_id` | Who serves: `ai` is Ailo; with `human`, `owner_agent_id` is the member |
| `handoff_state`, `assigned_agent_id` | Transfer state and who it went to |
| `waiting_since` | When the customer started waiting for the team; `null` when not waiting |
| `last_activity_at` | Latest activity |
| `last_message_preview` | Preview of the last message |
| `locale` | Conversation language |

There are more fields; `/api/openapi.json` and the actual response are the reference.

:::: example
::: code-group
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations?filter=waiting" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```
```js [JavaScript]
const res = await fetch(
  `${process.env.AILO_BASE_URL}/api/tenants/demo-shop/conversations?filter=waiting`,
  { headers: { Authorization: `Bearer ${process.env.AILO_ACCESS_KEY}` } },
);
const page = await res.json();
```
```python [Python]
import os, requests

page = requests.get(
    f"{os.environ['AILO_BASE_URL']}/api/tenants/demo-shop/conversations",
    params={"filter": "waiting"},
    headers={"Authorization": f"Bearer {os.environ['AILO_ACCESS_KEY']}"},
).json()
```
:::

```json [200 response]
{
  "rows": [
    {
      "conversation_id": "c_8f21",
      "site_id": "site_th",
      "channel": "web",
      "lifecycle": "open",
      "owner": "ai",
      "owner_agent_id": null,
      "handoff_state": "queued",
      "waiting_since": "2026-11-12T09:30:00Z",
      "last_activity_at": "2026-11-12T09:31:04Z",
      "last_message_preview": "Can I talk to a person?",
      "locale": "en"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 1
}
```
::::

## Read a conversation

::: endpoint GET /api/tenants/{tenant_id}/conversations/{conversation_id}/snapshot
:::

Returns the conversation's public events so far, the ones the customer's side can see. Internal notes, assist ticket details, Ailo's reasoning and tool parameters are not included. Minimum role: Specialist.

| Field | Description |
| --- | --- |
| `as_of_version` | The version this snapshot is at; subscribe to events from here |
| `events` | Public events, oldest first |
| `ai_serving` | Whether Ailo is serving now |
| `rating` | The customer's rating |
| `server_time` | Server time |

Every event has `event_id`, `conversation_id`, `version`, `occurred_at` and `type`, plus fields such as `message`, `task` or `handoff` depending on its type. Common types:

| `type` | When |
| --- | --- |
| `message.posted` | A public message was posted |
| `message.recalled` | A message was recalled |
| `assist_task.created` / `accepted` / `working` / `completed` | An assist ticket's public progress |
| `human.requested` / `human.queued` / `human.accepted` | A team member was requested, queued, or started serving |
| `human.released` | A teammate transferred the conversation to Ailo |
| `conversation.closed` | The conversation ended |

A conversation that does not exist or belongs to another organization returns `404 not_found`.

:::: example
```bash [curl]
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/snapshot" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
```

```json [200 response (excerpt)]
{
  "as_of_version": 12,
  "ai_serving": true,
  "events": [
    {
      "schema_version": "1",
      "event_id": "e_31",
      "conversation_id": "c_8f21",
      "version": 12,
      "occurred_at": "2026-11-12T09:31:04Z",
      "type": "message.posted",
      "actor": { "kind": "customer" },
      "message": { "message_id": "m_77", "text": "Can I talk to a person?" }
    }
  ],
  "server_time": "2026-11-12T09:31:05Z"
}
```
::::

## Subscribe to new events

::: endpoint GET /api/tenants/{tenant_id}/conversations/{conversation_id}/events
:::

Streams the conversation's new public events as Server-Sent Events. Minimum role: Specialist.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `Last-Event-ID` | header | No | Start after this version; browsers send it on reconnect |
| `last_event_id` | integer | No | The same, as a query parameter; the header wins when both are sent |
| `follow` | string | No | `0` closes the stream after past events instead of waiting for new ones |

- Each event is three lines: `id:` is the version, `event:` the event type, `data:` the event as JSON.
- `event: heartbeat` is sent every 25 seconds, with no `id`.
- `event: typing` is sent while the serving teammate is typing, with no `id`.
- If the version you send is ahead of the conversation, you get one `event: reset` and the stream closes; read the snapshot again.

:::: example
```bash [curl]
curl -N "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/events" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Last-Event-ID: 12"
```

```text [Event stream]
retry: 3000
: connected

id: 13
event: assist_task.accepted
data: {"schema_version":"1","event_id":"e_32","conversation_id":"c_8f21","version":13,"type":"assist_task.accepted","occurred_at":"2026-11-12T09:33:10Z","task":{"public_status":"accepted"}}

event: heartbeat
data: {}
```
::::

## Write an internal note

::: endpoint POST /api/tenants/{tenant_id}/conversations/{conversation_id}/commands/post_note
:::

Writes a note on the conversation that only the team sees, or a note to Ailo. The customer never sees it. Minimum role: Specialist; read-only keys cannot call it.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `command_id` | string | Yes | 1–200 characters; see [Writes and retries](api-overview.md#writes-and-retries) |
| `idempotency_key` | string | Yes | 1–200 characters |
| `input.text` | string | Yes | The note, 1–4000 characters after trimming |
| `input.audience` | string | Yes | `team` for teammates, `ai` for Ailo |
| `input.task_id` | string | No | An assist ticket in this conversation; the note goes on that ticket |
| `input.expected_task_version` | integer | No | The ticket version you read; refused if the ticket changed since |

With `task_id` and `audience` set to `ai`, this is messaging Ailo on the ticket: a ticket still in the pool becomes claimed by you, and a ticket you hold moves to In progress. Who serves does not change either way.

| Status | `code` | When |
| --- | --- | --- |
| 403 | `permission_denied` | You lack the permission, or used a read-only key |
| 404 | `not_found` | The conversation does not exist or belongs to another organization |
| 409 | `not_found` | The ticket in `task_id` does not exist |
| 409 | `version_conflict` | The ticket version does not match `expected_task_version` |
| 409 | `idempotency_key_reused` | The same keys came with different content |

Returns `ok`, the conversation's new `version`, and the `event_ids` this produced.

:::: example
::: code-group
```bash [curl]
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/commands/post_note" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command_id": "3f1c9a2e-5b7d-4e8f-a1c2-d3e4f5a6b7c8",
       "idempotency_key": "3f1c9a2e-5b7d-4e8f-a1c2-d3e4f5a6b7c8",
       "input": {"text": "Same deposit came up last week.", "audience": "team"}}'
```
```js [JavaScript]
const id = crypto.randomUUID();
await fetch(
  `${process.env.AILO_BASE_URL}/api/tenants/demo-shop/conversations/c_8f21/commands/post_note`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AILO_ACCESS_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      command_id: id,
      idempotency_key: id,
      input: { text: 'Same deposit came up last week.', audience: 'team' },
    }),
  },
);
```
```python [Python]
import os, uuid, requests

key = str(uuid.uuid4())
requests.post(
    f"{os.environ['AILO_BASE_URL']}/api/tenants/demo-shop/conversations/c_8f21/commands/post_note",
    headers={"Authorization": f"Bearer {os.environ['AILO_ACCESS_KEY']}"},
    json={
        "command_id": key,
        "idempotency_key": key,
        "input": {"text": "Same deposit came up last week.", "audience": "team"},
    },
)
```
:::

```json [200 response]
{ "ok": true, "version": 14, "event_ids": ["e_33"] }
```
::::
