All conversations

Every conversation of an agent, whatever the channel: website, hosted chat link, WhatsApp, Instagram, other integrations. Read only, with the permission conversations:read_all, plus, with livechat:read, the conversations currently handed to a person of your team.

2 min read Updated

All conversations of an agent

GET/v1/agents/{agent_id}/conversations

Permission conversations:read_all

Every channel (website, WhatsApp, API, ...), newest activity per session.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 20 characters.
start_datestringqueryFirst day, as YYYY-MM-DD (UTC).
end_datestringqueryLast day, inclusive, as YYYY-MM-DD (UTC).
channelstringqueryOnly conversations of this channel, e.g. website, whatsapp or api. Up to 64 characters.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].api_conversation_idstring or nullconv_... when the conversation came through the API.
data[].first_activitystring or nullFirst message, in UTC.
data[].last_activitystring or nullLast message, in UTC.
data[].message_countintegerMessages in the conversation, from every side.
data[].objectstringAlways agent_conversation. Always agent_conversation.
data[].referencestringUse it in GET /v1/agents/{agent_id}/conversations/{reference}/messages.
data[].visitor_messagesintegerMessages written by the visitor.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "data": [
    {
      "api_conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
      "first_activity": "2026-11-10T16:30:45.081227",
      "last_activity": "2026-11-10T16:30:48.673890",
      "message_count": 6,
      "object": "agent_conversation",
      "reference": "conv_2346",
      "visitor_messages": 3
    }
  ],
  "next_cursor": null,
  "object": "list"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

History of any conversation

GET/v1/agents/{agent_id}/conversations/{reference}/messages

Permission conversations:read_all

reference from the list above.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
referencerequiredstringpathThe reference of a conversation from the list above.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 20 characters.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].contentstringThe message text, at most 16000 characters.
data[].content_truncatedbooleantrue: the message is longer than 16000 characters and content is cut. Default false.
data[].idintegerMessage id.
data[].platformstring or nullThe channel: website, whatsapp, api, ...
data[].timestampstring or nullWhen the message was written, in UTC.
data[].typestringuser_input (the end user), assistant (the agent) or agent (a person of the business).
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations/conv_2346/messages" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "data": [
    {
      "content": "When is the farm shop open on Saturday?",
      "content_truncated": false,
      "id": 2346,
      "platform": "api",
      "timestamp": "2026-11-10T16:30:45.081227",
      "type": "user_input"
    },
    {
      "content": "Hello Anna, the farm shop is open on Saturdays from 9 to 14.",
      "content_truncated": false,
      "id": 2347,
      "platform": "api",
      "timestamp": "2026-11-10T16:30:46.637930",
      "type": "assistant"
    }
  ],
  "next_cursor": null,
  "object": "list"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Open handoffs

GET/v1/agents/{agent_id}/live-sessions

Permission livechat:read

Conversations waiting for or handled by a person of the business. Answering from your own tool comes in v1.1; staff replies arrive as handoff.message webhooks.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 200 characters.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].agent_display_namestring or nullName of the person who took over. null while the visitor waits.
data[].agent_requested_atstring or nullWhen the visitor asked for a person, in UTC.
data[].created_atstring or nullWhen the conversation started, in UTC.
data[].last_activitystring or nullLast message, in UTC.
data[].session_idstringSession id of the conversation.
data[].statusstringagent_requested (waiting for a person) or agent_joined.
data[].visitor_namestring or nullThe name the visitor gave, if any.
data[].bot_idstringThe agent's id (older field name, same value as the path's agent_id).
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/live-sessions" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "data": [
    {
      "agent_display_name": null,
      "agent_requested_at": "2026-11-10T16:31:02.114",
      "bot_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
      "created_at": "2026-11-10T16:30:45.081",
      "last_activity": "2026-11-10T16:31:02.114",
      "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
      "status": "agent_requested",
      "visitor_name": "Anna"
    }
  ],
  "next_cursor": null,
  "object": "list"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Next steps