DeskAPI reference

Conversations

Updated 2026-11-12

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
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations?filter=waiting" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
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
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()
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 #

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
curl "$AILO_BASE_URL/api/tenants/demo-shop/conversations/c_8f21/snapshot" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
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 #

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.
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"
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 #

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
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"}}'
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
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"},
    },
)
200 response
{ "ok": true, "version": 14, "event_ids": ["e_33"] }