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.
- GET
/v1/agents/{agent_id}/conversationsAll conversations of an agent - GET
/v1/agents/{agent_id}/conversations/{reference}/messagesHistory of any conversation - GET
/v1/agents/{agent_id}/live-sessionsOpen handoffs
All conversations of an agent
GET/v1/agents/{agent_id}/conversations
Every channel (website, WhatsApp, API, ...), newest activity per session.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 20 characters. |
start_date | stringquery | First day, as YYYY-MM-DD (UTC). |
end_date | stringquery | Last day, inclusive, as YYYY-MM-DD (UTC). |
channel | stringquery | Only conversations of this channel, e.g. website, whatsapp or api. Up to 64 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].api_conversation_id | string or null | conv_... when the conversation came through the API. |
data[].first_activity | string or null | First message, in UTC. |
data[].last_activity | string or null | Last message, in UTC. |
data[].message_count | integer | Messages in the conversation, from every side. |
data[].object | string | Always agent_conversation. Always agent_conversation. |
data[].reference | string | Use it in GET /v1/agents/{agent_id}/conversations/{reference}/messages. |
data[].visitor_messages | integer | Messages written by the visitor. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
reference from the list above.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
referencerequired | stringpath | The reference of a conversation from the list above. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 20 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].content | string | The message text, at most 16000 characters. |
data[].content_truncated | boolean | true: the message is longer than 16000 characters and content is cut. Default false. |
data[].id | integer | Message id. |
data[].platform | string or null | The channel: website, whatsapp, api, ... |
data[].timestamp | string or null | When the message was written, in UTC. |
data[].type | string | user_input (the end user), assistant (the agent) or agent (a person of the business). |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always 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"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations/conv_2346/messages",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/conversations/conv_2346/messages", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
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
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 200 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].agent_display_name | string or null | Name of the person who took over. null while the visitor waits. |
data[].agent_requested_at | string or null | When the visitor asked for a person, in UTC. |
data[].created_at | string or null | When the conversation started, in UTC. |
data[].last_activity | string or null | Last message, in UTC. |
data[].session_id | string | Session id of the conversation. |
data[].status | string | agent_requested (waiting for a person) or agent_joined. |
data[].visitor_name | string or null | The name the visitor gave, if any. |
data[].bot_id | string | The agent's id (older field name, same value as the path's agent_id). |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/live-sessions" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/live-sessions",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/live-sessions", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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.