Start an Audio Stream

Begin streaming audio from an active call to your WebSocket server with configurable tracks, codecs, and bidirectional mode.

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.

Important: The target WebSocket URL must be reachable from Vobiz and must accept connections over wss:// in production.

HTTP Request

POSThttps://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Path Parameters

auth_idstringRequired

Your Vobiz authentication ID.

call_uuidstringRequired

UUID of the active call to attach the stream to.

Request Parameters

Parameter	Type	Description
`service_url`required	string	WebSocket URL (wss:// or ws://) to which Vobiz forwards the call audio. Must be reachable from the public internet.
`audio_track`optional	string	Track of the call to fork to the WebSocket. One of "inbound", "outbound", "both". Default: "inbound". When bidirectional is true, only "inbound" is supported.
`bidirectional`optional	boolean	If true, the WebSocket may send audio back into the call using playAudio events. Default: false.
`content_type`optional	string	Audio 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".
`stream_timeout`optional	integer	Maximum stream duration in seconds. Vobiz automatically stops the stream when this limit is reached. Default: 86400 (24 hours).
`status_callback_url`optional	string	URL invoked when the stream status changes (connected, stopped, timeout, failed).
`status_callback_method`optional	string	HTTP method for status_callback_url. One of "GET", "POST". Default: "POST".
`extra_headers`optional	string	Comma-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 an HTTP request to your status_callback_url with the following events:

Event	Description
Stream connected	Audio streaming has started and audio is being forwarded to the WebSocket.
Stream stopped	Streaming was stopped intentionally via the API or XML.
Stream timeout	The configured `stream_timeout` duration was reached.
Stream failed	The WebSocket connection failed or was dropped unexpectedly.

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>"
  }
}

Field	Values
contentType	audio/x-l16, audio/x-mulaw
sampleRate	8000, 16000
payload	Base64-encoded raw audio

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"
  }'

The Stream Object

Retrieve an Audio Stream