Skip to main content
POST
/
api
/
v1
/
chats
/
{id}
/
messages
Submit one user turn to an existing chat session.
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({content: '<string>', idempotency_key: '<string>', additional_data: {}})
};

fetch('https://blackbox.dasha.ai/api/v1/chats/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "messages": [
    {
      "role": "<string>",
      "content": "<string>",
      "tool_calls": [
        {
          "id": "<string>",
          "name": "<string>",
          "arguments": "<unknown>",
          "response": "<unknown>"
        }
      ],
      "time": "2023-11-07T05:31:56Z"
    }
  ],
  "is_final": true,
  "status": "<string>"
}

​
Idempotency

Network retries (especially over SMS) can re-submit the same logical turn twice. Always send an idempotency_key (any client-chosen unique value, e.g. UUID or sessionId+turnNumber) so the server can dedupe. The retry returns the prior assistant response — including when the original turn finalised the session.

Path Parameters

​
id
string<uuid>
required

Body

Request body for POST /api/v1/chats/{id}/messages — submits a single user turn to the named session. The response contains only the assistant turn(s) produced this round, not the full transcript (the transcript lives on the server and is retrievable via GET /api/v1/chats/{id}).

​
content
string | null

User-supplied message content for this turn.

​
idempotency_key
string | null

Optional idempotency key. When supplied, a retried submit with the same key returns the previous assistant response without re-running the LLM. Bound to the session, not global. Capped at 128 characters.

​
additional_data
object

Turn-level additional_data overrides merged on top of the session's persisted bag. Reserved keys (DashaAI.BlackBox.AgentAPI.TextChat.ChatReservedKeys) are dropped before merge.

Response

Submit succeeded. Inspect is_final to decide whether to keep submitting.

Response to POST /api/v1/chats/{id}/messages. Returns only the new assistant turn(s) produced this round (per the plan's "returns only the new assistant turn(s)" requirement), plus the post-turn session status so clients don't need a follow-up GET to learn whether the agent finished the conversation.

​
messages
object[] | null

New messages produced this turn. Ordered: assistant tool-turns first (each bundling its tool calls with their executed responses), final plain-text assistant reply last.

​
is_final
boolean

True when the agent signalled end-of-conversation this turn (e.g. invoked the finishTheConversation built-in tool) and the session has been finalised. After this point, further submits return 409 Conflict.

​
status
string | null

Post-turn session status: active while accepting new turns, final after finalisation (matches the state filter on the list endpoint).