Send messages and keep conversations

One endpoint sends a message to an agent: POST /v1/responses. You choose how the answer comes back and which conversation it belongs to; Ultimo keeps the history.

5 min read Updated

The request

POST /v1/responses

{
  "agent_id": "YOUR_AGENT_ID",
  "input": "Can you check my order?",
  "external_id": "ticket-4711",
  "end_user": {"id": "U024BE7LH", "name": "Anna"},
  "context": {"customer_number": "K-1032", "plan": "Gold"},
  "metadata": {"department": "support"},
  "format": "text",
  "include": ["choices"]
}
FieldMeaning
agent_idRequired. An agent of GET /v1/agents.
inputRequired. The message, up to 4000 characters.
external_idYour id of the conversation (channel, thread, ticket), up to 200 characters. Created on first use, continued afterwards. No personal data in ids.
conversation_idContinue a conversation by its conv_ id instead.
conversation_typedirect (default) or group: several people in one channel. Set when the conversation is created. See group conversations.
end_userid and name of the author. The agent reads the message as “Anna: …” and so knows who is speaking in a group.
contextText or an object from your system for this answer only, up to 8000 characters. It is not stored in the history or with the finished response; an async request keeps it only while it waits. Not accepted in group conversations.
metadataUp to 20 key-value pairs of this message. Stored with the message and returned in the response.
formatmarkdown (default) or text for systems that cannot show Markdown.
includeproducts (product cards) and choices (quick-reply buttons) as own fields. Off by default.
streamServer-sent events instead of one JSON response.
async202 at once; poll or receive a webhook.

Conversations

Ultimo stores every conversation; you never send the history. Three ways to address one: your external_id (the usual way), a conversation_id, or neither, which starts a new conversation for one-off jobs such as “summarise this ticket”. The agent considers the last 60 entries.

  • Conversations belong to the integration. Two integrations with the same external_id have two separate conversations, and a new key keeps the history.
  • GET /v1/conversations lists the integration's conversations (filter by agent_id or external_id); GET /v1/conversations/{id}/messages returns the history with the roles user, assistant and staff (your team).
  • DELETE /v1/conversations/{id} deletes it for a new topic or a deletion request. See deleting and retention.
  • PUT /v1/conversations/{id}/auto-response with {"enabled": false} mutes the agent in one conversation: messages are stored, no answers, no credits.
  • The conversations show up in the portal's inbox under the channel API.

Group conversations

Use "conversation_type": "group" with the first message when several people write in one conversation, for example a team channel. Pass end_user.name with every message so the agent knows who is speaking. Two rules protect personal data there:

  • context is not accepted in a group conversation. Everyone in the group reads the answer, so data about one person must not reach it. The call answers 400 context_not_allowed_in_group and stores nothing. The type is fixed when the conversation is created, so this holds for every later message too.
  • The agent is told that several people read along and that it must not pass one participant's contact, order or account details to another. This is an instruction to the agent, not a technical barrier: do not send personal data into a group conversation that not everyone in it may see.

Deleting and retention

DELETE /v1/conversations/{id} removes everything stored for the conversation: the history with its authors and metadata, the stored requests and answers of POST /v1/responses, and the webhook events that carry its content, with their delivery log. A request that is still waiting or running for it ends failed with the code conversation_deleted. Afterwards GET /v1/responses/{id} of its finished responses answers 404.

  • Leads are their own records. Delete a lead with DELETE /v1/agents/{id}/leads/{lead_id}; its lead.created event goes with it.
  • Conversations stay until you delete them. Finished responses (the stored request and answer behind GET /v1/responses/{id}) are deleted after 30 days, webhook events and their delivery log too.
  • context is not stored in the history and not with the finished response. Only an async request keeps it, with the waiting job, until the job runs or expires (at most 15 minutes); then it is removed.
  • A lead or an agent deleted in the portal is removed from the API too, within a few minutes: the stored requests and answers and the webhook events with that content.

Answer as JSON

Without stream and async the call waits for the answer, up to 120 seconds. output.text holds the answer, usage.credits what it cost. Gateways and workflow tools that give up after 30 or 60 seconds should use a stream or async.

Answer as a stream

With "stream": true the answer arrives in pieces as server-sent events, each with JSON data: response.created, status (what the agent is doing), delta (text), products, choices, response.completed (the whole response object) or error. A comment line : heartbeat every 15 seconds keeps proxies from closing the connection. If your client disconnects, the answer is still finished and stored: repeat the request with the same Idempotency-Key to get it.

curl

curl -N https://api.ultimo-bots.com/v1/responses \
  -H "Authorization: Bearer $ULTIMO_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "YOUR_AGENT_ID", "input": "What does shipping cost?", "stream": true}'

event: response.created
data: {"id": "resp_...", "status": "in_progress", ...}

event: status
data: {"status": {"key": "search_knowledge", "label": "Searching the knowledge base"}}

event: delta
data: {"text": "Shipping within Germany "}

event: delta
data: {"text": "is free from 6 bottles."}

event: response.completed
data: {"id": "resp_...", "status": "completed", "output": {"text": "Shipping within Germany is free from 6 bottles.", ...}}

Node.js 18+

const res = await fetch("https://api.ultimo-bots.com/v1/responses", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ agent_id: "YOUR_AGENT_ID", input: "What does shipping cost?", stream: true })
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  let end;
  while ((end = buffer.indexOf("\n\n")) >= 0) {
    const block = buffer.slice(0, end); buffer = buffer.slice(end + 2);
    const event = /^event: (.*)$/m.exec(block)?.[1];
    const data = /^data: (.*)$/m.exec(block)?.[1];
    if (event === "delta") process.stdout.write(JSON.parse(data).text);
    if (event === "error") throw new Error(JSON.parse(data).error.code);
  }
}

Answer async

With "async": true you get 202 and the response with status queued at once. A worker answers it within the workspace's limits; poll GET /v1/responses/{id} until completed or failed, or subscribe to the response.completed and response.failed webhooks. A job cut off by a restart ends failed with code interrupted and is not run again, because an agent's actions (an order, an e-mail) must not happen twice. Send it again if you still need it.

A workspace can have up to 100 async requests waiting; more answer 429 queue_limit_exceeded. A request that has waited 15 minutes without being started ends failed with code expired and is not run, so an answer never arrives long after anyone still waits for it. Waiting requests of several workspaces are started in turn; a workspace with a long queue does not hold up the others.

curl

# 1. start
curl https://api.ultimo-bots.com/v1/responses -H "Authorization: Bearer $ULTIMO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4711-summary" \
  -d '{"agent_id": "YOUR_AGENT_ID", "input": "Summarise this ticket: ...", "async": true}'
# -> 202 {"id": "resp_...", "status": "queued", ...}

# 2. poll (or receive the response.completed webhook)
curl https://api.ultimo-bots.com/v1/responses/resp_... -H "Authorization: Bearer $ULTIMO_API_KEY"
# -> {"status": "completed", "output": {"text": "..."}, ...}

Python

import os, time, requests

H = {"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"}
job = requests.post("https://api.ultimo-bots.com/v1/responses", headers=H, json={
    "agent_id": "YOUR_AGENT_ID", "input": "Summarise this ticket: ...", "async": True}).json()
while job["status"] in ("queued", "in_progress"):
    time.sleep(2)
    job = requests.get(f"https://api.ultimo-bots.com/v1/responses/{job['id']}", headers=H).json()
print(job["status"], (job.get("output") or {}).get("text") or job["error"])

Handoff to your team

When the agent hands a conversation to a person (live chat), the response has handoff.requested: true and the status agent_requested or agent_joined. While your team has the conversation, further messages are stored and shown to the team, output is null and skipped_reason is human_handoff_active. Your team answers in the portal's live inbox; their replies reach your system as handoff.message webhooks and in the history. Answering from your own tool is not part of version 1.

What it does not do

  • No files or images in messages: text only.
  • No listening without answering (observe mode) and no verified end users for personal data yet.
  • No “conversation ended” or rating events: conversations with the agent have no fixed end.

Next steps