Conversations
The conversations your integration started with POST /v1/responses, under Ultimo's id (conv_...) or your own external_id. Conversations of other channels are under All conversations.
- GET
/v1/conversationsList conversations - GET
/v1/conversations/{conversation_id}Get a conversation - GET
/v1/conversations/{conversation_id}/messagesConversation history - PUT
/v1/conversations/{conversation_id}/auto-responseSwitch answers on or off - DELETE
/v1/conversations/{conversation_id}Delete a conversation
List conversations
GET/v1/conversations
Conversations of this integration, newest first.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_id | stringquery | Only conversations of this agent. Up to 200 characters. |
external_id | stringquery | Only the conversation with this external_id of yours. Up to 200 characters. |
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_id | string | The agent's id. |
data[].auto_response | boolean | false: the agent is muted in this conversation and stays silent. |
data[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].external_id | string or null | Your own id of the conversation, null if it has none. |
data[].id | string | Conversation id (conv_...). |
data[].last_activity_at | string or null | Last message, in UTC. |
data[].metadata | object | Key-value data stored with conversation_metadata. |
data[].object | string | Always conversation. |
data[].type | string | direct (one person) or group (several people in one channel). One of direct, group. |
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/conversations" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/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/conversations", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"data": [
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"auto_response": true,
"created_at": "2026-11-10T16:30:45Z",
"external_id": "ticket-4711",
"id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"last_activity_at": "2026-11-10T16:30:47Z",
"metadata": {
"team": "support"
},
"object": "conversation",
"type": "direct"
}
],
"next_cursor": null,
"object": "list"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Get a conversation
GET/v1/conversations/{conversation_id}
Parameters
| Parameter | Type | Description |
|---|---|---|
conversation_idrequired | stringpath | Conversation id (conv_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
auto_response | boolean | false: the agent is muted in this conversation and stays silent. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
external_id | string or null | Your own id of the conversation, null if it has none. |
id | string | Conversation id (conv_...). |
last_activity_at | string or null | Last message, in UTC. |
metadata | object | Key-value data stored with conversation_metadata. |
object | string | Always conversation. |
type | string | direct (one person) or group (several people in one channel). One of direct, group. |
Example request
curl "https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH",
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/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"auto_response": true,
"created_at": "2026-11-10T16:30:45Z",
"external_id": "ticket-4711",
"id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"last_activity_at": "2026-11-10T16:30:47Z",
"metadata": {
"team": "support"
},
"object": "conversation",
"type": "direct"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Conversation history
GET/v1/conversations/{conversation_id}/messages
The stored messages, oldest first: the end users' messages, the agent's answers and replies of the business's team (role staff).
Parameters
| Parameter | Type | Description |
|---|---|---|
conversation_idrequired | stringpath | Conversation id (conv_...). |
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[].content | string | The text. |
data[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].end_user | object or null | Who wrote it (id, name), on messages with the role user. |
data[].id | string | Message id (msg_...). |
data[].metadata | object | The metadata sent with the message. Default {}. |
data[].object | string | Always message. |
data[].role | string | user (your end user), assistant (the agent) or staff (a person of the business during a handoff). One of user, assistant, staff. |
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/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/messages" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/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/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/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?",
"created_at": "2026-11-10T16:30:45Z",
"end_user": {
"id": "u-17",
"name": "Anna"
},
"id": "msg_0000000000002346",
"metadata": {
"ticket": "4711"
},
"object": "message",
"role": "user"
},
{
"content": "Hello Anna, the farm shop is open on Saturdays from 9 to 14.",
"created_at": "2026-11-10T16:30:47Z",
"end_user": null,
"id": "msg_0000000000002347",
"metadata": {},
"object": "message",
"role": "assistant"
}
],
"next_cursor": null,
"object": "list"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Switch answers on or off
PUT/v1/conversations/{conversation_id}/auto-response
Mute the agent in one conversation (or switch it back on).
Parameters
| Parameter | Type | Description |
|---|---|---|
conversation_idrequired | stringpath | Conversation id (conv_...). |
Request body
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean | false: messages are stored, the agent stays silent (no credits). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
auto_response | boolean | false: the agent is muted in this conversation and stays silent. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
external_id | string or null | Your own id of the conversation, null if it has none. |
id | string | Conversation id (conv_...). |
last_activity_at | string or null | Last message, in UTC. |
metadata | object | Key-value data stored with conversation_metadata. |
object | string | Always conversation. |
type | string | direct (one person) or group (several people in one channel). One of direct, group. |
Example request
curl -X PUT "https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/auto-response" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'import os, requests
r = requests.put(
"https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/auto-response",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
json={
"enabled": False,
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/auto-response", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"enabled": false
})
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"auto_response": false,
"created_at": "2026-11-10T16:30:45Z",
"external_id": "ticket-4711",
"id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"last_activity_at": "2026-11-10T16:30:47Z",
"metadata": {
"team": "support"
},
"object": "conversation",
"type": "direct"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Delete a conversation
DELETE/v1/conversations/{conversation_id}
Deletes the conversation and everything stored for it: the history with its authors, the stored requests and answers of POST /v1/responses, and the webhook events that carry its content. A request that is still waiting or running for it ends failed with code conversation_deleted. Leads are their own records: delete them with DELETE /v1/agents/{agent_id}/leads/{lead_id}. Use it for a new topic or a deletion request.
Parameters
| Parameter | Type | Description |
|---|---|---|
conversation_idrequired | stringpath | Conversation id (conv_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
deleted | boolean | true: it is deleted. |
id | string | Id of the deleted object. |
object | string | Type of the deleted object. |
Example request
curl -X DELETE "https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.delete(
"https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH",
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/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"deleted": true,
"id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"object": "conversation"
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.