Vobiz Logo
Vobiz
|API Documentation
Console

Stream Events Overview

You can utilize the WebSocket connection to stream events from your application to Vobiz. With this connection, you can play audio, interrupt and clear buffered audio, and send a checkpoint event to indicate the completion of playback.

Prerequisites

To use stream events, you must:

  • →Set bidirectional="true" on the Stream element
  • →Have an active WebSocket connection established by Vobiz
  • →Send events as JSON messages through the WebSocket

Event Types

1. playAudio Event

Transmit audio through the WebSocket to be played on the call. When the bidirectional attribute is set to true, Vobiz can deliver the audio transmitted from your application to the party on the call.

Key Attributes:

  • event: playAudio
  • media: Object containing contentType, sampleRate, and base64-encoded payload
Learn more about playAudio →

2. clearAudio Event

The clearAudio event interrupts audio previously sent to Vobiz via the playAudio event. Vobiz clears all buffered media events, enabling you to initiate new playAudio events tailored to a specific use case.

Key Attributes:

  • event: clearAudio
  • streamId: Unique identifier for the audio stream
Learn more about clearAudio →

3. checkpoint Event

Send a checkpoint event via WebSocket when the desired audio events are queued. Vobiz will respond with playedStream, indicating that audio events buffered before the Checkpoint were successfully played out to the end user.

Key Attributes:

  • event: checkpoint
  • streamId: Unique identifier for the audio stream
  • name: Name of the checkpoint you use to recognize upon receiving acknowledgment
Learn more about checkpoint →

Event Flow

Here's how stream events flow between your application and Vobiz:

→

Your App → Vobiz

Send events through the WebSocket to control audio playback:

  • playAudio - Play audio to the caller
  • clearAudio - Interrupt and clear buffered audio
  • checkpoint - Mark playback completion points
←

Vobiz → Your App

Receive acknowledgments and stream data from Vobiz:

  • start - Stream connection established
  • media - Continuous audio packets from the call
  • playedStream - Checkpoint acknowledgment
  • clearedAudio - Clear audio acknowledgment
  • stop - Stream connection ended

Important: The playedStream event will only be emitted if the preceding events were played successfully. If playback fails or is interrupted, you may not receive this acknowledgment.

Examples

Bidirectional XML Configuration

Enable bidirectional audio streaming
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Stream
        bidirectional="true"
        keepCallAlive="true"
        contentType="audio/x-l16;rate=8000">
        wss://stream.vobiz.ai/stream
    </Stream>
</Response>

The bidirectional="true" attribute is required to send playAudio, clearAudio, and checkpoint events.

Typical Event Sequence

Example event flow for an interactive voice app
// 1. Vobiz sends 'start' event
{
  "event": "start",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "callId": "CALL_abc123xyz"
}

// 2. Your app sends playAudio event (greeting)
{
  "event": "playAudio",
  "media": {
    "contentType": "audio/x-l16",
    "sampleRate": 8000,
    "payload": "base64-encoded-audio..."
  }
}

// 3. Your app sends checkpoint to mark greeting completion
{
  "event": "checkpoint",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "name": "customer greeting audio"
}

// 4. Vobiz responds with playedStream (greeting played successfully)
{
  "event": "playedStream",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "name": "customer greeting audio"
}

// 5. User speaks - Vobiz sends media events
{
  "event": "media",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662",
  "media": {
    "payload": "base64-user-audio...",
    "contentType": "audio/x-l16",
    "sampleRate": 8000
  }
}

// 6. Your app decides to interrupt with new audio
{
  "event": "clearAudio",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}

// 7. Vobiz acknowledges the clear
{
  "sequenceNumber": 0,
  "event": "clearedAudio",
  "streamId": "20170ada-f610-433b-8758-c02a2aab3662"
}

// 8. Your app sends new playAudio event
{
  "event": "playAudio",
  "media": {
    "contentType": "audio/x-l16",
    "sampleRate": 8000,
    "payload": "base64-new-audio..."
  }
}

Node.js Implementation

Sending events from your WebSocket server
const WebSocket = require('ws');

let streamId = null;

wss.on('connection', (ws) => {
  ws.on('message', (message) => {
    const data = JSON.parse(message);

    if (data.event === 'start') {
      streamId = data.streamId;
      console.log('Stream started:', streamId);

      // Play a greeting audio
      sendPlayAudio(ws, greetingAudioBase64);

      // Send checkpoint to track when greeting finishes
      sendCheckpoint(ws, streamId, 'greeting-complete');
    }

    if (data.event === 'playedStream') {
      console.log('Checkpoint reached:', data.name);
      // Greeting played successfully - continue with next action
    }

    if (data.event === 'media') {
      // Process incoming audio
      const audioData = Buffer.from(data.media.payload, 'base64');
      // ... analyze, transcribe, etc.
    }
  });
});

function sendPlayAudio(ws, audioBase64) {
  ws.send(JSON.stringify({
    event: 'playAudio',
    media: {
      contentType: 'audio/x-l16',
      sampleRate: 8000,
      payload: audioBase64
    }
  }));
}

function sendCheckpoint(ws, streamId, checkpointName) {
  ws.send(JSON.stringify({
    event: 'checkpoint',
    streamId: streamId,
    name: checkpointName
  }));
}

function sendClearAudio(ws, streamId) {
  ws.send(JSON.stringify({
    event: 'clearAudio',
    streamId: streamId
  }));
}
Initiate Stream
Checkpoint Event