Skip to main content
Unpod can run the whole conversation for you (Realtime and WebSocket sessions: 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.
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.
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 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.
A call has at most one stream at a time.

The <Stream> verb

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 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://unpod.ai/api/v2/platform/sbc/v1, Authorization: Token and Org-Handle. 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.

WebSocket protocol

Unpod opens a WebSocket to your URL, signed with your webhook secret once your org has one, and both sides send JSON text frames. Unpod → your bot 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.
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, 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.
  • 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 signatures apart: neither can pass as the other.
With the SDK, check it before you accept the socket:
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:

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: a POST over its body, a GET over its full query string. 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. With the SDK:

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 on a failure.

Troubleshooting

Next

Pipecat bots on Unpod calls

A full voice bot on a call, with UnpodFrameSerializer.

Answer URL & XML

Every verb you can put before or after <Stream>.

Call control

Hang up, play, send digits and more on a live call.

Webhooks

Every event, its fields and how to verify it.