The Stream Element

Key Capabilities

Bidirectional streaming: Send and receive audio in real-time
Multiple audio tracks: Stream inbound, outbound, or both tracks
Flexible codecs: Support for multiple audio formats and sample rates
Event streaming: Send playback, checkpoint, and control events via WebSocket

Attributes

Attribute	Description
`bidirectional` boolean	Specifies whether the audio being streamed over the WebSocket is bidirectional (read/write) or one-way (read-only). If `true`, Vobiz accepts: - event: Takes `playAudio` as the value - media: JSON object containing: - contentType: audio/x-l16, audio/x-mulaw - sampleRate: 8000, 16000 - payload: Base64-encoded raw audio
`audioTrack` string	The audio track (inbound/outbound) that Vobiz will fork and stream to the WebSocket. Allowed values: `inbound`, `outbound`, `both` Default: `inbound` Note: When bidirectional is true, audioTrack should not be `outbound` or `both`.
`streamTimeout` integer	Maximum duration (in seconds) for audio streaming. Streaming stops after this duration. Must be a positive integer. Default: `86400` (24 hours)
`statusCallbackUrl` string	URL notified when: - Audio stream is connected - Audio stream is stopped intentionally or due to timeout - Audio stream failed or disconnected
`statusCallbackMethod` string	HTTP method used to invoke statusCallbackUrl. Allowed values: `GET`, `POST` Default: `POST`
`contentType` string	Preferred audio codec and sampling rate. Allowed values: - `audio/x-l16;rate=8000` - `audio/x-l16;rate=16000` - `audio/x-mulaw;rate=8000` Default: `audio/x-l16;rate=8000`
`extraHeaders` string	Key-value pairs sent to the WebSocket service with the audio stream. Example: `test1=12,test2=123` Max length: 512 bytes Allowed characters: [A-Z], [a-z], [0-9]
`keepCallAlive` boolean	If `true`, the Stream element executes exclusively and subsequent XML elements run only after the stream disconnects. Allowed values: `true`, `false` Default: `false`

Parameters sent to statusCallbackUrl

This information is sent to the statusCallbackUrl when an event is triggered.

Parameter	Description
`bidirectional` boolean	Indicates whether the audio stream was bidirectional (read/write) or one-way (read-only).
`audioTrack` string	The audio track that Vobiz forked and streamed. Values: `inbound`, `outbound`, `both`
`streamTimeout` integer	Maximum duration (in seconds) that audio was streamed. Default: 86400 (24 hours)
`statusCallbackUrl` string	URL that received the notification of stream events.
`statusCallbackMethod` string	HTTP method used (GET or POST). Default: POST
`contentType` string	Audio codec and sampling rate that was used.
`extraHeaders` string	Key-value pairs that were sent along with the audio stream.
`keepCallAlive` boolean	Whether the stream executed exclusively before continuing with subsequent XML elements.

Status callback events

When you configure a statusCallbackUrl, Vobiz sends HTTP POST/GET requests to that URL when specific stream lifecycle events occur. These are separate from WebSocket events and are useful for logging, monitoring, and triggering business logic.

HTTP Callbacks vs WebSocket EventsHTTP Status Callbacks (sent to statusCallbackUrl):

StartStream, PlayedStream, StopStream events
Sent via HTTP POST/GET to your web server
For logging, monitoring, and triggering workflows

WebSocket Events (sent via WebSocket connection):

start, media, stop, playedStream, clearedAudio events
Sent through the WebSocket connection in real-time
For audio streaming and real-time interaction

StartStream - stream started

Fired when the WebSocket connection is successfully established and audio streaming begins.

Example StartStream Callback

POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=StartStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
ServiceURL=ws://stream.vobiz.ai/ws
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:40

PlayedStream - checkpoint reached

Fired when audio queued before a checkpoint event has been successfully played to the caller. The Name parameter contains the checkpoint name you specified.

This event is only sent if you send a checkpoint event via WebSocket and the audio plays successfully. If playback is interrupted, this event may not fire.

Example PlayedStream Callback

POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=PlayedStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
Name=first
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:46

StopStream - stream ended

Fired when the audio streaming session ends. This can happen due to:

Stream timeout (streamTimeout reached)
Call ended by either party
WebSocket connection closed
Network error or disconnection

Example StopStream Callback

POST /stream-status HTTP/1.1
Host: yourapp.com
Content-Type: application/x-www-form-urlencoded

From=918071387423
To=919624705678
CallUUID=9a0e0208-d01a-4572-9a04-fe583a05ac53
Event=StopStream
StreamID=227d997a-0af4-447c-a3f3-b243e902e527
ParentAuthID=MA_PU0XU668
status_callback_url=https://yourapp.com/stream-status
status_callback_method=POST
Timestamp=2025-11-06 09:58:50

Common parameters in all events

Parameter	Description
`CallUUID`	Unique identifier for the call
`StreamID`	Unique identifier for this streaming session
`Event`	Event type: StartStream, PlayedStream, or StopStream
`From`	Caller’s phone number
`To`	Called phone number
`Timestamp`	When the event occurred
`Name`	Checkpoint name (PlayedStream only)
`ServiceURL`	WebSocket URL used for streaming (StartStream only)

Example: handling status callbacks

Node.js Express Handler

app.post('/stream-status', (req, res) => {
  const { Event, StreamID, CallUUID, Name, Timestamp } = req.body;

  switch(Event) {
    case 'StartStream':
      console.log(`Stream started: ${stream_id} for call ${CallUUID}`);
      // Log to database, initialize session, etc.
      break;

    case 'PlayedStream':
      console.log(`Checkpoint "${Name}" reached for stream ${stream_id}`);
      // Track checkpoint completion, trigger next action
      break;

    case 'StopStream':
      console.log(`Stream ended: ${stream_id} at ${Timestamp}`);
      // Clean up resources, finalize session, send notifications
      break;

    default:
      console.log(`Unknown event: ${Event}`);
  }

  // Always respond with 200 OK
  res.status(200).send('OK');
});

Examples

Basic audio stream

Simple one-way audio stream

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stream>wss://stream.vobiz.ai/stream</Stream>
</Response>

Streams inbound audio (default) to your WebSocket server at the specified URL.

Bidirectional audio stream

Two-way audio streaming with callbacks

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stream
bidirectional="true"
keepCallAlive="true"
statusCallbackUrl="https://yourapp.vobiz.ai/stream-status"
contentType="audio/x-l16;rate=16000">
wss://stream.vobiz.ai/stream
    </Stream>
</Response>

Enables bidirectional streaming with a 16 kHz sample rate, keeps the call alive during streaming, and sends status updates to your callback URL.

Stream both tracks with timeout

Stream inbound and outbound audio with 1-hour timeout

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stream
audioTrack="both"
streamTimeout="3600"
statusCallbackUrl="https://yourapp.vobiz.ai/stream-status"
statusCallbackMethod="POST"
extraHeaders="session=abc123,user=john">
wss://stream.vobiz.ai/stream
    </Stream>
    <Speak>Thank you for calling. We're processing your request.</Speak>
</Response>

Streams both inbound and outbound audio for up to 1 hour, includes custom headers, and continues to subsequent XML elements after streaming ends.

Next steps

Initiate a Stream - Learn how to establish a WebSocket connection and start streaming audio from active calls.
Stream Events Overview - Understand how to send events like playAudio, clearAudio, and checkpoint via WebSocket.
Checkpoint Event - Send checkpoint events to confirm audio playback completion and manage event queues.
Play Audio Event - Transmit audio through WebSocket for bidirectional audio streaming use cases.

XML Overview

Conference

The Stream Element

Attributes

Parameters sent to statusCallbackUrl

Status callback events

StartStream - stream started

PlayedStream - checkpoint reached

StopStream - stream ended

Common parameters in all events

Example: handling status callbacks

Examples

Basic audio stream

Bidirectional audio stream

Stream both tracks with timeout

Next steps

XML Overview

Conference

Documentation Index

​Attributes

​Parameters sent to statusCallbackUrl

​Status callback events

​StartStream - stream started

​PlayedStream - checkpoint reached

​StopStream - stream ended

​Common parameters in all events

​Example: handling status callbacks

​Examples

​Basic audio stream

​Bidirectional audio stream

​Stream both tracks with timeout

​Next steps

Attributes

Parameters sent to statusCallbackUrl

Status callback events

StartStream - stream started

PlayedStream - checkpoint reached

StopStream - stream ended

Common parameters in all events

Example: handling status callbacks

Examples

Basic audio stream

Bidirectional audio stream

Stream both tracks with timeout

Next steps