Skip to main content
POST
/
api
/
v1
/
Account
/
{auth_id}
/
Call
/
{call_uuid}
/
Stream
/
Start audio stream
curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "service_url": "wss://your-server.com/ws"
}
'
{
  "stream_id": "str_XXXXXXXXXX",
  "message": "Stream started"
}
POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/
This endpoint starts a new audio stream on a call that is currently in progress. Vobiz opens a WebSocket connection to the URL you provide and begins forwarding audio frames in near real time. You can start multiple concurrent streams on the same call - each one returns its own stream_id.
REST POST .../Stream/ vs the <Stream> XML verb
  • Use REST to attach a stream to a call that is already live - for example, to start transcription after a transfer, or fork a second pipeline mid-call. It returns a stream_id you can later list, retrieve, or stop.
  • Use the <Stream> XML verb when your answer handler is setting up the call from the start. The XML verb is the path for full-duplex AI voice agents.
Both share the same WebSocket event protocol once connected (start, media, playAudio, checkpoint, clearAudio, stop). See Stream Events Overview.
Authentication required:
  • X-Auth-ID - Your account Auth ID
  • X-Auth-Token - Your account Auth Token
  • Content-Type: application/json
Important: The target WebSocket URL must be reachable from Vobiz and must accept connections over wss:// in production.

​
Path parameters

FieldTypeRequiredDescription
auth_idstringYesYour Vobiz authentication ID.
call_uuidstringYesUUID of the active call to attach the stream to.

​
Request Parameters

FieldTypeRequiredDescription
service_urlstringYesWebSocket URL (wss:// or ws://) to which Vobiz forwards the call audio. Must be reachable from the public internet; use wss:// in production.
audio_trackstringNoTrack of the call to fork to the WebSocket. One of “inbound”, “outbound”, “both”. Default: “both”. When bidirectional is true, set audio_track to “inbound” - “both”/“outbound” are not supported with bidirectional.
bidirectionalbooleanNoIf true, the WebSocket may send audio back into the call using playAudio events. Default: false.
content_typestringNoAudio encoding format. Options: “audio/x-l16;rate=8000”, “audio/x-l16;rate=16000”, “audio/x-l16;rate=24000”, or “audio/x-mulaw;rate=8000”. Default: “audio/x-l16;rate=8000”. This value is echoed back to your server in the start.mediaFormat WebSocket event - match it in every playAudio.
stream_timeoutintegerNoMaximum stream duration in seconds. Vobiz automatically stops the stream when this limit is reached. Default: 86400 (24 hours).
status_callback_urlstringNoURL invoked when the stream status changes (connected, stopped, timeout, failed).
status_callback_methodstringNoHTTP method for status_callback_url. One of “GET”, “POST”. Default: “POST”.
extra_headersstringNoComma-separated list of additional HTTP headers (header:value) sent when opening the WebSocket connection. Useful for auth tokens.
Recommendation: Use audio/x-mulaw at 8000 Hz for maximum compatibility with telephony carriers and the lowest bandwidth usage.

​
Status Callback Events

When the stream changes state, Vobiz sends a form-encoded HTTP request to your status_callback_url. The Event field is one of:
Event valueMeaning
StartStreamThe WebSocket connected and audio is being forwarded. Carries ServiceURL.
PlayedStreamAudio queued before a checkpoint finished playing. Carries Name. Only fires if playback completed.
StopStreamStreaming ended. Reliably observed only for server-initiated stops - not for caller hangup or mid-call kill.
These HTTP callbacks are a separate channel from the WebSocket events. For the exact payload fields and examples, see Status callback events.
The authoritative “call is over” signal across all termination paths (caller hangup, carrier drop, timeout, server stop) is the Event=Hangup POST to your call’s hangup_url, not StopStream. See Detecting end of stream.

​
Bidirectional Streaming

When bidirectional=true, your WebSocket server can send audio back to the call by sending a JSON message:
Send audio from WebSocket to call
{
  "event": "playAudio",
  "media": {
    "contentType": "audio/x-l16",
    "sampleRate": 8000,
    "payload": "<base64-encoded-audio>"
  }
}
FieldValues
contentTypeaudio/x-l16, audio/x-mulaw
sampleRate8000, 16000, 24000 (must match the negotiated content_type)
payloadBase64-encoded raw audio (little-endian for L16; no WAV header)
For the full bidirectional protocol - checkpoint, clearAudio (barge-in), stop, and the inbound media/start events - see Stream Events Overview and Play Audio Event.

​
Response

Returns a confirmation along with the generated stream_id.
Response - 202 Accepted
{
  "message": "audio streaming started",
  "stream_id": "728e273b-9c2c-4902-8509-2f88224cd3d5"
}

​
Example Request

cURL
curl -X POST 'https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/' \
  -H 'X-Auth-ID: {auth_id}' \
  -H 'X-Auth-Token: {auth_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "service_url": "wss://your-server.com/ws",
    "bidirectional": true,
    "audio_track": "both",
    "content_type": "audio/x-l16;rate=16000",
    "status_callback_url": "https://your-server.com/stream-status"
  }'

Authorizations

​
X-Auth-ID
string
header
required

Your Vobiz account Auth ID

​
X-Auth-Token
string
header
required

Your Vobiz account Auth Token

Path Parameters

​
auth_id
string
required

Your account Auth ID

Example:

"MA_XXXXXX"

​
call_uuid
string
required

Body

application/json
​
service_url
string
required
Example:

"wss://your-server.com/ws"

​
bidirectional
boolean
default:false
​
audio_track
enum<string>
default:both
Available options:
inbound,
outbound,
both
​
audio_format
enum<string>
default:mulaw
Available options:
pcm,
mulaw

Response

200 - application/json

Stream started