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.
Send a message
POST/v1/responses
Send one message to an agent and get its answer.
- JSON (default): waits for the answer (up to 120 s).
"stream": true: server-sent eventsresponse.created,status,delta,products,choices,response.completed,error; JSON in every event; a heartbeat comment every 15 s."async": true: 202 at once; pollGET /v1/responses/{id}or receive theresponse.completedwebhook.
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
| Parameter | Type | Description |
|---|---|---|
Idempotency-Key | stringheader | Any 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
| Field | Type | Description |
|---|---|---|
agent_idrequired | string | Agent id from GET /v1/agents. Up to 200 characters. |
inputrequired | string | The message, at most 4000 characters. |
async | boolean | Return 202 at once and poll GET /v1/responses/{id}. Default false. |
context | string or object or null | Data from your system for this answer only (e.g. CRM fields). Never stored in the history. |
conversation_id | string or null | Continue an existing conversation (conv_...). Up to 64 characters. |
conversation_metadata | object or null | Key-value data stored on the conversation. |
conversation_type | string or null | direct (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_user | object or null | Who wrote the message. |
end_user.id | string or null | Your id of the person who wrote the message. No personal data in ids. Up to 200 characters. |
end_user.name | string or null | Display name; the agent sees the message as "<name>: <text>". Up to 100 characters. |
external_id | string or null | Your id of the conversation (channel, thread, ticket). Created on first use. Up to 200 characters. |
format | string | Answer as Markdown (default) or plain text. One of markdown, text. Default markdown. |
include | array of strings | Structured extras: product cards and quick-reply choices. Off by default. One of products, choices. |
metadata | object or null | Key-value data of this message, returned with the response. |
stream | boolean | Server-sent events instead of one JSON response. Default false. |
Response 200 OK ยท 202 Accepted
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
choices | array or null | Only with include=["choices"]. |
completed_at | string or null | When the answer was finished, in UTC. |
conversation_id | string or null | The conversation (conv_...). Send it, or your external_id, with the next message. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
end_user | object or null | The end_user you sent. |
error | object or null | type, code and message when the response failed, otherwise null. |
external_id | string or null | Your id of the conversation, if you sent one. |
handoff | object | Whether a person of the business was asked to take over. |
handoff.requested | boolean | A person of the business has been asked to take over (or has taken over). |
handoff.status | string or null | agent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined. |
id | string | Response id (resp_...). |
input_message_id | string or null | Id of the stored message you sent (msg_...). |
metadata | object | The metadata you sent. Default {}. |
mode | string | How it was sent: sync, stream or async. One of sync, stream, async. |
object | string | Always response. |
output | object or null | The answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation. |
output.format | string | markdown or text, as you asked. One of markdown, text. |
output.language | string or null | Language of the answer as an ISO code, when it was detected. |
output.text | string | The answer. |
output_message_id | string or null | Id of the stored answer (msg_...). |
products | array of objects or null | Only with include=["products"]. |
skipped_reason | string or null | Why 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. |
status | string | queued, in_progress, completed or failed. One of queued, in_progress, completed, failed. |
usage | object | What the answer cost. |
usage.credits | integer | AI 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"
}
}'import os, uuid, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/responses",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"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",
},
},
timeout=130,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/responses", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"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"
}
})
});
console.log(res.status, await res.json());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}
The state and result of a response, e.g. an async one: queued, in_progress, completed or failed.
Parameters
| Parameter | Type | Description |
|---|---|---|
response_idrequired | stringpath | Response id (resp_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
choices | array or null | Only with include=["choices"]. |
completed_at | string or null | When the answer was finished, in UTC. |
conversation_id | string or null | The conversation (conv_...). Send it, or your external_id, with the next message. |
created_at | string or null | When it was created, in UTC (ISO 8601). |
end_user | object or null | The end_user you sent. |
error | object or null | type, code and message when the response failed, otherwise null. |
external_id | string or null | Your id of the conversation, if you sent one. |
handoff | object | Whether a person of the business was asked to take over. |
handoff.requested | boolean | A person of the business has been asked to take over (or has taken over). |
handoff.status | string or null | agent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined. |
id | string | Response id (resp_...). |
input_message_id | string or null | Id of the stored message you sent (msg_...). |
metadata | object | The metadata you sent. Default {}. |
mode | string | How it was sent: sync, stream or async. One of sync, stream, async. |
object | string | Always response. |
output | object or null | The answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation. |
output.format | string | markdown or text, as you asked. One of markdown, text. |
output.language | string or null | Language of the answer as an ISO code, when it was detected. |
output.text | string | The answer. |
output_message_id | string or null | Id of the stored answer (msg_...). |
products | array of objects or null | Only with include=["products"]. |
skipped_reason | string or null | Why 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. |
status | string | queued, in_progress, completed or failed. One of queued, in_progress, completed, failed. |
usage | object | What the answer cost. |
usage.credits | integer | AI 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"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/responses/resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
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/responses/resp_Qk3mV8sT1xZ7bN4cL0pR2dHw", {
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",
"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.