Start an Audio Stream

POST

api

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

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/"

payload = { "service_url": "wss://your-server.com/ws" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({service_url: 'wss://your-server.com/ws'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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.

On this REST route, bidirectional must be the string "true". A JSON boolean true is accepted and silently produces a one-way stream - no error, no warning, and your playAudio events are discarded. The <Stream> XML verb accepts either form; this route does not.

"bidirectional": "true"     // correct
"bidirectional": true       // accepted, but streams one way only

Attaching to a leg that is in a conference. This route is the way to stream from a call that is also in a <Conference> - XML verbs execute in sequence and a bidirectional <Stream> holds its leg, so a <Conference> placed after it is never reached. The REST route attaches the stream as a media bug on the channel, outside XML sequencing.Wait for the ConferenceEnter callback and allow roughly two seconds before attaching. The leg has to settle in the room first, or the stream receives no audio.

Path parameters

Field	Type	Required	Description
`auth_id`	string	Yes	Your Vobiz authentication ID.
`call_uuid`	string	Yes	UUID of the active call to attach the stream to.

Request Parameters

Field	Type	Required	Description
`service_url`	string	Yes	WebSocket URL (wss:// or ws://) to which Vobiz forwards the call audio. Must be reachable from the public internet; use `wss://` in production.
`audio_track`	string	No	Track 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.
`bidirectional`	string	No	If `"true"`, the WebSocket may send audio back into the call using playAudio events. Send this as the string `"true"`, not a JSON boolean - see the warning below. Default: `"false"`.
`content_type`	string	No	Format for inbound audio sent from Vobiz to your WebSocket. Options: “audio/x-l16;rate=8000”, “audio/x-l16;rate=16000”, or “audio/x-mulaw;rate=8000”. Default: “audio/x-l16;rate=8000”. Vobiz reports the selected format in `start.mediaFormat`.
`stream_timeout`	integer	No	Maximum stream duration in seconds. Vobiz automatically stops the stream when this limit is reached. Default: 86400 (24 hours).
`status_callback_url`	string	No	URL invoked when the stream status changes (connected, stopped, timeout, failed).
`status_callback_method`	string	No	HTTP method for status_callback_url. One of “GET”, “POST”. Default: “POST”.
`extra_headers`	string	No	Comma-separated list of additional HTTP headers (header:value) sent when opening the WebSocket connection. Useful for auth tokens.

Choose the inbound content_type that your speech or media processor accepts. L16 carries raw 16-bit PCM; μ-law uses less bandwidth at 8 kHz.

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` value	Meaning
`StartStream`	The WebSocket connected and audio is being forwarded. Carries `ServiceURL`.
`PlayedStream`	Audio queued before a `checkpoint` finished playing. Carries `Name`. Only fires if playback completed.
`StopStream`	Streaming 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 outbound playback audio to the call. This format is independent of the inbound REST content_type.

Send audio from WebSocket to call

{
  "event": "playAudio",
  "streamId": "STREAM_ID",
  "media": {
    "contentType": "audio/x-l16",
    "sampleRate": 24000,
    "payload": "<base64-encoded-audio>"
  }
}

Field	Values
`contentType`	audio/x-l16, audio/x-mulaw
`sampleRate`	L16: 8000, 16000, or 24000. μ-law: 8000. The bytes must match the declared rate.
`payload`	Base64-encoded raw mono audio without a WAV or other container 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.

Do not set REST content_type to L16/24 kHz to play a 24 kHz TTS response. content_type configures inbound Vobiz-to-application audio. Set sampleRate: 24000 on a playAudio event that contains genuine L16/24 kHz 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": "inbound",
    "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

⌘I

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

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/"

payload = { "service_url": "wss://your-server.com/ws" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({service_url: 'wss://your-server.com/ws'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "stream_id": "str_XXXXXXXXXX",
  "message": "Stream started"
}

​Path parameters

​Request Parameters

​Status Callback Events

​Bidirectional streaming

​Response

​Example Request

Authorizations

Path Parameters

Body

Response

Path parameters

Request Parameters

Status Callback Events

Bidirectional streaming

Response

Example Request