> ## Documentation Index > Fetch the complete documentation index at: https://blackbox.dasha.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## 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. ## OpenAPI ````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/chats openapi: 3.0.4 info: title: Dasha BlackBox Agent API description: API for managing AI agents and calls contact: name: DashaAI Team email: support@dasha.ai version: v1 servers: - url: https://blackbox.dasha.ai description: Dasha BlackBox Agent API security: - ApiKey: [] - OAuth: [] tags: - name: ActivityLogs - name: Agents - name: AgentTestCases - name: CallResults - name: Calls - name: Chats - name: Copilot - name: CustomerData - name: Mcp - name: Media - name: Misc - name: PronunciationDictionaries - name: Providers - name: SipAliases - name: SipCredentials - name: SipPhoneNumbers - name: TextChat - name: TwilioProvider - name: Voice - name: WebhookTest - name: WebIntegrations - name: WebSocket description: WebSocket endpoints for real-time communication paths: /api/v1/chats: post: tags: - Chats summary: Open a new chat session. description: >- 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. requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/OpenChatRequest' description: >- 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. text/json: schema: allOf: - $ref: '#/components/schemas/OpenChatRequest' description: >- 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. application/*+json: schema: allOf: - $ref: '#/components/schemas/OpenChatRequest' description: >- 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. responses: '201': description: >- Session created. The returned id is the only piece the client needs to remember. content: application/json: schema: $ref: '#/components/schemas/ChatSessionDto' '400': description: >- Request failed validation (missing agent_id / channel, out-of-range ttl_seconds, …). content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '409': description: A non-final session already exists for this channel + external_id. content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: OpenChatRequest: type: object properties: agent_id: type: string description: >- Identifier of the agent that will drive this session. Frozen at open — a session is bound to one agent for its entire lifetime. nullable: true channel: type: string description: >- 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. nullable: true external_id: type: object additionalProperties: {} description: >- 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. nullable: true ttl_seconds: type: integer description: >- Per-session inactivity timeout in seconds (60–86400). When set, the TTL sweeper finishes the session once `LastActivity + TtlSeconds < now()`. format: int32 nullable: true additional_data: type: object additionalProperties: {} description: >- 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. nullable: true additionalProperties: false description: >- 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. ChatSessionDto: type: object properties: id: type: string description: Session identifier. format: uuid agent_id: type: string description: Agent driving this session. Frozen at open. nullable: true channel: type: string description: Channel name (`web`, `twilio_sms`, …). nullable: true messages: type: array items: $ref: '#/components/schemas/ChatMessageDto' description: Full conversation transcript so far, in send order. nullable: true created_time: type: string description: Session creation timestamp (UTC). format: date-time last_activity: type: string description: >- Most recent activity timestamp (inbound, outbound or assistant turn). format: date-time ttl_seconds: type: integer description: Inactivity timeout in seconds; null when no TTL applies. format: int32 nullable: true is_final: type: boolean description: True once the session has terminated. status: type: string description: >- Status mirror of DashaAI.BlackBox.AgentAPI.TextChat.Dtos.Chats.ChatSessionDto.IsFinal for list-endpoint filtering (`active` / `final`). nullable: true final_reason: type: string description: Reason for finalisation (`ttl`, `user_end`, `agent_finish`, …). nullable: true additionalProperties: false description: >- 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. ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} ChatMessageDto: type: object properties: role: type: string description: One of "user", "assistant", "system". nullable: true content: type: string description: >- Plain-text message content. Null when the assistant message only contains tool calls. nullable: true tool_calls: type: array items: $ref: '#/components/schemas/ChatToolCallDto' description: >- Tool calls produced by the assistant this turn, bundled with their responses. nullable: true time: type: string description: >- Real wall-clock time of the message. The server stamps the messages it produces and echoes back any client-supplied value; it is used verbatim for the call transcript / post-call analysis instead of a synthesized clock. One timestamp per chat message is enough — chat messages are point-in-time events, unlike voice utterances. Optional. format: date-time nullable: true additionalProperties: false description: >- Wire-format text-chat message. Supports user / assistant / system roles. Tool invocations are bundled — a single assistant message carries the tool call(s) alongside their executed response(s) via DashaAI.BlackBox.AgentAPI.TextChat.Dtos.ChatMessageDto.ToolCalls. ChatToolCallDto: type: object properties: id: type: string description: >- Tool call identifier propagated through the OpenAI round-trip. Required. nullable: true name: type: string description: >- Tool name as registered with the agent (built-in, agent-defined function, or MCP). nullable: true arguments: description: >- Tool arguments emitted by the LLM, as a JSON object. May be omitted for tools with no parameters. response: description: >- Tool response. Set after the server executes the tool. Null while the request is still in flight (only happens internally — wire-format messages from the client always include the response). nullable: true additionalProperties: false description: >- Combined tool call: the LLM-generated request and the executed response in a single object. Wire-format choice — internally the orchestrator translates to OpenAI's split assistant/tool format. securitySchemes: ApiKey: type: http description: API Key Authentication (Bearer {key}) scheme: Bearer OAuth: type: oauth2 flows: implicit: authorizationUrl: https://auth.dasha.ai/connect/authorize scopes: platform_api: Platform API ````