> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boson.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Build realtime voice assistants over WebSocket with streaming audio, text, turn detection, and tool calling.

The Realtime API enables real-time bidirectional voice communication over WebSocket (WebRTC support is in progress). Stream audio and text both ways for voice assistants, phone agents, and interactive voice systems: the model listens and speaks natively in a single full-duplex session — no separate transcription or synthesis steps to manage.

```text Model theme={null}
higgs-realtime
```

```text WebSocket endpoint theme={null}
wss://api.boson.ai/v1/realtime
```

## Quickstart

Connect, configure the session, send a text message, and play the model's spoken reply through your speakers:

```python theme={null}
# pip install websockets sounddevice
import asyncio
import base64
import json
import os
import sounddevice as sd
import websockets

async def voice_agent():
    # Speaker output matching the default audio format: 24 kHz, 16-bit, mono PCM
    speaker = sd.RawOutputStream(samplerate=24000, channels=1, dtype="int16")
    speaker.start()

    async with websockets.connect(
        "wss://api.boson.ai/v1/realtime",
        additional_headers={"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"}
    ) as ws:
        # Configure session
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "model": "higgs-realtime",
                "instructions": "You are a helpful assistant.",
                "audio": {
                    "input": {"turn_detection": {"type": "server_vad"}},
                    "output": {"voice": "default"}
                }
            }
        }))

        # Send a text message
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {"type": "message", "role": "user",
                     "content": [{"type": "input_text", "text": "Hello!"}]}
        }))
        await ws.send(json.dumps({"type": "response.create"}))

        # Play audio responses as they stream in
        async for msg in ws:
            event = json.loads(msg)
            if event["type"] == "response.output_audio.delta":
                speaker.write(base64.b64decode(event["delta"]))
            elif event["type"] == "response.output_audio_transcript.done":
                print("Assistant:", event["transcript"])
            elif event["type"] == "response.done":
                break

    speaker.stop()

asyncio.run(voice_agent())
```

The reply arrives as a stream of `response.output_audio.delta` events (base64 24 kHz 16-bit mono PCM) alongside `response.output_audio_transcript.delta` text, ending with `response.done`. To talk instead of type, stream microphone audio with `input_audio_buffer.append` — with `server_vad` turn detection the model detects when you stop speaking and responds on its own, no `response.create` needed.

For browser apps, don't ship your API key: mint a short-lived key with `POST /v1/realtime/client_secrets` and connect with the `bai-client-secret.<key>` subprotocol (see [Authentication](/models/higgs-realtime/guides/connections-and-sessions#authentication)).