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.

4 min read Updated

List conversations

GET/v1/conversations

Permission chat:write

Conversations of this integration, newest first.

Parameters

ParameterTypeDescription
agent_idstringqueryOnly conversations of this agent. Up to 200 characters.
external_idstringqueryOnly the conversation with this external_id of yours. Up to 200 characters.
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_idstringThe agent's id.
data[].auto_responsebooleanfalse: the agent is muted in this conversation and stays silent.
data[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].external_idstring or nullYour own id of the conversation, null if it has none.
data[].idstringConversation id (conv_...).
data[].last_activity_atstring or nullLast message, in UTC.
data[].metadataobjectKey-value data stored with conversation_metadata.
data[].objectstringAlways conversation.
data[].typestringdirect (one person) or group (several people in one channel). One of direct, group.
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/conversations" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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}

Permission chat:write

Parameters

ParameterTypeDescription
conversation_idrequiredstringpathConversation id (conv_...).

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
auto_responsebooleanfalse: the agent is muted in this conversation and stays silent.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
external_idstring or nullYour own id of the conversation, null if it has none.
idstringConversation id (conv_...).
last_activity_atstring or nullLast message, in UTC.
metadataobjectKey-value data stored with conversation_metadata.
objectstringAlways conversation.
typestringdirect (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"

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

Permission chat:write

The stored messages, oldest first: the end users' messages, the agent's answers and replies of the business's team (role staff).

Parameters

ParameterTypeDescription
conversation_idrequiredstringpathConversation id (conv_...).
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[].contentstringThe text.
data[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].end_userobject or nullWho wrote it (id, name), on messages with the role user.
data[].idstringMessage id (msg_...).
data[].metadataobjectThe metadata sent with the message. Default {}.
data[].objectstringAlways message.
data[].rolestringuser (your end user), assistant (the agent) or staff (a person of the business during a handoff). One of user, assistant, staff.
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/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH/messages" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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

Permission chat:writeNeeds an integration with read and change access

Mute the agent in one conversation (or switch it back on).

Parameters

ParameterTypeDescription
conversation_idrequiredstringpathConversation id (conv_...).

Request body

FieldTypeDescription
enabledrequiredbooleanfalse: messages are stored, the agent stays silent (no credits).

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
auto_responsebooleanfalse: the agent is muted in this conversation and stays silent.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
external_idstring or nullYour own id of the conversation, null if it has none.
idstringConversation id (conv_...).
last_activity_atstring or nullLast message, in UTC.
metadataobjectKey-value data stored with conversation_metadata.
objectstringAlways conversation.
typestringdirect (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
}'

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}

Permission chat:writeNeeds an integration with read and change access

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

ParameterTypeDescription
conversation_idrequiredstringpathConversation id (conv_...).

Response 200 OK

FieldTypeDescription
deletedbooleantrue: it is deleted.
idstringId of the deleted object.
objectstringType of the deleted object.

Example request

curl -X DELETE "https://api.ultimo-bots.com/v1/conversations/conv_8TFivGiB5wHJqdt7FfRZkFYH" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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.

Next steps