> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VonageFrameSerializer

> Serializer for Vonage Video API Audio Connector WebSocket protocol

## Overview

`VonageFrameSerializer` enables integration with the Vonage Video API Audio Connector WebSocket protocol, allowing Pipecat applications to process real-time audio streams from active Vonage video sessions.

<CardGroup cols={2}>
  <Card title="Vonage Serializer API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.serializers.vonage.html">
    Pipecat's API methods for Vonage Audio Connector Streams integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/vonage-audio-bot">
    End-to-end Pipecat example using Vonage Audio Connector
  </Card>

  <Card title="Vonage Audio Connector Documentation" icon="book" href="https://developer.vonage.com/en/video/guides/audio-connector">
    Official Vonage Video API Audio Connector documentation
  </Card>

  <Card title="Vonage Video API Console" icon="microphone" href="https://tokbox.com/account/">
    Manage Vonage Video API projects
  </Card>
</CardGroup>

## Installation

The `VonageFrameSerializer` does not require any additional dependencies beyond the core Pipecat library:

```bash theme={null}
uv add "pipecat-ai"
```

## Prerequisites

### Vonage Video API Account Setup

Before using VonageFrameSerializer, you need:

1. **Vonage (TokBox) Account**: Sign up at [Vonage Video API Console](https://tokbox.com/account/)
2. **Vonage Video API Project**: Create a project to obtain Project API Key and Project Secret
3. **Existing Vonage Video Session**: A Vonage session must already exist. Sessions can be created using TokBox Playground or Vonage Video API SDKs

### Required Environment Variables

* `VONAGE_API_KEY`: Your Vonage Video API project key
* `VONAGE_API_SECRET`: Your Vonage Video API project secret
* `VONAGE_SESSION_ID`: The existing routed session ID
* `WS_URI`: Public WebSocket endpoint URI of the server application running Pipecat (e.g. via ngrok)

### Required Configuration

* **WebSocket Endpoint (/ws)**: A WebSocket server application (e.g. FastAPI) running Pipecat that accepts raw PCM audio frames.
* **Audio Connector /connect Request**: Triggers Vonage to open a WebSocket connection to your server and begin streaming audio from the active session.

### Key Features

* **Bidirectional Audio**: Convert between Pipecat and Vonage Audio Connector formats
* **Real-Time AI Pipelines**: Stream live audio into Pipecat and process it through any real-time pipeline configuration supported by the framework
* **Session Control Events**: Handle Vonage Audio Connector JSON events
* **Linear PCM Audio**: Handle raw 16-bit linear PCM audio streams used by the Vonage Video API Audio Connector

## Configuration

<ParamField path="params" type="InputParams" default="None">
  Configuration parameters for audio settings. See [InputParams](#inputparams)
  below.
</ParamField>

### InputParams

| Parameter              | Type   | Default | Description                                                                                         |
| ---------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------- |
| `vonage_sample_rate`   | `int`  | `16000` | Sample rate used by Vonage (Hz). Common values: 8000, 16000, 24000.                                 |
| `sample_rate`          | `int`  | `None`  | Optional override for pipeline input sample rate. When `None`, uses the pipeline's configured rate. |
| `ignore_rtvi_messages` | `bool` | `True`  | Whether to ignore RTVI protocol messages during serialization.                                      |

## Usage

### Basic Setup

```python theme={null}
from pipecat.serializers.vonage import VonageFrameSerializer
from pipecat.transports.network.websocket_server import WebSocketServerTransport

serializer = VonageFrameSerializer()

transport = WebSocketServerTransport(
    params=WebSocketServerParams(
        audio_out_enabled=True,
        add_wav_header=False,
        serializer=serializer,
    )
)
```

### With Custom Sample Rate

```python theme={null}
serializer = VonageFrameSerializer(
    params=VonageFrameSerializer.InputParams(
        vonage_sample_rate=8000,
    ),
)
```

## Notes

* **Linear PCM audio**: Unlike Twilio and Plivo, Vonage uses raw 16-bit linear PCM audio (not mu-law encoded). Audio data is sent as binary WebSocket messages rather than base64-encoded JSON.
* **No auto hang-up**: The Vonage serializer does not include automatic call termination. Session lifecycle is managed through the Vonage Video API.
* **Event handling**: The serializer handles Vonage-specific WebSocket events including `websocket:connected`, `websocket:cleared`, `websocket:notify`, and `websocket:dtmf`.
* **DTMF support**: Touch-tone digit events are converted to `InputDTMFFrame` objects.