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

# VonageVideoConnectorTransport

> WebRTC transport implementation using Vonage Video API for real-time audio/video communication

## Overview

`VonageVideoConnectorTransport` provides real-time WebRTC audio and video communication using the Vonage Video API. It handles bidirectional media streams, participant management, and session lifecycle events, enabling you to build AI-powered applications that participate in Vonage Video sessions.

<Warning>
  The Vonage Video Connector library runs on Linux AMD64 and ARM64 platforms
  only (Python 3.13+).
</Warning>

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/transports/transports-vonage.py">
    Complete Vonage Video Connector voice agent example
  </Card>

  <Card title="Vonage Video API Documentation" icon="book" href="https://developer.vonage.com/en/video/overview">
    Official Vonage Video API documentation and guides
  </Card>

  <Card title="Vonage Dashboard" icon="external-link" href="https://ui.idp.vonage.com/ui/auth/registration">
    Sign up for Vonage API access and application management
  </Card>
</CardGroup>

## Installation

To use `VonageVideoConnectorTransport`, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[vonage-video-connector]"
```

<Note>
  The `vonage-video-connector` extra installs the Vonage Video Connector native
  library, which is only available on Linux AMD64 and ARM64 with Python 3.13.
</Note>

## Prerequisites

### Vonage Account Setup

Before using `VonageVideoConnectorTransport`, you need:

1. **Vonage Account**: Sign up at [Vonage Dashboard](https://ui.idp.vonage.com/ui/auth/registration)
2. **Application**: Create a Vonage Video API application in the dashboard
3. **Session**: Create a Vonage Video session (via the server SDK or REST API)
4. **Token**: Generate a participant token for the session

<Tip>
  The [Vonage Video Playground](https://tools.vonage.com/video/playground) is an
  easy way to create a session and generate a token for testing — no code
  required.
</Tip>

### Required Environment Variables

* `VONAGE_APPLICATION_ID`: Your Vonage Video application ID
* `VONAGE_SESSION_ID`: The ID of the Video API session to join
* `VONAGE_TOKEN`: A valid participant token for the session

### Key Features

* **Vonage Video API**: Integrate with Vonage's managed WebRTC infrastructure
* **Audio and Video I/O**: Bidirectional audio and video streaming
* **Participant Management**: Stream subscription and participant lifecycle events
* **Auto-subscription**: Optionally auto-subscribe to incoming audio and video streams
* **Interruption Handling**: Automatic media buffer clearing on pipeline interruptions

## Configuration

### VonageVideoConnectorTransport

<ParamField path="application_id" type="str" required>
  Your Vonage Video API application identifier.
</ParamField>

<ParamField path="session_id" type="str" required>
  The ID of the Vonage Video session to connect to.
</ParamField>

<ParamField path="token" type="str" required>
  A valid participant token for the session.
</ParamField>

<ParamField path="params" type="VonageVideoConnectorTransportParams" default="VonageVideoConnectorTransportParams()">
  Transport configuration parameters. See
  [VonageVideoConnectorTransportParams](#vonagevideoconnectortransportparams)
  below and
  [TransportParams](/api-reference/server/services/transport/transport-params)
  for inherited base parameters.
</ParamField>

### VonageVideoConnectorTransportParams

Inherits all parameters from [TransportParams](/api-reference/server/services/transport/transport-params) (audio, video settings) with these additional fields:

<ParamField path="publisher_name" type="str" default="&#x22;Bot&#x22;">
  Display name for the bot's published stream in the session.
</ParamField>

<ParamField path="publisher_enable_opus_dtx" type="bool" default="False">
  Whether to enable Opus Discontinuous Transmission (DTX) for the publisher
  audio, which reduces bandwidth when no audio is being sent.
</ParamField>

<ParamField path="session_enable_migration" type="bool" default="False">
  Whether to enable session migration, allowing the connection to survive
  network changes.
</ParamField>

<ParamField path="audio_in_auto_subscribe" type="bool" default="True">
  Whether to automatically subscribe to incoming audio streams from session
  participants.
</ParamField>

<ParamField path="video_in_auto_subscribe" type="bool" default="False">
  Whether to automatically subscribe to incoming video streams from session
  participants.
</ParamField>

<ParamField path="video_in_preferred_resolution" type="tuple[int, int]" default="None">
  Preferred `(width, height)` resolution for auto-subscribed video input
  streams.
</ParamField>

<ParamField path="video_in_preferred_framerate" type="int" default="None">
  Preferred framerate for auto-subscribed video input streams.
</ParamField>

<ParamField path="clear_buffers_on_interruption" type="bool" default="True">
  Whether to clear media buffers in the Vonage Video Connector when an
  `InterruptionFrame` is received. Enable this for conversational AI
  applications that need to stop playback immediately when the user interrupts;
  disable it for recording or streaming scenarios where all media should be
  preserved.
</ParamField>

<ParamField path="video_connector_log_level" type="str" default="&#x22;INFO&#x22;">
  Log level for the Vonage Video Connector native library. Accepted values:
  `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`.
</ParamField>

### SubscribeSettings

Used with `subscribe_to_stream()` to control per-stream subscription quality when `audio_in_auto_subscribe` or `video_in_auto_subscribe` are disabled.

<ParamField path="subscribe_to_audio" type="bool" default="True">
  Whether to subscribe to the stream's audio track.
</ParamField>

<ParamField path="subscribe_to_video" type="bool" default="False">
  Whether to subscribe to the stream's video track.
</ParamField>

<ParamField path="preferred_resolution" type="tuple[int, int]" default="None">
  Preferred `(width, height)` resolution for the subscribed video track. The
  server provides the closest available quality if the exact resolution is
  unavailable.
</ParamField>

<ParamField path="preferred_framerate" type="int" default="None">
  Preferred framerate for the subscribed video track.
</ParamField>

## Usage

`VonageVideoConnectorTransport` connects your Pipecat bot to a Vonage Video session where it can communicate with participants through audio and video streams. The transport handles session joining, stream subscription, and media conversion automatically.

Use `pipecat.runner.vonage.configure()` to read credentials from environment variables:

```python theme={null}
from pipecat.runner.vonage import configure
from pipecat.transports.vonage.video_connector import (
    VonageVideoConnectorTransport,
    VonageVideoConnectorTransportParams,
)

(application_id, session_id, token) = await configure()

transport = VonageVideoConnectorTransport(
    application_id,
    session_id,
    token,
    VonageVideoConnectorTransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        publisher_name="Bot",
    ),
)
```

See the [complete example](https://github.com/pipecat-ai/pipecat/blob/main/examples/transports/transports-vonage.py) for a full implementation including:

* Session credential configuration via environment variables
* Transport setup with audio input and output
* Pipeline integration with an LLM service
* Event handling to trigger the bot when a participant connects

### Subscribing to streams manually

When `audio_in_auto_subscribe` or `video_in_auto_subscribe` is disabled, subscribe to a specific participant's stream with `subscribe_to_stream()`, passing [SubscribeSettings](#subscribesettings) to control which tracks are received and at what quality. The `streamId` is available from the `on_participant_joined` event data.

```python theme={null}
from pipecat.transports.vonage.video_connector import SubscribeSettings

await transport.subscribe_to_stream(
    stream_id="participant_stream_id",
    params=SubscribeSettings(
        subscribe_to_audio=True,
        subscribe_to_video=True,
        preferred_resolution=(1280, 720),
        preferred_framerate=30,
    ),
)
```

## Event Handlers

`VonageVideoConnectorTransport` provides event handlers for session lifecycle, participant stream management, and subscriber connectivity. Register handlers using the `@event_handler` decorator on the transport instance.

### Events Summary

| Event                         | Description                                          |
| ----------------------------- | ---------------------------------------------------- |
| `on_joined`                   | Bot joined the Vonage session                        |
| `on_left`                     | Bot left the Vonage session                          |
| `on_error`                    | Transport error occurred                             |
| `on_first_participant_joined` | First participant stream joined the session (sync)   |
| `on_participant_joined`       | A participant stream joined the session (sync)       |
| `on_participant_left`         | A participant stream left the session                |
| `on_client_connected`         | Transport connected to a participant's stream (sync) |
| `on_client_disconnected`      | Transport disconnected from a participant's stream   |

### Session Lifecycle

#### on\_joined

Fired when the bot successfully connects to the Vonage Video session.

```python theme={null}
@transport.event_handler("on_joined")
async def on_joined(transport, data):
    print(f"Joined session: {data['sessionId']}")
```

**Parameters:**

| Parameter   | Type                            | Description                       |
| ----------- | ------------------------------- | --------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance            |
| `data`      | `dict`                          | Event data containing `sessionId` |

#### on\_left

Fired when the bot disconnects from the Vonage Video session.

```python theme={null}
@transport.event_handler("on_left")
async def on_left(transport, data):
    print(f"Left session: {data['sessionId']}")
```

**Parameters:**

| Parameter   | Type                            | Description                       |
| ----------- | ------------------------------- | --------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance            |
| `data`      | `dict`                          | Event data containing `sessionId` |

#### on\_error

Fired when a transport-level error occurs.

```python theme={null}
@transport.event_handler("on_error")
async def on_error(transport, error):
    print(f"Transport error: {error}")
```

**Parameters:**

| Parameter   | Type                            | Description            |
| ----------- | ------------------------------- | ---------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance |
| `error`     | `str`                           | Error description      |

### Participants

#### on\_first\_participant\_joined

Fired when the first participant stream is received in the session. Commonly used to trigger the bot's initial response.

```python theme={null}
@transport.event_handler("on_first_participant_joined")
async def on_first_participant_joined(transport, data):
    print(f"First participant joined stream: {data['streamId']}")
    await task.queue_frames([LLMRunFrame()])
```

**Parameters:**

| Parameter   | Type                            | Description                                                         |
| ----------- | ------------------------------- | ------------------------------------------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance                                              |
| `data`      | `dict`                          | Event data containing `sessionId`, `streamId`, and `connectionData` |

<Note>
  This is a **synchronous** event — the session will not proceed until all
  handlers complete. Keep handlers fast.
</Note>

#### on\_participant\_joined

Fired when any participant stream is received in the session.

```python theme={null}
@transport.event_handler("on_participant_joined")
async def on_participant_joined(transport, data):
    print(f"Participant joined stream: {data['streamId']}")
```

**Parameters:**

| Parameter   | Type                            | Description                                                         |
| ----------- | ------------------------------- | ------------------------------------------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance                                              |
| `data`      | `dict`                          | Event data containing `sessionId`, `streamId`, and `connectionData` |

<Note>
  This is a **synchronous** event — the session will not proceed until all
  handlers complete. Keep handlers fast.
</Note>

<Note>
  Both `on_first_participant_joined` and `on_participant_joined` fire for the
  first stream. Use `on_first_participant_joined` if you only need to react
  once.
</Note>

#### on\_participant\_left

Fired when a participant's stream is dropped from the session.

```python theme={null}
@transport.event_handler("on_participant_left")
async def on_participant_left(transport, data):
    print(f"Participant left stream: {data['streamId']}")
```

**Parameters:**

| Parameter   | Type                            | Description                                                         |
| ----------- | ------------------------------- | ------------------------------------------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance                                              |
| `data`      | `dict`                          | Event data containing `sessionId`, `streamId`, and `connectionData` |

### Subscribers

#### on\_client\_connected

Fired when the transport successfully connects to a participant's stream — at this point the subscription is established and media is flowing.

```python theme={null}
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, data):
    print(f"Client connected to stream: {data['streamId']}")
    await task.queue_frames([LLMRunFrame()])
```

**Parameters:**

| Parameter   | Type                            | Description                                                            |
| ----------- | ------------------------------- | ---------------------------------------------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance                                                 |
| `data`      | `dict`                          | Event data containing `subscriberId`, `streamId`, and `connectionData` |

<Note>
  This is a **synchronous** event — the session will not proceed until all
  handlers complete. Keep handlers fast.
</Note>

#### on\_client\_disconnected

Fired when the transport disconnects from a participant's stream, either due to an explicit unsubscription or a connection drop.

```python theme={null}
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, data):
    print(f"Client disconnected from stream: {data['streamId']}")
```

**Parameters:**

| Parameter   | Type                            | Description                                                            |
| ----------- | ------------------------------- | ---------------------------------------------------------------------- |
| `transport` | `VonageVideoConnectorTransport` | The transport instance                                                 |
| `data`      | `dict`                          | Event data containing `subscriberId`, `streamId`, and `connectionData` |

## Additional Resources

* [Events Overview](/api-reference/server/events/overview) - Overview of all events in Pipecat
* [TransportParams](/api-reference/server/services/transport/transport-params) - Base transport parameters reference