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.

Build real-time voice and chat experiences with Dasha BlackBox. WebSockets provide instant bidirectional communication with agents for browser-based voice calls, live chat, and client-side tool execution. What you’ll learn: Connection lifecycle, call types, and when to use WebSockets vs REST.
All WebSocket examples require authentication with a web integration token or API key.

Connection lifecycle

1

Connect

Establish WebSocket connection to Dasha BlackBox server
2

Authenticate

Send initialize message with call configuration
3

Communicate

Exchange messages bidirectionally (chat or voice via WebRTC)
4

Disconnect

Send terminate to end gracefully

Connection endpoints

EndpointUse caseAuth
wss://blackbox.dasha.ai/api/v1/ws/webCall?token={TOKEN}ProductionWeb integration token
wss://blackbox.dasha.ai/api/v1/ws/dev?authorization={KEY}DevelopmentAPI key
The dev endpoint requires your API key and should never be exposed in client-side code.

Call types

TypeValueUse case
Text ChatchatCustomer support, FAQ bots
Web CallwebCallBrowser-based voice support
Phone CallonPhoneOutbound campaigns, call centers

Quick start: Chat

const ws = new WebSocket(
  'wss://blackbox.dasha.ai/api/v1/ws/webCall?token=YOUR_TOKEN'
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'initialize',
    timestamp: new Date().toISOString(),
    request: { callType: 'chat', additionalData: {} }
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'text' && msg.content.source === 'assistant') {
    console.log('Agent:', msg.content.text);
  }
};

function sendMessage(text) {
  ws.send(JSON.stringify({
    type: 'incomingChatMessage',
    content: text,
    timestamp: new Date().toISOString()
  }));
}

When to use WebSockets vs REST

Use WebSockets for:
  • Real-time chat conversations
  • Browser-based voice calls (WebRTC)
  • Tool execution with immediate results
Use REST API for:
  • Creating and configuring agents
  • Enqueueing outbound phone calls
  • Fetching call history and results
Most applications use both: REST for setup, WebSockets for runtime communication.

Message types

Client → Server

TypeDescription
initializeStart conversation
incomingChatMessageSend text message
sdpAnswerWebRTC SDP answer
websocketToolResponseTool execution result
terminateEnd conversation

Server → Client

TypeDescription
eventConnection lifecycle events
textAgent responses
sdpInviteWebRTC SDP offer
websocketToolRequestTool execution request
conversationResultConversation summary
errorError notification

Message Reference

Complete schema documentation

What’s next

Chat Implementation

Build a complete text chat interface

Voice Call Implementation

Add WebRTC voice calls

Message Reference

Complete message schemas

Tool Execution

Handle agent tool calls