const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
channel: '<string>',
external_id: {},
ttl_seconds: 123,
additional_data: {}
})
};
fetch('https://blackbox.dasha.ai/api/v1/chats', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://blackbox.dasha.ai/api/v1/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"channel": "<string>",
"external_id": {},
"ttl_seconds": 123,
"additional_data": {}
}
'import requests
url = "https://blackbox.dasha.ai/api/v1/chats"
payload = {
"agent_id": "<string>",
"channel": "<string>",
"external_id": {},
"ttl_seconds": 123,
"additional_data": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_id": "<string>",
"channel": "<string>",
"messages": [
{
"role": "<string>",
"content": "<string>",
"tool_calls": [
{
"id": "<string>",
"name": "<string>",
"arguments": "<unknown>",
"response": "<unknown>"
}
],
"time": "2023-11-07T05:31:56Z"
}
],
"created_time": "2023-11-07T05:31:56Z",
"last_activity": "2023-11-07T05:31:56Z",
"ttl_seconds": 123,
"is_final": true,
"status": "<string>",
"final_reason": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}Open a new chat session.
Mints a server-side session bound to the named agent on the named channel. The agent is
frozen for the session’s lifetime. external_id is optional but recommended for
channel-driven sessions (SMS, web widget) — it lets the server dedupe duplicate
open-session requests for the same external endpoint via a partial unique index.
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
channel: '<string>',
external_id: {},
ttl_seconds: 123,
additional_data: {}
})
};
fetch('https://blackbox.dasha.ai/api/v1/chats', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://blackbox.dasha.ai/api/v1/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"channel": "<string>",
"external_id": {},
"ttl_seconds": 123,
"additional_data": {}
}
'import requests
url = "https://blackbox.dasha.ai/api/v1/chats"
payload = {
"agent_id": "<string>",
"channel": "<string>",
"external_id": {},
"ttl_seconds": 123,
"additional_data": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_id": "<string>",
"channel": "<string>",
"messages": [
{
"role": "<string>",
"content": "<string>",
"tool_calls": [
{
"id": "<string>",
"name": "<string>",
"arguments": "<unknown>",
"response": "<unknown>"
}
],
"time": "2023-11-07T05:31:56Z"
}
],
"created_time": "2023-11-07T05:31:56Z",
"last_activity": "2023-11-07T05:31:56Z",
"ttl_seconds": 123,
"is_final": true,
"status": "<string>",
"final_reason": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}Sessions vs. completions
Stateful sessions (/api/v1/chats) are the server-owned counterpart of the stateless
/api/v1/text-chat/completion endpoint. Use sessions when the transport itself is asynchronous
(SMS, persistent web chat) and the client cannot reliably carry the encrypted state envelope
across turns.Body
Request body for POST /api/v1/chats — opens a new stateful chat session bound to
the named agent on the named channel. The server owns the conversation transcript from
this point forward; the client only needs to keep the returned session id between turns.
Identifier of the agent that will drive this session. Frozen at open — a session is bound to one agent for its entire lifetime.
Channel name the session lives on (web, twilio_sms, …). Together with
DashaAI.BlackBox.AgentAPI.TextChat.Dtos.Chats.OpenChatRequest.ExternalIdRaw identifies the external endpoint and dedupes against
already-open sessions.
Channel-specific external identifier (e.g. for Twilio SMS, { "from": "+1…", "to":
"+1…", "provider_id": "…" }). Server hashes the canonical form into
ExternalIdHash for the partial unique index that prevents two active sessions
from sharing the same endpoint.
Show child attributes
Show child attributes
Per-session inactivity timeout in seconds (60–86400). When set, the TTL sweeper
finishes the session once LastActivity + TtlSeconds < now().
Initial additional_data bag merged into agent prompt template variables. Server
overwrites the reserved keys (DashaAI.BlackBox.AgentAPI.TextChat.ChatReservedKeys.Channel,
DashaAI.BlackBox.AgentAPI.TextChat.ChatReservedKeys.SipEndpoint) before each LLM call.
Show child attributes
Show child attributes
Response
Session created. The returned id is the only piece the client needs to remember.
Public projection of a chat session — what callers see via GET /api/v1/chats/{id}
and the list endpoint. Deliberately omits the orchestration State blob, the
ExternalIdHash, and the worker hot-flags; those are server-internal.
Session identifier.
Agent driving this session. Frozen at open.
Channel name (web, twilio_sms, …).
Full conversation transcript so far, in send order.
Show child attributes
Show child attributes
Session creation timestamp (UTC).
Most recent activity timestamp (inbound, outbound or assistant turn).
Inactivity timeout in seconds; null when no TTL applies.
True once the session has terminated.
Status mirror of DashaAI.BlackBox.AgentAPI.TextChat.Dtos.Chats.ChatSessionDto.IsFinal for list-endpoint filtering (active /
final).
Reason for finalisation (ttl, user_end, agent_finish, …).
Was this page helpful?