WebSocket Message Types and Schemas - Dasha BlackBox Documentation

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.

Base message structure

All WebSocket messages share these common fields:

{
  "type": "messageType",
  "timestamp": "2025-01-20T10:00:00Z",
  "channelId": null
}

Field	Type	Required	Description
`type`	`string`	Yes	Message type identifier
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Optional channel identifier for routing

Client to server messages

Messages you send to the Dasha BlackBox server.

initialize

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

Field	Type	Required	Description
`type`	`"initialize"`	Yes	Message type
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Channel identifier
`request`	`object`	Yes*	Call configuration (production endpoint)
`request.callType`	`"chat" \| "webCall" \| "onPhone"`	Yes	Type of conversation
`request.additionalData`	`object`	No	Custom data passed to agent prompts
`request.endpoint`	`string \| null`	No	Phone number for `onPhone` calls
`devRequest`	`object`	Yes*	Call configuration (dev endpoint)

*Either request (production) or devRequest (development) is required, depending on which endpoint you’re using.

incomingChatMessage

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

Field	Type	Required	Description
`type`	`"incomingChatMessage"`	Yes	Message type
`content`	`string`	Yes	Text message content
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Channel identifier

sdpAnswer

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

Field	Type	Required	Description
`type`	`"sdpAnswer"`	Yes	Message type
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Channel identifier
`data.sdpAnswer`	`string`	Yes	WebRTC SDP answer string

websocketToolResponse

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

Field	Type	Required	Description
`type`	`"websocketToolResponse"`	Yes	Message type
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Channel identifier
`content.id`	`string`	Yes	Request ID from `websocketToolRequest`
`content.result`	`unknown`	Yes	Tool execution result (any JSON value)

terminate

End the conversation gracefully. Wait for conversationResult before closing the WebSocket.

{
  "type": "terminate",
  "timestamp": "2025-01-20T10:05:00Z"
}

TerminateMessage schema

Field	Type	Required	Description
`type`	`"terminate"`	Yes	Message type
`timestamp`	`string` (ISO 8601)	Yes	Message timestamp
`channelId`	`string \| null`	No	Channel identifier

Server to client messages

Messages you receive from the Dasha BlackBox server.

event

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

Field	Type	Description
`type`	`"event"`	Message type
`name`	`string`	Event name (see below)
`timestamp`	`string` (ISO 8601)	Event timestamp
`channelId`	`string \| null`	Channel identifier
`data.recordId`	`string \| null`	Call record ID
`data.endpoint`	`string \| null`	Phone endpoint (for `onPhone` calls)
`data.startEstablishConnectionTimeISO`	`string \| null`	Connection start time
`data.endEstablishConnectionTimeISO`	`string \| null`	Connection established time

Event names

Event	Description	When Triggered
`connection`	Agent session ready	After `initialize` is processed
`opened`	Conversation started	Voice call connected or chat opened
`closed`	Conversation ended	After `terminate` or natural completion
`failedOpen`	Failed to open conversation	Agent unavailable, auth failed, etc.

text

Text messages from agent or user speech transcription.

Agent response

{
  "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"
  }
}

User message (echo/transcription)

{
  "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

Field	Type	Description
`type`	`"text"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`content.source`	`"assistant" \| "user"`	Message sender
`content.text`	`string \| null`	Message text content
`content.name`	`string \| null`	Sender name (optional)

Additional fields for assistant messages:

Field	Type	Description
`content.synthStartISOTimes`	`string \| null`	TTS synthesis start time
`content.synthEndISOTimes`	`string \| null`	TTS synthesis end time
`content.playStartISOTimes`	`string \| null`	Audio playback start time
`content.playEndISOTimes`	`string \| null`	Audio playback end time

Additional fields for user messages:

Field	Type	Description
`content.type`	`"potential" \| "confident" \| "final"`	Recognition confidence
`content.segmentId`	`string`	Speech segment identifier
`content.startISOTimes`	`string`	Speech start time
`content.endISOTimes`	`string \| null`	Speech end time

Recognition types

Type	Description	Use Case
`potential`	Low confidence interim result	Show real-time transcription
`confident`	Medium confidence interim result	Update transcription display
`final`	Final confirmed transcription	Store in conversation history

sdpInvite

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

Field	Type	Description
`type`	`"sdpInvite"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`data.sdpOffer`	`string`	WebRTC SDP offer string

toolCall

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

Field	Type	Description
`type`	`"toolCall"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`name`	`string`	Tool name
`args`	`object`	Tool arguments
`callId`	`string`	Unique call identifier
`startISOTimes`	`string` (ISO 8601)	Tool call start time

toolCallResult

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

Field	Type	Description
`type`	`"toolCallResult"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`name`	`string`	Tool name
`callId`	`string`	Unique call identifier (matches `toolCall`)
`startISOTimes`	`string` (ISO 8601)	Tool call start time
`endISOTimes`	`string` (ISO 8601)	Tool call end time
`result`	`unknown`	Tool execution result

websocketToolRequest

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

Field	Type	Description
`type`	`"websocketToolRequest"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`content.id`	`string`	Request ID (use in response)
`content.toolName`	`string`	Tool name to execute
`content.args`	`unknown`	Tool arguments

conversationResult

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

Field	Type	Description
`type`	`"conversationResult"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`result`	`object`	Conversation result payload

The result object structure depends on your agent configuration.

error

Error notification from the server.

{
  "type": "error",
  "timestamp": "2025-01-20T10:00:00Z",
  "channelId": null,
  "data": {
    "message": "Invalid token"
  }
}

ErrorHistoryMessage schema

Field	Type	Description
`type`	`"error"`	Message type
`timestamp`	`string` (ISO 8601)	Message timestamp
`channelId`	`string \| null`	Channel identifier
`data.message`	`string`	Error message

Common error messages

Error	Cause	Resolution
`Invalid token`	Authentication failed	Check token validity in dashboard
`Token expired`	Token has expired	Generate new token
`Agent not found`	Invalid agent reference	Verify agent ID
`Rate limit exceeded`	Too many requests	Implement backoff, reduce frequency
`Connection timeout`	Session timed out	Reconnect with new session
`Invalid message format`	Malformed JSON	Validate message structure

Message flow diagrams

Chat conversation

Voice call

Tool execution via WebSocket

TypeScript types

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

Documentation Index

​Client to server messages

​WebCallStartMessage schema

​IncomingChatMessage schema

​SdpAnswerMessage schema

​WebsocketToolResponseMessage schema

​TerminateMessage schema

​Server to client messages

​EventHistoryMessage schema

​Event names

​text

​TextHistoryMessage schema

​Recognition types

​SdpInviteMessage schema

​ToolCallHistoryMessage schema

​ToolCallResultHistoryMessage schema

​WebsocketToolRequestHistoryMessage schema

​ConversationResultHistoryMessage schema

​ErrorHistoryMessage schema

​Common error messages

​Message flow diagrams

​Next steps

Chat Implementation

Tool Execution

Error Handling

Voice Implementation

Client to server messages

WebCallStartMessage schema

IncomingChatMessage schema

SdpAnswerMessage schema

WebsocketToolResponseMessage schema

TerminateMessage schema

Server to client messages

EventHistoryMessage schema

Event names

text

TextHistoryMessage schema

Recognition types

SdpInviteMessage schema

ToolCallHistoryMessage schema

ToolCallResultHistoryMessage schema

WebsocketToolRequestHistoryMessage schema

ConversationResultHistoryMessage schema

ErrorHistoryMessage schema

Common error messages

Message flow diagrams

Next steps