> ## 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.
# Stream XML Element – Real-Time WebSocket Audio | Vobiz
> Fork live call audio to a WebSocket server in real time with Vobiz Stream. Supports bidirectional streaming, L16/μ-law codecs, and AI voice agent pipelines.
**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] |
| `maxRetries`
*integer* | Maximum number of reconnect attempts if the WebSocket connection fails to establish or drops mid-stream.
**Default:** `0` (retries disabled)
**Max:** `10`
Values below `0` are treated as `0`. Values above `10` are capped at `10`. Non-integer values fall back to `0`. |
| `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. |
| `maxRetries`
*integer* | Maximum reconnect attempts configured for this stream. Default: 0 (disabled). |
| `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 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
### StartStream - stream started
Fired when the WebSocket connection is successfully established and audio streaming begins.
```http Example StartStream Callback theme={null}
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=wss://your-server.com/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.
```http Example PlayedStream Callback theme={null}
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
```http Example StopStream Callback theme={null}
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
```javascript Node.js Express Handler theme={null}
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
```xml Simple one-way audio stream theme={null}
wss://stream.vobiz.ai/stream
```
Streams inbound audio (default) to your WebSocket server at the specified URL.
### Bidirectional audio stream
```xml Two-way audio streaming with callbacks theme={null}
wss://stream.vobiz.ai/stream
```
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
```xml Stream inbound and outbound audio with 1-hour timeout theme={null}
wss://stream.vobiz.ai/stream
Thank you for calling. We're processing your request.
```
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](/xml/stream/initiate) - Learn how to establish a WebSocket connection and start streaming audio from active calls.
* [Stream Events Overview](/xml/stream/stream-events) - Understand how to send events like playAudio, clearAudio, and checkpoint via WebSocket.
* [Checkpoint Event](/xml/stream/checkpoint-event) - Send checkpoint events to confirm audio playback completion and manage event queues.
* [Play Audio Event](/xml/stream/play-audio) - Transmit audio through WebSocket for bidirectional audio streaming use cases.