Twilio Frame Serializer

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:

Twilio Account: Sign up at Twilio Console
Phone Number: Purchase a Twilio phone number with voice capabilities
Media Streams: Configure your phone number to use Media Streams
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

str

required

The Twilio Media Stream SID.

str

default:"None"

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

str

default:"None"

Twilio account SID. Required when auto_hang_up is enabled.

str

default:"None"

Twilio Auth Token. When auto_hang_up is enabled, provide either this or api_key_sid and api_key_secret, not both.

str

default:"None"

Twilio API key SID (starts with SK). Alternative to auth_token for auto hang-up. Keyword-only; must be provided with api_key_secret.

str

default:"None"

Twilio API key secret. Keyword-only; must be provided with api_key_sid.

str

default:"None"

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

str

default:"None"

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

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.

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

import os

from pipecat.serializers.twilio import TwilioFrameSerializer
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketParams,
    FastAPIWebsocketTransport,
)

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 = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        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 either auth_token or both api_key_sid and api_key_secret. A ValueError is raised at initialization if any are missing, if auth_token is combined with any part of an API key, or if only one of api_key_sid and api_key_secret is given. Credentials must belong to the configured region, since each Twilio region has its own Auth Token and API keys.
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.

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Twilio Frame Serializer

Overview

Twilio Serializer API Reference

Example Implementation

Twilio Documentation

Twilio Console

Installation

Prerequisites

Twilio Account Setup

Required Environment Variables

Required Configuration

Key Features

Configuration

InputParams

Usage

Basic Setup

Without Auto Hang-up

Notes

​Overview

Twilio Serializer API Reference

Example Implementation

Twilio Documentation

Twilio Console

​Installation

​Prerequisites

​Twilio Account Setup

​Required Environment Variables

​Required Configuration

​Key Features

​Configuration

​InputParams

​Usage

​Basic Setup

​Without Auto Hang-up

​Notes

Overview

Installation

Prerequisites

Twilio Account Setup

Required Environment Variables

Required Configuration

Key Features

Configuration

InputParams

Usage

Basic Setup

Without Auto Hang-up

Notes