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.

Twilio Serializer API Reference

Pipecat’s API methods for Twilio Media Streams integration

Example Implementation

Complete telephony examples with Twilio

Twilio Documentation

Official Twilio Media Streams documentation

Twilio Console

Manage phone numbers and Media Stream configuration

Installation

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

uv add "pipecat-ai"

Prerequisites

Twilio Account Setup

Before using TwilioFrameSerializer, you need:

1. Twilio Account: Sign up at Twilio Console
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

stream_sid · str · required

The Twilio Media Stream SID.

call_sid · str · default: "None"

The associated Twilio Call SID. Required when auto_hang_up is enabled.

account_sid · str · default: "None"

Twilio account SID. Required when auto_hang_up is enabled.

auth_token · str · default: "None"

Twilio auth token. Required when auto_hang_up is enabled.

region · str · default: "None"

Twilio region (e.g., "au1", "ie1"). Must be specified together with edge when base_url is not provided.

edge · str · default: "None"

Twilio edge location (e.g., "sydney", "dublin"). Must be specified together with region when base_url is not provided.

base_url · str · default: "None"

REST API base URL (scheme + host, e.g., https://api.twilio.com) used for auto hang-up. Defaults to the host derived from region/edge. Set this to target a Twilio-API-compatible backend or a self-hosted server.

params · InputParams · default: "None"

Configuration parameters for audio and hang-up behavior. See InputParams below.

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.
resampler_clear_after_secs	float | None	0.2	Seconds of inactivity after which the stream resampler clears its internal history to avoid audio artefacts. Set to None to never clear (recommended for telephony providers with irregular gaps).

Usage

Basic Setup

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

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: When base_url is not provided, both region and edge must be specified together if either is set. Twilio’s API uses the FQDN format api.{edge}.{region}.twilio.com. This requirement does not apply when base_url is provided, since base_url is used verbatim and ignores region/edge.
• 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.