> ## 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.

# Build Real-Time Voice and Chat Experiences

> Build real-time voice and chat experiences with AI agents using WebSocket connections for instant bidirectional communication.

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.

<Note>
  All WebSocket examples require authentication with a web integration token or API key.
</Note>

***

## Connection lifecycle

<Steps>
  <Step title="Connect">
    Establish WebSocket connection to Dasha BlackBox server
  </Step>

  <Step title="Authenticate">
    Send `initialize` message with call configuration
  </Step>

  <Step title="Communicate">
    Exchange messages bidirectionally (chat or voice via WebRTC)
  </Step>

  <Step title="Disconnect">
    Send `terminate` to end gracefully
  </Step>
</Steps>

***

## Connection endpoints

| Endpoint                                                    | Use case    | Auth                  |
| ----------------------------------------------------------- | ----------- | --------------------- |
| `wss://blackbox.dasha.ai/api/v1/ws/webCall?token={TOKEN}`   | Production  | Web integration token |
| `wss://blackbox.dasha.ai/api/v1/ws/dev?authorization={KEY}` | Development | API key               |

<Warning>
  The dev endpoint requires your API key and should never be exposed in client-side code.
</Warning>

***

## Call types

| Type           | Value     | Use case                         |
| -------------- | --------- | -------------------------------- |
| **Text Chat**  | `chat`    | Customer support, FAQ bots       |
| **Web Call**   | `webCall` | Browser-based voice support      |
| **Phone Call** | `onPhone` | Outbound campaigns, call centers |

***

## Quick start: Chat

<Accordion title="Example: Basic chat connection">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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()
    }));
  }
  ```
</Accordion>

***

## 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

| Type                    | Description           |
| ----------------------- | --------------------- |
| `initialize`            | Start conversation    |
| `incomingChatMessage`   | Send text message     |
| `sdpAnswer`             | WebRTC SDP answer     |
| `websocketToolResponse` | Tool execution result |
| `terminate`             | End conversation      |

### Server → Client

| Type                   | Description                 |
| ---------------------- | --------------------------- |
| `event`                | Connection lifecycle events |
| `text`                 | Agent responses             |
| `sdpInvite`            | WebRTC SDP offer            |
| `websocketToolRequest` | Tool execution request      |
| `conversationResult`   | Conversation summary        |
| `error`                | Error notification          |

<Card title="Message Reference" icon="book" href="/docs/websockets/message-reference">
  Complete schema documentation
</Card>

***

## What's next

<CardGroup cols={2}>
  <Card title="Chat Implementation" icon="comments" href="/docs/websockets/chat-implementation">
    Build a complete text chat interface
  </Card>

  <Card title="Voice Call Implementation" icon="phone" href="/docs/websockets/voice-call-implementation">
    Add WebRTC voice calls
  </Card>

  <Card title="Message Reference" icon="book" href="/docs/websockets/message-reference">
    Complete message schemas
  </Card>

  <Card title="Tool Execution" icon="wrench" href="/docs/websockets/tool-execution">
    Handle agent tool calls
  </Card>
</CardGroup>