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

# Audio Streaming

> Stream a call's raw audio to your own WebSocket and play your bot's audio back: the <Stream> verb, the REST stream API, the WebSocket protocol and its signature.

Unpod can run the whole conversation for you ([Realtime](https://docs.unpod.ai/telephony/streaming/unpod-speech-quickstart.md)
and [WebSocket sessions](https://docs.unpod.ai/telephony/streaming/websocket.md): Unpod does STT, VAD, barge-in and
TTS, and your code sees only text). Audio streaming is the other way round: Unpod sends the
call's audio to your WebSocket, 20 ms at a time, and plays back the audio your bot returns.
You bring the speech pipeline.

| | Realtime / WebSocket sessions | Audio streaming |
| - | - | - |
| Who runs STT, VAD, TTS | Unpod | You |
| Your code sees | Text | Audio frames |
| How a call reaches it | Number attached to an agent | `<Stream>` in your answer URL reply, or the REST stream API |

> [!NOTE]
>
> **Preview.** Audio streaming is off by default. Your org needs the Call API switched on
> (otherwise `403 call_api_disabled`) **and** audio streaming switched on. Ask the Unpod team
> to enable both. While streaming is off, a `<Stream>` verb is skipped and the call carries on
> with the rest of your reply, and the REST stream API returns `403 audio_stream_disabled`.

Audio streaming

CallInbound or outboundaudioUnpod\<Stream> or RESTsigned WebSocketYour botAny language

Unpod runs itYou run itOutside Unpod

> [!NOTE]
>
> The Python SDK pieces on this page (`Answer().stream()`, `calls.start_stream()`,
> `verify_stream_request`, `UnpodFrameSerializer`) ship in `unpod` 0.7.0
> (`pip install "unpod>=0.7.0"`). The HTTP API, the `<Stream>` verb and the WebSocket protocol
> work from any language.

Building with Pipecat? [Pipecat bots on Unpod calls](https://docs.unpod.ai/telephony/integrations/pipecat#your-pipecat-bot-on-an-unpod-call)
is a full walkthrough: `UnpodFrameSerializer` does the protocol below for you.

## Start a stream

There are two ways:

* **From your answer URL.** Reply to `StartApp` with a `<Stream>` verb (below). Works for
  inbound calls and for calls you place with `calls.create(answer_url=...)`.
* **On a live call, over REST.** `POST /calls/{id}/stream` starts a stream on a call that is
  already up, for example halfway through. See [REST stream API](#rest-stream-api).

A call has at most one stream at a time.

## The `<Stream>` verb

```xml XML theme={null}
<Response>
    <Stream bidirectional="true" keepCallAlive="true" audioTrack="inbound"
            contentType="audio/x-mulaw;rate=8000">wss://bot.example.com/ws</Stream>
</Response>
```

```json JSON theme={null}
{"actions": [{"type": "stream", "url": "wss://bot.example.com/ws",
              "bidirectional": true, "keep_call_alive": true, "audio_track": "inbound",
              "content_type": "audio/x-mulaw;rate=8000"}]}
```

```python Python SDK theme={null}
from unpod.telephony.answer import Response as Answer

Answer().stream("wss://bot.example.com/ws").to_xml()   # or .to_json()
```

| XML | JSON | Default when left out | Notes |
| - | - | - | - |
| element text | `url` | - | `ws://` or `wss://`, at most 2048 characters, with no user or password in it, and not `localhost` or a private address. The path and query reach your bot, so you can put a per-call token in them. Unpod dials and signs the normalised URL: lowercase host, default port dropped, `/` for an empty path |
| `bidirectional` | `bidirectional` | `false` | `true` lets the bot play audio back. Then `audioTrack` must be `inbound` |
| `audioTrack` | `audio_track` | `inbound` | What the bot hears: `inbound` (the caller), `outbound` (what Unpod plays to the caller) or `both` |
| `contentType` | `content_type` | `audio/x-l16;rate=8000` | `audio/x-mulaw;rate=8000`, `audio/x-alaw;rate=8000`, or `audio/x-l16;rate=8000`, `16000` or `24000`. The rate is part of the content type |
| `keepCallAlive` | `keep_call_alive` | `false` | `true`: the call waits on the stream until the bot closes it. `false`: the stream runs in the background and the next verb runs at once; with no next verb the call ends (`End Of XML Instructions`) |
| `streamTimeout` | `stream_timeout` | `86400` | Seconds from `started` until Unpod stops the stream. At least 1 |
| `extraHeaders` | `extra_headers` | - | `key=value,key2=value2` (`,` or `;` between pairs). Keys and values are letters, digits, `_` and `-` only; at most 512 bytes in all. Sent to your bot in the `start`, `media` and `dtmf` frames and in the status callbacks |
| `statusCallbackUrl` | `status_callback_url` | - | Where [status callbacks](#status-callbacks) go: a public `http` or `https` URL. **Without it there are no stream callbacks** |
| `statusCallbackMethod` | `status_callback_method` | `POST` | `POST` or `GET` |
| `noiseCancellation`, `noiseCancellationLevel` | `noise_cancellation`, `noise_cancellation_level` | - | Accepted and checked (level 60-100) but **not applied yet** |

> [!TIP]
>
> The SDK's `Answer().stream(url)` is set up for a voice bot: it sends `bidirectional="true"`,
> `keepCallAlive="true"`, `audioTrack="inbound"` and μ-law at 8000 Hz unless you pass
> `bidirectional=`, `keep_call_alive=`, `audio_track=`, `content_type=` / `sample_rate=`.
> It also takes `stream_timeout=`, `status_callback_url=`, `status_callback_method=`,
> `extra_headers=` (a string or a dict), `noise_cancellation=` and `noise_cancellation_level=`,
> and checks them the same way Unpod does.

Verbs after `<Stream>` run once the stream ends (with `keepCallAlive="true"`, when your bot
closes the socket), for example a `<Dial>` to hand the caller to a person. See
[Answer URL & XML](https://docs.unpod.ai/telephony/apis/answer-url.md) for every verb.

A `<Stream>` that comes while a background stream is still running stops that stream first.
It ends `stopped` with `completed`.

## REST stream API

Start, list and stop streams on a live call. Same host and headers as the other
[call APIs](https://docs.unpod.ai/telephony/apis/call-control.md): `https://unpod.ai/api/v2/platform/sbc/v1`,
`Authorization: Token` and `Org-Handle`.

| Method and path | Does | Returns |
| - | - | - |
| `POST /calls/{id}/stream` | Start a stream | `202 {"stream_id", "message"}`. `400` ("a stream is already active") when the call already has one; `400 invalid_url` for a bad `service_url` |
| `GET /calls/{id}/stream` | Every stream the call has had | `{"streams": [...]}` |
| `GET /calls/{id}/stream/{stream_id}` | One stream | The stream object below. `404` for an unknown `stream_id` |
| `DELETE /calls/{id}/stream` | Stop the active stream | `204`. The stream ends with `api_request`; the call carries on. `400` ("no active stream") when none is running |
| `DELETE /calls/{id}/stream/{stream_id}` | Stop that stream | `204`. `400` ("no active stream") for an unknown or ended `stream_id` |

Every route returns `404` for an unknown call or one that is ending, `503` while the call's
media is degraded, and `409` for any other refusal.

The `POST` body takes the snake\_case keys from the `<Stream>` table, with `service_url` in
place of `url`. The noise-cancellation keys are not taken over REST.

A stream object has `stream_id`, `call_uuid`, `service_url`, `status` (`in-progress`,
`stopped` or `failed`), `bidirectional`, `audio_track`, `content_type`, `start_time`,
`end_time`, `duration` (seconds) and `status_reason`.

```python Python theme={null}
import asyncio
from unpod import AsyncClient

async def main():
    async with AsyncClient() as client:
        calls = client.telephony.calls
        started = await calls.start_stream(
            "CALL_ID",
            "wss://bot.example.com/ws",
            bidirectional=True,
            content_type="audio/x-mulaw;rate=8000",
            status_callback_url="https://app.example.com/stream-events",
        )
        print(started.stream_id)

        for s in await calls.list_streams("CALL_ID"):
            print(s.stream_id, s.status, s.status_reason)

        await calls.stop_stream("CALL_ID")  # the call carries on

asyncio.run(main())
```

```bash cURL theme={null}
curl -s -X POST "https://unpod.ai/api/v2/platform/sbc/v1/calls/CALL_ID/stream" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE" \
  -H "Content-Type: application/json" \
  -d '{"service_url": "wss://bot.example.com/ws", "bidirectional": true,
       "content_type": "audio/x-mulaw;rate=8000",
       "status_callback_url": "https://app.example.com/stream-events"}'

curl -s -X DELETE "https://unpod.ai/api/v2/platform/sbc/v1/calls/CALL_ID/stream" \
  -H "Authorization: Token $UNPOD_PLATFORM_TOKEN" -H "Org-Handle: $UNPOD_ORG_HANDLE"
```

## WebSocket protocol

Unpod opens a WebSocket to your URL, signed with your [webhook secret](#verify-the-stream-signature)
once your org has one, and both sides send JSON text frames.

**Unpod → your bot**

| Event | Carries |
| - | - |
| `start` | First frame. `start.callId`, `start.streamId`, `start.accountId` (your org), `start.tracks`, `start.mediaFormat {encoding, sampleRate}` |
| `media` | `media.track`, `media.timestamp` (Unix ms, as a string), `media.chunk`, `media.payload` (base64 audio, about 20 ms) |
| `dtmf` | `dtmf.digit`, `dtmf.track` (`inbound`), `dtmf.timestamp` (Unix ms, as a string): the caller pressed a key. The same digit twice within 150 ms is sent once |
| `playedStream` | `name`: every audio frame you sent before that `checkpoint` has played |
| `clearedAudio` | Reply to your `clearAudio` |

Every frame has `sequenceNumber`. `media` and `dtmf` also have `streamId` and a top-level
`extra_headers` string (your `extraHeaders`). `start` has `extra_headers` too, but its stream
id is `start.streamId`, not a top-level `streamId`. `playedStream` and `clearedAudio` carry
only `event`, `sequenceNumber` and `streamId` (plus `name` on `playedStream`).

**Your bot → Unpod**

Unpod ignores all of these unless the stream is `bidirectional`.

| Event | Carries |
| - | - |
| `playAudio` | `media {contentType, sampleRate, payload}`. μ-law or A-law at 8000 Hz, or L16 (little-endian) at 8000-48000 Hz, whatever the stream's `contentType`: Unpod resamples it. Without `contentType`, the stream's encoding. Any other format is dropped |
| `clearAudio` | Drop the audio still queued to play (the caller barged in). Pending checkpoints get no `playedStream` |
| `checkpoint` | `name` (up to 256 bytes). Unpod answers with `playedStream` once everything before it has played. A longer name, or one past 256 pending checkpoints, is dropped without a reply |
| `sendDTMF` | `dtmf`: digits `0-9`, `A-D` (or `a-d`), `*`, `#`, played 250 ms apart to the call's party: the callee on a call you placed with `calls.create`, otherwise the caller. At most 32 queued and 256 per stream; extra digits are dropped without an error |

```json theme={null}
{"event": "start", "sequenceNumber": 1, "extra_headers": "",
 "start": {"callId": "<call id>", "streamId": "<uuid>", "accountId": "<org id>",
           "tracks": ["inbound"], "mediaFormat": {"encoding": "audio/x-mulaw", "sampleRate": 8000}}}

{"event": "media", "sequenceNumber": 2, "streamId": "<uuid>", "extra_headers": "",
 "media": {"track": "inbound", "timestamp": "1763380000000", "chunk": 1, "payload": "<base64>"}}

{"event": "playAudio", "streamId": "<uuid>",
 "media": {"contentType": "audio/x-mulaw", "sampleRate": 8000, "payload": "<base64>"}}

{"event": "checkpoint", "streamId": "<uuid>", "name": "greeting-done"}
```

The SDK builds and reads these frames for you in `unpod.telephony.stream`: `parse_start()`
reads `start` (`call_id`, `stream_id`, `account_id`, `media_format`, `extra_headers`), and
`play_audio_message()`, `clear_audio_message()`, `checkpoint_message()` and
`send_dtmf_message()` build the bot's frames. Only `checkpoint_message()` and
`send_dtmf_message()` check the limits above. `checkpoint_message()` counts characters, not
bytes, so keep names with multibyte characters well under 256.

* There is no `stop` frame: Unpod ends the stream by closing the socket with code `1000`,
  or `1009` when your bot sent a frame over 64 KB.
* To end the stream from the bot, close with `1000`, `1001` or no code (`completed`). Any
  other code ends it `failed` with `connection_dropped`.
* `start.callId` is the id the call APIs take, for example to hang up from the bot with
  `calls.hangup(call_id)`. It is not a UUID.
* The audio you receive is in `start.mediaFormat`. `playAudio` need not match it: Unpod
  resamples any format from the table above.

## Verify the stream signature

Once your org has a [webhook secret](https://docs.unpod.ai/telephony/apis/incoming-calls.md#the-webhook-secret),
Unpod signs every stream WebSocket upgrade with it, in one header. Until then the upgrade is
unsigned, and a verifier such as `verify_stream_request` rejects it.

```
X-Unpod-Signature: t=<unix seconds>,n=<nonce>,v1=<hex>
v1 = hex(HMAC-SHA256(webhook secret, "ws." + t + "." + n + "." + url))
```

* `url` is the URL exactly as Unpod dialled it, `wss://host/path?query`.
* Reject the upgrade when `t` is more than 300 seconds from now. To block replays, remember
  each `n` for 10 minutes and reject one you have seen.
* The header carries one `v1` today. `verify_stream_request` also accepts several and passes
  if any matches.
* The `ws.` prefix keeps stream and [webhook](https://docs.unpod.ai/telephony/apis/webhooks.md) signatures apart:
  neither can pass as the other.

With the SDK, check it before you accept the socket:

```python theme={null}
import os

from unpod.pipecat import verify_stream_request
from unpod.telephony.stream import NonceCache

NONCES = NonceCache()  # one per process, shared by your handlers

ok = verify_stream_request(
    websocket.headers,
    os.environ["UNPOD_WEBHOOK_SECRET"],
    url=str(websocket.url),
    public_base="wss://bot.example.com",  # behind a proxy or tunnel
    nonce_cache=NONCES,
)
```

Behind a proxy or tunnel your server sees its own host and often `ws://`, so pass
`public_base`: the host is taken from it, never from request headers.

Without the SDK (any language), the same check:

```python theme={null}
import hashlib, hmac, time

def verify(header: str, secret: str, url: str) -> bool:
    parts = [p.strip().partition("=")[::2] for p in header.split(",")]
    t = next((v for k, v in parts if k == "t"), "")
    n = next((v for k, v in parts if k == "n"), "")
    sigs = [v.lower() for k, v in parts if k == "v1" and v]
    if not (t.isdigit() and n and sigs) or abs(time.time() - int(t)) > 300:
        return False
    want = hmac.new(secret.encode(), f"ws.{t}.{n}.{url}".encode(), hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(want, s) for s in sigs)
```

## Status callbacks

With `statusCallbackUrl` set, Unpod posts stream events there (form fields; with
`statusCallbackMethod="GET"`, query parameters). Once your org has a webhook secret they are
signed with `X-Webhook-Signature` like every other [webhook](https://docs.unpod.ai/telephony/apis/webhooks.md): a
POST over its body, a GET over its full query string.

| `Event` | When |
| - | - |
| `started` | Your bot accepted the socket |
| `stopped` | The stream ended normally |
| `failed` | The stream could not start, or broke |
| `degraded` | Warning: your bot is reading audio too slowly, or the playback queue is full. The stream keeps running |

Fields: `Event`, `CallUUID`, `StreamID`, `Timestamp` (ISO 8601), `From`, `To`, `Direction`,
`ServiceURL` (without its query), `ExtraHeaders`; plus `StatusReason` on every event except
`started`, `Duration` on `stopped` and `failed`, and `Error` on `failed`.

| `Event` | `StatusReason` |
| - | - |
| `stopped` | `completed`, `api_request` (REST `DELETE`), `stream_timeout`, `call_hangup` |
| `failed` | `start_failed`, `connection_failed`, `authentication_failed`, `connection_dropped`, `slow_connection`, `message_too_large` |
| `degraded` | `slow_connection_30`, `slow_connection_60`, `slow_connection_90`: 12, 24 and 36 s without a successful write to your bot. `buffer_overflow`: the playback queue (about 40 s of audio) is full and `playAudio` is dropped; sent once, then again only after a `playAudio` is accepted |

With the SDK:

```python theme={null}
from unpod.telephony import STREAM_EVENTS, parse_call_event

ev = parse_call_event(body, headers, secret=SECRET)
if ev.event in STREAM_EVENTS:
    print(ev.event, ev.stream_id, ev.stream_reason, ev.service_url, ev.error, ev.event_time)
```

## Limits

* One stream per call at a time.
* The URL is at most 2048 characters; `extraHeaders` at most 512 bytes.
* A frame over 64 KB ends the stream (`message_too_large`); Unpod closes the socket with `1009`.
* A bot that keeps falling behind gets `degraded` warnings after 12, 24 and 36 s without a
  successful write, then the stream fails with `slow_connection` at 40 s.
* About 40 s of `playAudio` can wait to play; more is dropped (`degraded` with
  `buffer_overflow`).
* Noise cancellation is accepted but not applied yet.
* The answer URL rules still apply: public https, 3000 ms to reply, and the
  [fallback](https://docs.unpod.ai/telephony/apis/answer-url.md#timeouts-and-fallback) on a failure.

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| Answer URL hit, no WebSocket | Audio streaming is off for your org: ask the Unpod team. Or the stream URL isn't a public `ws://` / `wss://` host |
| `failed` with `authentication_failed` | Your server rejected the upgrade: wrong secret, wrong `url` / `public_base`, or a clock more than 300 s off |
| Call ends the moment it is answered | `keepCallAlive` left at `false` with nothing after `<Stream>` |
| Fallback instead of streaming | The reply didn't parse (bad `contentType`, `bidirectional` with a track other than `inbound`), a non-2xx status, or no reply within 3000 ms |
| Bot hears noise | Your code decodes a different format than `start.mediaFormat` |
| Caller hears nothing | `bidirectional` is off, or `playAudio` is in an unsupported format: μ-law or A-law not at 8000 Hz, or L16 outside 8000-48000 Hz or big-endian |
| No stream callbacks | No `statusCallbackUrl` on the stream |

## Next

> [card] [Pipecat bots on Unpod calls](https://docs.unpod.ai/telephony/integrations/pipecat#your-pipecat-bot-on-an-unpod-call)
>
> A full voice bot on a call, with `UnpodFrameSerializer`.

> [card] [Answer URL & XML](https://docs.unpod.ai/telephony/apis/answer-url.md)
>
> Every verb you can put before or after `<Stream>`.

> [card] [Call control](https://docs.unpod.ai/telephony/apis/call-control.md)
>
> Hang up, play, send digits and more on a live call.

> [card] [Webhooks](https://docs.unpod.ai/telephony/apis/webhooks.md)
>
> Every event, its fields and how to verify it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.