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

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
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.
audio_trackstringNoTrack of the call to fork to the WebSocket. One of “inbound”, “outbound”, “both”. Default: “inbound”. When bidirectional is true, only “inbound” is supported.
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”.
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 an HTTP request to your status_callback_url with the following events:
EventDescription
Stream connectedAudio streaming has started and audio is being forwarded to the WebSocket.
Stream stoppedStreaming was stopped intentionally via the API or XML.
Stream timeoutThe configured stream_timeout duration was reached.
Stream failedThe 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>"
  }
}
FieldValues
contentTypeaudio/x-l16, audio/x-mulaw
sampleRate8000, 16000
payloadBase64-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"
  }'

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