The Stream Element

The Stream element lets you receive raw audio from active calls over a WebSocket connection in near real time. This enables powerful use cases like real-time transcription, sentiment analysis, and AI-powered call assistants.

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`, this stream element runs alone. Subsequent XML elements execute only after the stream disconnects. Allowed values: `true`, `false` Default: `false`

Parameters Sent to statusCallbackUrl

This information is sent to 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)	Indicates whether stream was executed alone 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 Events

HTTP 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

StartStreamStream 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

PlayedStreamCheckpoint 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.

Note: This event is only sent if you send a checkpointevent 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

StopStreamStream 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: ${StreamID} for call ${CallUUID}`);
      // Log to database, initialize session, etc.
      break;

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

    case 'StopStream':
      console.log(`Stream ended: ${StreamID} 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>

This 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>

This enables bidirectional streaming with 16kHz 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>

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

Initiate Stream