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

# PlivoFrameSerializer

> Serializer for Plivo Audio Streaming WebSocket protocol

## Overview

`PlivoFrameSerializer` enables integration with Plivo's Audio Streaming WebSocket protocol, allowing your Pipecat application to handle phone calls via Plivo's voice services with bidirectional audio conversion, DTMF event handling, and automatic call termination.

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/plivo-chatbot">
    Complete telephony examples with Plivo
  </Card>

  <Card title="Plivo Documentation" icon="book" href="https://www.plivo.com/docs/voice/api/stream/">
    Official Plivo Audio Streaming documentation
  </Card>

  <Card title="Plivo Console" icon="microphone" href="https://console.plivo.com/">
    Manage phone numbers and streaming configuration
  </Card>
</CardGroup>

## Installation

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

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

## Prerequisites

### Plivo Account Setup

Before using PlivoFrameSerializer, you need:

1. **Plivo Account**: Sign up at [Plivo Console](https://console.plivo.com/)
2. **Phone Number**: Purchase a Plivo phone number with voice capabilities
3. **Audio Streaming**: Configure your phone number for WebSocket streaming
4. **Webhook Configuration**: Set up webhook endpoints for call handling

### Required Environment Variables

* `PLIVO_AUTH_ID`: Your Plivo Auth ID for authentication
* `PLIVO_AUTH_TOKEN`: Your Plivo Auth Token for API operations

### Required Configuration

* **Stream ID**: Provided by Plivo during Audio Streaming connection
* **Call ID**: Required for automatic call termination (optional)

### Key Features

* **Bidirectional Audio**: Convert between Pipecat and Plivo audio formats
* **DTMF Handling**: Process touch-tone events from callers
* **Auto Hang-up**: Terminate calls via Plivo's REST API
* **μ-law Encoding**: Handle Plivo's standard audio encoding format

## Configuration

<ParamField path="stream_id" type="str" required>
  The Plivo Stream ID.
</ParamField>

<ParamField path="call_id" type="str" default="None">
  The associated Plivo Call ID. Required when `auto_hang_up` is enabled.
</ParamField>

<ParamField path="auth_id" type="str" default="None">
  Plivo auth ID. Required when `auto_hang_up` is enabled.
</ParamField>

<ParamField path="auth_token" type="str" default="None">
  Plivo auth token. Required when `auto_hang_up` is enabled.
</ParamField>

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

### InputParams

| Parameter              | Type   | Default | Description                                                                                         |
| ---------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------- |
| `plivo_sample_rate`    | `int`  | `8000`  | Sample rate used by Plivo (Hz).                                                                     |
| `sample_rate`          | `int`  | `None`  | Optional override for pipeline input sample rate. When `None`, uses the pipeline's configured rate. |
| `auto_hang_up`         | `bool` | `True`  | Whether to automatically terminate the call on `EndFrame` or `CancelFrame`.                         |
| `ignore_rtvi_messages` | `bool` | `True`  | Whether to ignore RTVI protocol messages during serialization.                                      |

## Usage

### Basic Setup

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

serializer = PlivoFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    auth_id=os.getenv("PLIVO_AUTH_ID"),
    auth_token=os.getenv("PLIVO_AUTH_TOKEN"),
)

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

### Without Auto Hang-up

```python theme={null}
serializer = PlivoFrameSerializer(
    stream_id=stream_id,
    params=PlivoFrameSerializer.InputParams(
        auto_hang_up=False,
    ),
)
```

## Notes

* **Auto hang-up requires credentials**: When `auto_hang_up` is enabled (the default), you must provide `call_id`, `auth_id`, and `auth_token`. A `ValueError` is raised at initialization if any are missing.
* **Audio format**: Plivo uses 8kHz mu-law (PCMU) audio encoding. The serializer automatically converts between this format and Pipecat's PCM audio.
* **DTMF support**: Touch-tone digit events from callers are converted to `InputDTMFFrame` objects.