Conversations
Open a conversation for one of your end users, send messages, read the answer as JSON or as an event stream, answer the agent's questions, attach files and stop a turn.
A conversation is one thread between an agent and one end user of your product. A turn is one message and the agent's answer to it. A conversation runs one turn at a time.
All paths on this page start with:
https://sokko.ai/api/v1/workspaces/{workspaceId}/agents/{agentId}The examples use $BASE for that prefix and $CONV for a conversation id.
Create a conversation
POST /conversations| Field | Type | Rules |
|---|---|---|
externalUserId | string | Required. 1 to 128 characters: letters, digits and . _ : @ -. |
title | string | Optional. One line, 1 to 120 characters. Without it the title is New chat. |
curl $BASE/conversations \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "externalUserId": "user_88213", "title": "Order for Saturday" }'The answer is 201:
{
"id": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
"externalUserId": "user_88213",
"title": "Order for Saturday",
"createdAt": "2026-11-20T09:21:12.300Z",
"updatedAt": "2026-11-20T09:21:12.300Z"
}externalUserId is your own id for the person. One end user can have many
conversations, and the same id can be used with several agents.
The agent is shown the externalUserId as an identifier. Use an opaque id of your system, not an
email address or a name. The id is also what you pass to delete the data of one end
user.
In every conversation the agent is told that the writer is a customer of the business and not its owner, which reply format to use, and to put its complete answer in the reply text.
A new conversation needs an agent whose status is ready. Reading, listing
and deleting conversations work in every status of the agent.
Errors: 400 invalid_request, 404 not_found, 409 agent_not_ready (the
agent is not ready).
List, read and delete conversations
GET /conversations
GET /conversations/{conversationId}
DELETE /conversations/{conversationId}The list comes newest first. It takes limit, cursor and externalUserId,
which keeps the conversations of one end user.
curl "$BASE/conversations?externalUserId=user_88213" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"Reading one conversation returns its messages, oldest first:
{
"conversation": {
"id": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
"externalUserId": "user_88213",
"title": "Order for Saturday",
"createdAt": "2026-11-20T09:21:12.300Z",
"updatedAt": "2026-11-20T09:21:46.031Z"
},
"messages": [
{
"id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"role": "user",
"text": "Can I still order 20 croissants for tomorrow?",
"status": "completed",
"createdAt": "2026-11-20T09:21:40.512Z"
},
{
"id": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"role": "assistant",
"text": "Yes. Orders for tomorrow close at 16:00 today.",
"status": "completed",
"createdAt": "2026-11-20T09:21:40.512Z"
}
],
"pendingInputs": [],
"activeTurnId": null
}- The
idof ausermessage is theclientMessageIdof its send. Theidof anassistantmessage is the turn id. - The
statusof anassistantmessage is the status of its turn. pendingInputsholds the questions the agent waits on. See Agent questions.activeTurnIdis the id of the running turn, ornull.
A delete removes the conversation with its turns and files, and answers:
{ "id": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d", "deleted": true }A conversation with a running turn cannot be deleted: the call answers 409
turn_in_progress with the turn's id. Stop the turn first.
Only conversations created through this API exist here. Errors: 400
invalid_request, 404 not_found, 409 turn_in_progress.
Send a message
POST /conversations/{conversationId}/messages| Field | Type | Rules |
|---|---|---|
text | string | The end user's message, up to 32,000 characters. |
clientMessageId | string | Optional. A UUID you generate. It makes the send safe to retry. |
attachmentIds | string[] | Optional. Up to 5 ids of attachments. Only with text. |
answers | array | Answers to the agent's questions, 1 to 20. See Agent questions. |
Send exactly one of text and answers. The whole body holds at most
160,000 bytes.
The same call answers in one of two modes. You choose with the Accept
header.
JSON mode
Without Accept: text/event-stream, the answer is the turn as JSON. The query
parameter wait holds the request open for up to that many seconds (0 to 60,
default 0) until the turn ends.
curl "$BASE/conversations/$CONV/messages?wait=60" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Can I still order 20 croissants for tomorrow?",
"clientMessageId": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}'200 when the turn has ended, or waits for an answer of the end user:
{
"id": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"conversationId": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"status": "completed",
"text": "Yes. Orders for tomorrow close at 16:00 today.",
"tools": [{ "name": "orders_cutoff", "state": "completed" }],
"createdAt": "2026-11-20T09:21:40.512Z",
"finishedAt": "2026-11-20T09:21:46.031Z"
}202 when the turn still runs after the wait:
{
"id": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"conversationId": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"status": "running",
"text": "",
"tools": [{ "name": "orders_cutoff", "state": "running" }],
"createdAt": "2026-11-20T09:21:40.512Z",
"finishedAt": null
}The turn keeps running after a 202. Read it again until it ends:
GET /conversations/{conversationId}/turns/{turnId}?wait=60That call takes the same wait and answers 200 or 202 the same way. Or open
the event stream of the turn.
The turn object
| Field | Meaning |
|---|---|
id | The turn id. |
status | running, waiting, completed, failed, interrupted or cancelled. |
text | The agent's answer. Complete when status is completed. It can be empty while the turn runs. |
tools | The tools the agent called, in order, each with name and state: running, completed, failed. See Tool names. |
pendingInputs | Only on a waiting turn: the questions the agent asked. |
error | Only on a failed, interrupted or cancelled turn: { "code", "message" }. |
finishedAt | null while the turn runs. |
Turn errors
A turn that fails is still a 200: the HTTP call worked, the turn did not. Read
error.code:
status | error.code | Meaning |
|---|---|---|
failed | credits_exhausted | The workspace ran out of credits during the turn. |
failed | agent_unavailable | The agent could not be reached. Try again later. |
failed | timeout | The turn reached its time limit of 30 minutes. |
failed | response_too_large | The answer was too large. |
failed | agent_error | The agent could not complete the turn. |
interrupted | interrupted | The turn was cut off before it finished. The message was not sent again. |
cancelled | cancelled | You stopped the turn. |
After interrupted, decide in your product whether to send the message again.
Use a new clientMessageId for a new attempt.
The status of a finished turn is completed everywhere: in the turn object, in
the messages of a conversation, in the event stream (turn.completed) and in
the status of a webhook.
Tool names
tools[].name and the name of a tool.updated event are the names the agent
reported, with one change: a built-in tool of the platform is given without
the platform's own prefix. A tool of an MCP server of yours keeps the name the
agent reported, which can carry the name of the server in front of the tool.
Treat a name as a label to show or to log. Do not build logic on the exact
name of a built-in tool.
Errors of the send
Before a new turn starts, the call checks your subscription, the agent, the
fit of the message and the workspace's credits. A retry with a
clientMessageId the conversation already has skips these checks and returns
the first turn.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | Both or neither of text and answers, a bad field, or an answer that does not match its question. |
| 413 | payload_too_large | The body is over 160,000 bytes. |
| 404 | not_found | No such conversation on this agent. |
| 402 | billing_inactive | Your subscription has ended or is paused. A past-due payment does not stop messages. |
| 409 | agent_not_ready | The agent is not ready. |
| 409 | input_required | The agent waits for an answer and you sent text, or you answered only some questions. |
| 409 | no_pending_input | You sent answers and no question waits. |
| 402 | credits_exhausted | The workspace has no credits left, and no automatic top-up was possible. |
| 409 | turn_in_progress | Another turn is running in this conversation. |
| 409 | idempotency_mismatch | The clientMessageId was used in this conversation with other content. |
| 409 | conflict | The conversation cannot take the message at this moment. Read the conversation, then send again. |
| 429 | too_many_streams | Stream mode only: 20 streams are open. No turn was started. |
| 503 | agent_unavailable | The agent could not be reached. Try again later. |
| 504 | timeout | The agent did not accept the message in time. |
One turn at a time
While a turn runs, a second message to the same conversation answers:
{
"error": {
"code": "turn_in_progress",
"message": "A turn is already running in this conversation.",
"turnId": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f"
}
}turnId is the running turn. Wait for it, stream it, or
stop it, then send the next message. Different conversations
of the same agent run at the same time.
Retry a send
Send a clientMessageId with every message. If the request times out or the
connection drops, send the same body again:
- The first turn is returned. No second turn starts, and nothing is charged twice.
- In stream mode you get the stream of that turn from its first event.
- The same id with other content answers 409
idempotency_mismatch.
Stream mode
Send Accept: text/event-stream on the same POST, and the answer is a
server-sent event
stream of the new turn. wait is ignored.
curl -N "$BASE/conversations/$CONV/messages" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"text": "Can I still order 20 croissants for tomorrow?",
"clientMessageId": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}'The response has the header x-turn-id with the id of the turn. Keep it: you
need it to continue a broken stream.
The format
- The stream starts with
retry: 3000, the delay in milliseconds a client waits before it connects again. - Every event has three lines:
id,eventanddata.datais one line of JSON. idis a whole number that grows through the turn. Numbers can be skipped. Anidbelongs to its turn: the same number means another event in another turn. The last event of a turn has anidof its own, higher than every event before it.- A comment line
: keepalivearrives every 15 seconds. Ignore it. - The stream closes after the last event of the turn.
A full stream
retry: 3000
id: 0
event: turn.started
data: {"turnId":"9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f","conversationId":"c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d","createdAt":"2026-11-20T09:21:40.512Z"}
id: 2
event: tool.updated
data: {"toolCallId":"call_01","name":"orders_cutoff","state":"running"}
id: 3
event: tool.updated
data: {"toolCallId":"call_01","name":"orders_cutoff","state":"completed"}
id: 5
event: message.delta
data: {"partId":"text-1","text":"Yes. Orders for tomorrow "}
id: 6
event: message.delta
data: {"partId":"text-1","text":"close at 16:00 today."}
: keepalive
id: 8
event: turn.completed
data: {"turnId":"9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f","text":"Yes. Orders for tomorrow close at 16:00 today."}Event types
| Event | data | Meaning |
|---|---|---|
turn.started | turnId, conversationId, createdAt | The turn began. |
message.delta | partId, text | The next piece of the answer. Append text to what you have for this partId. |
tool.updated | toolCallId, name, state | A tool call changed state: running, completed or failed. |
input.requested | requestId, kind, prompt, options, allowFreeform, multiSelect | The agent asks the end user a question. options, allowFreeform and multiSelect are optional. |
file.created | url, mediaType | The agent made a file available at a public https address. |
turn.completed | turnId, text | Last event. The complete answer. |
turn.waiting | turnId, pendingInputs | Last event. The turn stopped to wait for answers. |
turn.failed | turnId, status, error | Last event. status is failed, interrupted or cancelled. error is { code, message } as in Turn errors. |
Notes for your client:
- An answer can have several text parts, for example text before and after a
tool call. Keep one buffer per
partIdand show them in order of arrival. Thetextofturn.completedis all parts together: use it as the final answer. tool.updatedcarries the tool's name and state only, never its input or its result. See Tool names.- Exactly one of
turn.completed,turn.waitingandturn.failedends a stream. A stream that closes without one of them broke: continue it. file.createdis rare. Agents are told to answer in text, and a file is sent only when its address is one your server can fetch without a login.- Ignore event types you do not know. New ones can be added.
Continue a stream
A stream can break: a proxy closes it, a network drops. The turn keeps running on the platform. Open the stream again behind the last event you have:
GET /conversations/{conversationId}/stream?turnId={turnId}&after={lastEventId}| Query | Meaning |
|---|---|
turnId | The turn to read. Without it: the turn that runs now, from its first event. |
after | The id of the last event you received. Needs turnId. Without it: from the first event. |
The header Last-Event-ID works in place of after. When both are present,
after wins.
A resume requires turnId. An event id counts the events of one turn, so
after (or Last-Event-ID) without turnId answers 400 invalid_request.
Keep the x-turn-id of the first response for this. A browser's EventSource
sends Last-Event-ID by itself when it reconnects, so give it a URL that
already holds turnId.
curl -N "$BASE/conversations/$CONV/stream?turnId=9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f&after=5" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Accept: text/event-stream"The stream continues with the events after id 5. No event is sent twice.
The call answers 204 with no body when there is nothing to stream: no
turnId was given and no turn runs, or the turn has ended and after is at
its last event. After a 204, read the turn with
GET /conversations/{conversationId}/turns/{turnId} for its final state.
You can also use this call on its own: send the message in JSON mode with
wait=0, then open the stream of the returned turn id.
Errors: 400 invalid_request (after is not an event id, or after without
turnId), 404 not_found (no such conversation or turn), 429
too_many_streams.
Read the stream in Node.js
This example sends a message, prints the answer as it arrives, and continues behind the last event when the connection breaks. It needs Node.js 20 or newer and no package.
const API = "https://sokko.ai/api/v1";
const AUTH = { Authorization: `Bearer ${process.env.SOKKO_PLATFORM_KEY}` };
const LAST_EVENTS = new Set(["turn.completed", "turn.waiting", "turn.failed"]);
// Yields { id, type, data } for each event of a text/event-stream response.
async function* readEvents(response) {
const decoder = new TextDecoder();
let buffer = "";
for await (const chunk of response.body) {
buffer += decoder.decode(chunk, { stream: true });
let end = buffer.indexOf("\n\n");
while (end !== -1) {
const event = {};
for (const line of buffer.slice(0, end).split("\n")) {
if (line.startsWith("id: ")) event.id = Number(line.slice(4));
if (line.startsWith("event: ")) event.type = line.slice(7);
if (line.startsWith("data: ")) event.data = JSON.parse(line.slice(6));
}
buffer = buffer.slice(end + 2);
if (event.type) yield event; // "retry:" and ": keepalive" have no type
end = buffer.indexOf("\n\n");
}
}
}
// conversation: /workspaces/<id>/agents/<id>/conversations/<id>
export async function ask(conversation, text, onText) {
const url = `${API}${conversation}`;
let response = await fetch(`${url}/messages`, {
method: "POST",
headers: { ...AUTH, "Content-Type": "application/json", Accept: "text/event-stream" },
body: JSON.stringify({ text, clientMessageId: crypto.randomUUID() }),
});
if (!response.ok) throw new Error(`send failed: ${response.status} ${await response.text()}`);
const turnId = response.headers.get("x-turn-id");
let lastId = null;
for (let attempt = 0; attempt < 30; attempt += 1) {
try {
for await (const event of readEvents(response)) {
lastId = event.id;
if (event.type === "message.delta") onText(event.data.text);
if (LAST_EVENTS.has(event.type)) return event;
}
} catch {
// The connection broke. Continue behind the last event.
}
await new Promise((resolve) => setTimeout(resolve, 3000));
const after = lastId === null ? "" : `&after=${lastId}`;
response = await fetch(`${url}/stream?turnId=${turnId}${after}`, {
headers: { ...AUTH, Accept: "text/event-stream" },
});
if (response.status === 204) break; // nothing more to stream
if (!response.ok) throw new Error(`stream failed: ${response.status}`);
}
// The stream has no more events: read the final state of the turn.
const turn = await fetch(`${url}/turns/${turnId}?wait=60`, { headers: AUTH });
return { type: "turn", data: await turn.json() };
}const last = await ask(
"/workspaces/7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11/agents/3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05/conversations/c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"Can I still order 20 croissants for tomorrow?",
(text) => process.stdout.write(text),
);Run this on your server and pass the text on to your front end over your own connection. The platform key must not reach the browser.
Agent questions
An agent can stop a turn to ask the end user something: a choice between
options, a free answer, or approval of an action. The turn then ends with the
status waiting.
In stream mode you get input.requested for each question, then
turn.waiting. In JSON mode the turn has pendingInputs:
{
"id": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"conversationId": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
"status": "waiting",
"text": "I can book one of two pick-up times.",
"tools": [],
"pendingInputs": [
{
"requestId": "req_7f3a",
"kind": "question",
"prompt": "Which pick-up time do you want?",
"options": [
{ "id": "opt_1", "label": "Saturday 8:00" },
{ "id": "opt_2", "label": "Saturday 10:30", "description": "The shop is busier then." }
],
"allowFreeform": true
}
],
"createdAt": "2026-11-20T09:25:02.110Z",
"finishedAt": "2026-11-20T09:25:09.774Z"
}| Field | Meaning |
|---|---|
requestId | The id you answer with. |
kind | question, tool-approval (the agent asks to run an action) or session-limit (the agent's session reached its limit, and it asks to continue). |
prompt | The question, to show to the end user. |
options | Optional. The choices, each with id, label and an optional description. |
allowFreeform | Optional. true when the end user may type an answer of their own. |
multiSelect | Optional. true when the end user may pick several options. |
Show the question in your product, then send the answers with answers in
place of text:
curl "$BASE/conversations/$CONV/messages?wait=60" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "answers": [{ "requestId": "req_7f3a", "optionId": "opt_1" }] }'Each answer has requestId and exactly one of:
| Field | Use it for |
|---|---|
optionId | One option. |
optionIds | Several options (1 to 4), when multiSelect is true. |
text | A typed answer, up to 32,000 characters. |
Rules:
- Answer every pending question in one message. A message that answers
only some of them answers 409
input_required. - While questions wait, a
textmessage answers 409input_required. To drop the questions and move on, stop the turn, then sendtext. answerswith no pending question answers 409no_pending_input.attachmentIdscannot go withanswers.
The answers start a new turn, which answers in JSON or as a stream like any
other. GET /conversations/{conversationId} shows the pending questions of a
conversation in pendingInputs at any time.
Attachments
Upload a file to a conversation, then name it in a message.
POST /conversations/{conversationId}/attachmentsThe body is multipart/form-data with exactly one field, file.
curl $BASE/conversations/$CONV/attachments \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-F "file=@./order-list.pdf"The answer is 201:
{
"id": "b8d0f2a4-6c1e-4f3a-9b5d-7e9f1a3c5b7d",
"filename": "order-list.pdf",
"mediaType": "application/pdf",
"size": 184220
}Then send the message:
curl "$BASE/conversations/$CONV/messages?wait=60" \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Is everything on this list available for Saturday?",
"attachmentIds": ["b8d0f2a4-6c1e-4f3a-9b5d-7e9f1a3c5b7d"]
}'- File types, by extension:
png,jpg,jpeg,webp,pdf,docx,xlsx,pptx,odt,ods,odp,txt,md,csv,json. The content must match the extension. - One file: 5 MB at most. A PDF: 50 pages at most.
- One message: 5 files and 20 MB together at most.
- One conversation: 2,000 files and 200 MB together at most.
- The answer has no download address. The API does not serve an attachment back.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | Not multipart, more than one field, a file type that is not allowed, or content that does not match its type. |
| 404 | not_found | No such conversation on this agent. |
| 413 | payload_too_large | The file, the PDF or the conversation is over its limit. |
| 503 | unavailable | File storage is not available. You can still send text. |
Stop a turn
POST /conversations/{conversationId}/stopcurl -X POST $BASE/conversations/$CONV/stop \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{ "stopped": true }The call asks the running turn to stop and drops the questions the agent
waits on. The turn then ends with the status cancelled, an open stream gets
turn.failed with "status": "cancelled", and your endpoints get the event
turn.failed with the same status. The stop is a request: the
turn can take a few seconds to end, so wait for its last event or read the
turn before you send the next message.
A conversation with no running turn and no pending question answers
{ "stopped": true } and changes nothing.
Errors: 404 not_found, 409 agent_not_ready (the agent does not run, so it
could not be told to stop).