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 outbound
audio
Unpod<Stream> or REST
signed WebSocket
Your botAny language
Unpod runs itYou run itOutside Unpod
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.UnpodFrameSerializer does the protocol below for you.
Start a stream
There are two ways:- From your answer URL. Reply to
StartAppwith a<Stream>verb (below). Works for inbound calls and for calls you place withcalls.create(answer_url=...). - On a live call, over REST.
POST /calls/{id}/streamstarts a stream on a call that is already up, for example halfway through. See REST stream API.
The <Stream> verb
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.
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
stopframe: Unpod ends the stream by closing the socket with code1000, or1009when your bot sent a frame over 64 KB. - To end the stream from the bot, close with
1000,1001or no code (completed). Any other code ends itfailedwithconnection_dropped. start.callIdis the id the call APIs take, for example to hang up from the bot withcalls.hangup(call_id). It is not a UUID.- The audio you receive is in
start.mediaFormat.playAudioneed 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 asverify_stream_request rejects it.
urlis the URL exactly as Unpod dialled it,wss://host/path?query.- Reject the upgrade when
tis more than 300 seconds from now. To block replays, remember eachnfor 10 minutes and reject one you have seen. - The header carries one
v1today.verify_stream_requestalso accepts several and passes if any matches. - The
ws.prefix keeps stream and webhook signatures apart: neither can pass as the other.
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
WithstatusCallbackUrl 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;
extraHeadersat most 512 bytes. - A frame over 64 KB ends the stream (
message_too_large); Unpod closes the socket with1009. - A bot that keeps falling behind gets
degradedwarnings after 12, 24 and 36 s without a successful write, then the stream fails withslow_connectionat 40 s. - About 40 s of
playAudiocan wait to play; more is dropped (degradedwithbuffer_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.