Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blackbox.dasha.ai/llms.txt

Use this file to discover all available pages before exploring further.

Reference for all WebSocket message types. Use this when building integrations to understand the exact JSON format for every message you send and receive. What you’ll learn: Base message structure, client-to-server messages, server-to-client messages, and event payloads.
Testing requires a valid API key. All examples in this section require authentication with either a web integration token or API key for Dasha BlackBox.
All WebSocket messages share these common fields:
{
  "type": "messageType",
  "timestamp": "2025-01-20T10:00:00Z",
  "channelId": null
}
FieldTypeRequiredDescription
typestringYesMessage type identifier
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoOptional channel identifier for routing

​
Client to server messages

Messages you send to the Dasha BlackBox server.
Start a new conversation with an agent. Send immediately after WebSocket connection opens.
{
  "type": "initialize",
  "timestamp": "2025-01-20T10:00:00Z",
  "request": {
    "callType": "chat",
    "additionalData": {
      "userId": "user-123",
      "context": "support"
    }
  }
}

​
WebCallStartMessage schema

FieldTypeRequiredDescription
type"initialize"YesMessage type
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoChannel identifier
requestobjectYes*Call configuration (production endpoint)
request.callType"chat" | "webCall" | "onPhone"YesType of conversation
request.additionalDataobjectNoCustom data passed to agent prompts
request.endpointstring | nullNoPhone number for onPhone calls
devRequestobjectYes*Call configuration (dev endpoint)
*Either request (production) or devRequest (development) is required, depending on which endpoint you’re using.
Send a text message to the agent during chat conversations.
{
  "type": "incomingChatMessage",
  "content": "Hello, I need help with my order",
  "timestamp": "2025-01-20T10:01:00Z"
}

​
IncomingChatMessage schema

FieldTypeRequiredDescription
type"incomingChatMessage"YesMessage type
contentstringYesText message content
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoChannel identifier
Respond to WebRTC SDP offer for voice calls. Send in response to sdpInvite message.
{
  "type": "sdpAnswer",
  "timestamp": "2025-01-20T10:00:02Z",
  "data": {
    "sdpAnswer": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\n..."
  }
}

​
SdpAnswerMessage schema

FieldTypeRequiredDescription
type"sdpAnswer"YesMessage type
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoChannel identifier
data.sdpAnswerstringYesWebRTC SDP answer string
Return the result of a tool execution requested via WebSocket. Send in response to websocketToolRequest message.
{
  "type": "websocketToolResponse",
  "timestamp": "2025-01-20T10:00:05Z",
  "content": {
    "id": "tool-request-abc123",
    "result": {
      "status": "success",
      "customer": {
        "id": "cust-456",
        "name": "John Smith",
        "email": "john@example.com"
      }
    }
  }
}

​
WebsocketToolResponseMessage schema

FieldTypeRequiredDescription
type"websocketToolResponse"YesMessage type
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoChannel identifier
content.idstringYesRequest ID from websocketToolRequest
content.resultunknownYesTool execution result (any JSON value)
End the conversation gracefully. Wait for conversationResult before closing the WebSocket.
{
  "type": "terminate",
  "timestamp": "2025-01-20T10:05:00Z"
}

​
TerminateMessage schema

FieldTypeRequiredDescription
type"terminate"YesMessage type
timestampstring (ISO 8601)YesMessage timestamp
channelIdstring | nullNoChannel identifier

​
Server to client messages

Messages you receive from the Dasha BlackBox server.
System events indicating connection state and lifecycle changes.
{
  "type": "event",
  "name": "connection",
  "timestamp": "2025-01-20T10:00:01Z",
  "data": {
    "recordId": "call-abc123",
    "endpoint": null
  }
}

​
EventHistoryMessage schema

FieldTypeDescription
type"event"Message type
namestringEvent name (see below)
timestampstring (ISO 8601)Event timestamp
channelIdstring | nullChannel identifier
data.recordIdstring | nullCall record ID
data.endpointstring | nullPhone endpoint (for onPhone calls)
data.startEstablishConnectionTimeISOstring | nullConnection start time
data.endEstablishConnectionTimeISOstring | nullConnection established time

​
Event names

EventDescriptionWhen Triggered
connectionAgent session readyAfter initialize is processed
openedConversation startedVoice call connected or chat opened
closedConversation endedAfter terminate or natural completion
failedOpenFailed to open conversationAgent unavailable, auth failed, etc.

​
text

Text messages from agent or user speech transcription. 
{
  "type": "text",
  "timestamp": "2025-01-20T10:01:05Z",
  "content": {
    "source": "assistant",
    "text": "Hello! I'd be happy to help you with your order. Could you provide your order number?",
    "name": null,
    "synthStartISOTimes": "2025-01-20T10:01:03Z",
    "synthEndISOTimes": "2025-01-20T10:01:04Z",
    "playStartISOTimes": "2025-01-20T10:01:04Z",
    "playEndISOTimes": "2025-01-20T10:01:08Z"
  }
}

{
  "type": "text",
  "timestamp": "2025-01-20T10:01:00Z",
  "content": {
    "source": "user",
    "text": "Hello, I need help with my order",
    "name": null,
    "type": "final",
    "segmentId": "seg-abc123",
    "startISOTimes": "2025-01-20T10:00:58Z",
    "endISOTimes": "2025-01-20T10:01:00Z"
  }
}

​
TextHistoryMessage schema

FieldTypeDescription
type"text"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
content.source"assistant" | "user"Message sender
content.textstring | nullMessage text content
content.namestring | nullSender name (optional)
Additional fields for assistant messages:
FieldTypeDescription
content.synthStartISOTimesstring | nullTTS synthesis start time
content.synthEndISOTimesstring | nullTTS synthesis end time
content.playStartISOTimesstring | nullAudio playback start time
content.playEndISOTimesstring | nullAudio playback end time
Additional fields for user messages:
FieldTypeDescription
content.type"potential" | "confident" | "final"Recognition confidence
content.segmentIdstringSpeech segment identifier
content.startISOTimesstringSpeech start time
content.endISOTimesstring | nullSpeech end time

​
Recognition types

TypeDescriptionUse Case
potentialLow confidence interim resultShow real-time transcription
confidentMedium confidence interim resultUpdate transcription display
finalFinal confirmed transcriptionStore in conversation history
WebRTC SDP offer for voice call setup. Respond with sdpAnswer.
{
  "type": "sdpInvite",
  "timestamp": "2025-01-20T10:00:02Z",
  "data": {
    "sdpOffer": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111\r\n..."
  }
}

​
SdpInviteMessage schema

FieldTypeDescription
type"sdpInvite"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
data.sdpOfferstringWebRTC SDP offer string
Notification that the agent is calling a tool/function.
{
  "type": "toolCall",
  "timestamp": "2025-01-20T10:02:00Z",
  "name": "lookupOrder",
  "args": {
    "orderId": "ORD-12345"
  },
  "callId": "tc-abc123",
  "startISOTimes": "2025-01-20T10:02:00Z"
}

​
ToolCallHistoryMessage schema

FieldTypeDescription
type"toolCall"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
namestringTool name
argsobjectTool arguments
callIdstringUnique call identifier
startISOTimesstring (ISO 8601)Tool call start time
Result of a tool execution.
{
  "type": "toolCallResult",
  "timestamp": "2025-01-20T10:02:03Z",
  "name": "lookupOrder",
  "callId": "tc-abc123",
  "startISOTimes": "2025-01-20T10:02:00Z",
  "endISOTimes": "2025-01-20T10:02:03Z",
  "result": {
    "orderId": "ORD-12345",
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784",
    "estimatedDelivery": "2025-01-22"
  }
}

​
ToolCallResultHistoryMessage schema

FieldTypeDescription
type"toolCallResult"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
namestringTool name
callIdstringUnique call identifier (matches toolCall)
startISOTimesstring (ISO 8601)Tool call start time
endISOTimesstring (ISO 8601)Tool call end time
resultunknownTool execution result
Request to execute a tool via WebSocket (for tools configured with WebSocket execution). Respond with websocketToolResponse.
{
  "type": "websocketToolRequest",
  "timestamp": "2025-01-20T10:02:00Z",
  "channelId": null,
  "content": {
    "id": "wtr-abc123",
    "toolName": "updateCart",
    "args": {
      "action": "add",
      "productId": "PROD-789",
      "quantity": 2
    }
  }
}

​
WebsocketToolRequestHistoryMessage schema

FieldTypeDescription
type"websocketToolRequest"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
content.idstringRequest ID (use in response)
content.toolNamestringTool name to execute
content.argsunknownTool arguments
Final conversation summary and metadata. Sent after terminate or when conversation ends.
{
  "type": "conversationResult",
  "timestamp": "2025-01-20T10:05:00Z",
  "result": {
    "status": "completed",
    "duration": 240,
    "callId": "call-abc123",
    "agentId": "agent-xyz789",
    "transcript": [
      {"role": "user", "content": "Hello, I need help with my order"},
      {"role": "assistant", "content": "Hello! I'd be happy to help you with your order..."}
    ],
    "metadata": {
      "resolvedIssue": true,
      "sentiment": "positive"
    }
  }
}

​
ConversationResultHistoryMessage schema

FieldTypeDescription
type"conversationResult"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
resultobjectConversation result payload
The result object structure depends on your agent configuration.
Error notification from the server.
{
  "type": "error",
  "timestamp": "2025-01-20T10:00:00Z",
  "channelId": null,
  "data": {
    "message": "Invalid token"
  }
}

​
ErrorHistoryMessage schema

FieldTypeDescription
type"error"Message type
timestampstring (ISO 8601)Message timestamp
channelIdstring | nullChannel identifier
data.messagestringError message

​
Common error messages

ErrorCauseResolution
Invalid tokenAuthentication failedCheck token validity in dashboard
Token expiredToken has expiredGenerate new token
Agent not foundInvalid agent referenceVerify agent ID
Rate limit exceededToo many requestsImplement backoff, reduce frequency
Connection timeoutSession timed outReconnect with new session
Invalid message formatMalformed JSONValidate message structure

​
Message flow diagrams

Use these types for type-safe message handling:
// Base message structure
interface BaseMessage {
  type: string;
  timestamp: string;
  channelId?: string | null;
}

// Client to server messages
interface InitializeMessage extends BaseMessage {
  type: 'initialize';
  request?: {
    callType: 'chat' | 'webCall' | 'onPhone';
    additionalData?: Record<string, unknown>;
    endpoint?: string | null;
  };
}

interface IncomingChatMessage extends BaseMessage {
  type: 'incomingChatMessage';
  content: string;
}

interface SdpAnswerMessage extends BaseMessage {
  type: 'sdpAnswer';
  data: { sdpAnswer: string };
}

interface WebsocketToolResponseMessage extends BaseMessage {
  type: 'websocketToolResponse';
  content: {
    id: string;
    result: unknown;
  };
}

interface TerminateMessage extends BaseMessage {
  type: 'terminate';
}

type ClientMessage =
  | InitializeMessage
  | IncomingChatMessage
  | SdpAnswerMessage
  | WebsocketToolResponseMessage
  | TerminateMessage;

// Server to client messages
interface EventMessage extends BaseMessage {
  type: 'event';
  name: 'connection' | 'opened' | 'closed' | 'failedOpen';
  data?: {
    recordId?: string | null;
    endpoint?: string | null;
  };
}

interface TextMessage extends BaseMessage {
  type: 'text';
  content: {
    source: 'assistant' | 'user';
    text: string | null;
    name?: string | null;
    type?: 'potential' | 'confident' | 'final';
    segmentId?: string;
  };
}

interface SdpInviteMessage extends BaseMessage {
  type: 'sdpInvite';
  data: { sdpOffer: string };
}

interface ToolCallMessage extends BaseMessage {
  type: 'toolCall';
  name: string;
  args: Record<string, unknown>;
  callId: string;
  startISOTimes: string;
}

interface ToolCallResultMessage extends BaseMessage {
  type: 'toolCallResult';
  name: string;
  callId: string;
  result: unknown;
  startISOTimes: string;
  endISOTimes: string;
}

interface WebsocketToolRequestMessage extends BaseMessage {
  type: 'websocketToolRequest';
  content: {
    id: string;
    toolName: string;
    args: unknown;
  };
}

interface ConversationResultMessage extends BaseMessage {
  type: 'conversationResult';
  result: Record<string, unknown>;
}

interface ErrorMessage extends BaseMessage {
  type: 'error';
  data: { message: string };
}

type ServerMessage =
  | EventMessage
  | TextMessage
  | SdpInviteMessage
  | ToolCallMessage
  | ToolCallResultMessage
  | WebsocketToolRequestMessage
  | ConversationResultMessage
  | ErrorMessage;

// Type guard helper
function isServerMessage(msg: unknown): msg is ServerMessage {
  return (
    typeof msg === 'object' &&
    msg !== null &&
    'type' in msg &&
    typeof (msg as { type: unknown }).type === 'string'
  );
}

​
Next steps

Chat Implementation

Build a complete chat interface with these messages

Tool Execution

Handle tool calls via WebSocket

Error Handling

Handle errors and edge cases

Voice Implementation

WebRTC voice call message flow