Responses

A response is one message to an agent and its answer. Send it as JSON and wait, as a stream of server-sent events, or async and fetch the result later. The guide Send messages explains the three modes and conversations step by step.

2 min read Updated

Send a message

POST/v1/responses

Permission chat:writeNeeds an integration with read and change access

Send one message to an agent and get its answer.

  • JSON (default): waits for the answer (up to 120 s).
  • "stream": true: server-sent events response.created, status, delta, products, choices, response.completed, error; JSON in every event; a heartbeat comment every 15 s.
  • "async": true: 202 at once; poll GET /v1/responses/{id} or receive the response.completed webhook.

Conversations: pass your external_id (created on first use), a conversation_id, or neither (a new conversation). With the same Idempotency-Key and body a retry returns the stored result for 24 hours without a second answer or charge.

Parameters

ParameterTypeDescription
Idempotency-KeystringheaderAny unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries.

Request body

FieldTypeDescription
agent_idrequiredstringAgent id from GET /v1/agents. Up to 200 characters.
inputrequiredstringThe message, at most 4000 characters.
asyncbooleanReturn 202 at once and poll GET /v1/responses/{id}. Default false.
contextstring or object or nullData from your system for this answer only (e.g. CRM fields). Never stored in the history.
conversation_idstring or nullContinue an existing conversation (conv_...). Up to 64 characters.
conversation_metadataobject or nullKey-value data stored on the conversation.
conversation_typestring or nulldirect (default) or group (several people in one channel). Set when the conversation is created. In a group conversation context is not accepted. One of direct, group.
end_userobject or nullWho wrote the message.
end_user.idstring or nullYour id of the person who wrote the message. No personal data in ids. Up to 200 characters.
end_user.namestring or nullDisplay name; the agent sees the message as "<name>: <text>". Up to 100 characters.
external_idstring or nullYour id of the conversation (channel, thread, ticket). Created on first use. Up to 200 characters.
formatstringAnswer as Markdown (default) or plain text. One of markdown, text. Default markdown.
includearray of stringsStructured extras: product cards and quick-reply choices. Off by default. One of products, choices.
metadataobject or nullKey-value data of this message, returned with the response.
streambooleanServer-sent events instead of one JSON response. Default false.

Response 200 OK ยท 202 Accepted

FieldTypeDescription
agent_idstringThe agent's id.
choicesarray or nullOnly with include=["choices"].
completed_atstring or nullWhen the answer was finished, in UTC.
conversation_idstring or nullThe conversation (conv_...). Send it, or your external_id, with the next message.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
end_userobject or nullThe end_user you sent.
errorobject or nulltype, code and message when the response failed, otherwise null.
external_idstring or nullYour id of the conversation, if you sent one.
handoffobjectWhether a person of the business was asked to take over.
handoff.requestedbooleanA person of the business has been asked to take over (or has taken over).
handoff.statusstring or nullagent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined.
idstringResponse id (resp_...).
input_message_idstring or nullId of the stored message you sent (msg_...).
metadataobjectThe metadata you sent. Default {}.
modestringHow it was sent: sync, stream or async. One of sync, stream, async.
objectstringAlways response.
outputobject or nullThe answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation.
output.formatstringmarkdown or text, as you asked. One of markdown, text.
output.languagestring or nullLanguage of the answer as an ISO code, when it was detected.
output.textstringThe answer.
output_message_idstring or nullId of the stored answer (msg_...).
productsarray of objects or nullOnly with include=["products"].
skipped_reasonstring or nullWhy there is no answer: human_handoff_active (a person has taken over) or auto_response_off (the agent is muted). One of human_handoff_active, auto_response_off.
statusstringqueued, in_progress, completed or failed. One of queued, in_progress, completed, failed.
usageobjectWhat the answer cost.
usage.creditsintegerAI credits booked for this answer. Default 0.

Example request

curl -X POST "https://api.ultimo-bots.com/v1/responses" \
  -H "Authorization: Bearer $ULTIMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "context": {
    "customer_tier": "gold",
    "last_order": "2026-10-28"
  },
  "end_user": {
    "id": "u-17",
    "name": "Anna"
  },
  "external_id": "ticket-4711",
  "input": "When is the farm shop open on Saturday?",
  "metadata": {
    "ticket": "4711"
  }
}'

Response 200 OK

{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "completed_at": "2026-11-10T16:30:47Z",
  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
  "created_at": "2026-11-10T16:30:45Z",
  "end_user": {
    "id": "u-17",
    "name": "Anna"
  },
  "error": null,
  "external_id": "ticket-4711",
  "handoff": {
    "requested": false,
    "status": null
  },
  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
  "input_message_id": "msg_0000000000002346",
  "metadata": {
    "ticket": "4711"
  },
  "mode": "sync",
  "object": "response",
  "output": {
    "format": "markdown",
    "language": "en",
    "text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
  },
  "output_message_id": "msg_0000000000002347",
  "status": "completed",
  "usage": {
    "credits": 1
  }
}

Response 202 Accepted

{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "completed_at": null,
  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
  "created_at": "2026-11-10T16:30:45Z",
  "end_user": {
    "id": "u-17",
    "name": "Anna"
  },
  "error": null,
  "external_id": "ticket-4711",
  "handoff": {
    "requested": false,
    "status": null
  },
  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
  "input_message_id": null,
  "metadata": {
    "ticket": "4711"
  },
  "mode": "async",
  "object": "response",
  "output": null,
  "output_message_id": null,
  "status": "queued",
  "usage": {
    "credits": 0
  }
}

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

Get a response

GET/v1/responses/{response_id}

Permission chat:write

The state and result of a response, e.g. an async one: queued, in_progress, completed or failed.

Parameters

ParameterTypeDescription
response_idrequiredstringpathResponse id (resp_...).

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
choicesarray or nullOnly with include=["choices"].
completed_atstring or nullWhen the answer was finished, in UTC.
conversation_idstring or nullThe conversation (conv_...). Send it, or your external_id, with the next message.
created_atstring or nullWhen it was created, in UTC (ISO 8601).
end_userobject or nullThe end_user you sent.
errorobject or nulltype, code and message when the response failed, otherwise null.
external_idstring or nullYour id of the conversation, if you sent one.
handoffobjectWhether a person of the business was asked to take over.
handoff.requestedbooleanA person of the business has been asked to take over (or has taken over).
handoff.statusstring or nullagent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined.
idstringResponse id (resp_...).
input_message_idstring or nullId of the stored message you sent (msg_...).
metadataobjectThe metadata you sent. Default {}.
modestringHow it was sent: sync, stream or async. One of sync, stream, async.
objectstringAlways response.
outputobject or nullThe answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation.
output.formatstringmarkdown or text, as you asked. One of markdown, text.
output.languagestring or nullLanguage of the answer as an ISO code, when it was detected.
output.textstringThe answer.
output_message_idstring or nullId of the stored answer (msg_...).
productsarray of objects or nullOnly with include=["products"].
skipped_reasonstring or nullWhy there is no answer: human_handoff_active (a person has taken over) or auto_response_off (the agent is muted). One of human_handoff_active, auto_response_off.
statusstringqueued, in_progress, completed or failed. One of queued, in_progress, completed, failed.
usageobjectWhat the answer cost.
usage.creditsintegerAI credits booked for this answer. Default 0.

Example request

curl "https://api.ultimo-bots.com/v1/responses/resp_Qk3mV8sT1xZ7bN4cL0pR2dHw" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
  "completed_at": "2026-11-10T16:30:47Z",
  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
  "created_at": "2026-11-10T16:30:45Z",
  "end_user": {
    "id": "u-17",
    "name": "Anna"
  },
  "error": null,
  "external_id": "ticket-4711",
  "handoff": {
    "requested": false,
    "status": null
  },
  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
  "input_message_id": "msg_0000000000002346",
  "metadata": {
    "ticket": "4711"
  },
  "mode": "async",
  "object": "response",
  "output": {
    "format": "markdown",
    "language": "en",
    "text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
  },
  "output_message_id": "msg_0000000000002347",
  "status": "completed",
  "usage": {
    "credits": 1
  }
}

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

Next steps