DeskAPI reference
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. IDs and content in the examples are made up.
List conversations #
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.
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations?filter=waiting" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
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();
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()
{
"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 #
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.
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/snapshot" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
{
"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 #
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: heartbeatis sent every 25 seconds, with noid.event: typingis sent while the serving teammate is typing, with noid.- If the version you send is ahead of the conversation, you get one
event: resetand the stream closes; read the snapshot again.
curl -N "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/events" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Last-Event-ID: 12"
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 #
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 |
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.
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"}}'
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' },
}),
},
);
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"},
},
)
{ "ok": true, "version": 14, "event_ids": ["e_33"] }