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

# TwilioFrameSerializer

> Serializer for Twilio Media Streams WebSocket protocol

## Overview

`TwilioFrameSerializer` enables integration with Twilio's Media Streams WebSocket protocol, allowing your Pipecat application to handle phone calls via Twilio's voice services with bidirectional audio conversion, DTMF event handling, and automatic call termination.

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

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

  <Card title="Twilio Documentation" icon="book" href="https://www.twilio.com/docs/voice/media-streams">
    Official Twilio Media Streams documentation
  </Card>

  <Card title="Twilio Console" icon="microphone" href="https://console.twilio.com/">
    Manage phone numbers and Media Stream configuration
  </Card>
</CardGroup>

## Installation

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

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

## Prerequisites

### Twilio Account Setup

Before using TwilioFrameSerializer, you need:

1. **Twilio Account**: Sign up at [Twilio Console](https://console.twilio.com/)
2. **Phone Number**: Purchase a Twilio phone number with voice capabilities
3. **Media Streams**: Configure your phone number to use Media Streams
4. **Webhook Configuration**: Set up webhook endpoints for call handling

### Required Environment Variables

* `TWILIO_ACCOUNT_SID`: Your Twilio Account SID for authentication
* `TWILIO_AUTH_TOKEN`: Your Twilio Auth Token for API operations

### Required Configuration

* **Stream SID**: Provided by Twilio during Media Stream connection
* **Call SID**: Required for automatic call termination (optional)

### Key Features

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

## Configuration

<ParamField path="stream_sid" type="str" required>
  The Twilio Media Stream SID.
</ParamField>

<ParamField path="call_sid" type="str" default="None">
  The associated Twilio Call SID. Required when `auto_hang_up` is enabled.
</ParamField>

<ParamField path="account_sid" type="str" default="None">
  Twilio account SID. Required when `auto_hang_up` is enabled.
</ParamField>

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

<ParamField path="region" type="str" default="None">
  Twilio region (e.g., `"au1"`, `"ie1"`). Must be specified together with
  `edge`.
</ParamField>

<ParamField path="edge" type="str" default="None">
  Twilio edge location (e.g., `"sydney"`, `"dublin"`). Must be specified
  together with `region`.
</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                                                                                         |
| ---------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------- |
| `twilio_sample_rate`   | `int`  | `8000`  | Sample rate used by Twilio (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.twilio import TwilioFrameSerializer
from pipecat.transports.network.websocket_server import WebSocketServerTransport

serializer = TwilioFrameSerializer(
    stream_sid=stream_sid,
    call_sid=call_sid,
    account_sid=os.getenv("TWILIO_ACCOUNT_SID"),
    auth_token=os.getenv("TWILIO_AUTH_TOKEN"),
)

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

### Without Auto Hang-up

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

## Notes

* **Auto hang-up requires credentials**: When `auto_hang_up` is enabled (the default), you must provide `call_sid`, `account_sid`, and `auth_token`. A `ValueError` is raised at initialization if any are missing.
* **Region and edge pairing**: If either `region` or `edge` is specified, both must be provided. Twilio's API uses the FQDN format `api.{edge}.{region}.twilio.com`.
* **Audio format**: Twilio 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.