Skip to main content

​
Overview

TelnyxFrameSerializer enables integration with Telnyx’s WebSocket media streaming protocol, allowing your Pipecat application to handle phone calls via Telnyx’s voice services with bidirectional audio conversion, DTMF event handling, and support for multiple audio encodings.

Telnyx Serializer API Reference

Pipecat’s API methods for Telnyx WebSocket integration

Example Implementation

Complete telephony examples with Telnyx

Telnyx Documentation

Official Telnyx media streaming documentation

Telnyx Portal

Manage phone numbers and streaming configuration

​
Installation

The TelnyxFrameSerializer does not require any additional dependencies beyond the core Pipecat library: 
pip install "pipecat-ai"

​
Prerequisites

​
Telnyx Account Setup

Before using TelnyxFrameSerializer, you need:
  1. Telnyx Account: Sign up at Telnyx Portal
  2. Phone Number: Purchase a Telnyx phone number with voice capabilities
  3. Media Streaming: Configure your phone number for WebSocket streaming
  4. Webhook Configuration: Set up webhook endpoints for call handling

​
Required Environment Variables

  • TELNYX_API_KEY: Your Telnyx API key for authentication and call control

​
Required Configuration

  • Stream ID: Provided by Telnyx during WebSocket connection
  • Audio Encodings: Configure inbound/outbound encodings (PCMU, PCMA)
  • Call Control ID: Required for automatic call termination (optional)

​
Key Features

  • Bidirectional Audio: Convert between Pipecat and Telnyx audio formats
  • DTMF Handling: Process touch-tone events from callers
  • Auto Hang-up: Terminate calls via Telnyx’s REST API
  • Multiple Encodings: Support for PCMU and PCMA audio formats

​
Configuration

​
stream_id
str
required
The Telnyx Stream ID.
​
outbound_encoding
str
required
The encoding type for outbound audio received from Telnyx (e.g., "PCMU", "PCMA").
​
inbound_encoding
str
required
The encoding type for inbound audio sent to Telnyx (e.g., "PCMU", "PCMA").
​
call_control_id
str
default:"None"
The Telnyx Call Control ID. Required when auto_hang_up is enabled.
​
api_key
str
default:"None"
Telnyx API key. Required when auto_hang_up is enabled.
​
params
InputParams
default:"None"
Configuration parameters for audio and hang-up behavior. See InputParams below.

​
InputParams

ParameterTypeDefaultDescription
telnyx_sample_rateint8000Sample rate used by Telnyx (Hz).
sample_rateintNoneOptional override for pipeline input sample rate. When None, uses the pipeline’s configured rate.
inbound_encodingstr"PCMU"Audio encoding for data sent to Telnyx.
outbound_encodingstr"PCMU"Audio encoding for data received from Telnyx.
auto_hang_upboolTrueWhether to automatically terminate the call on EndFrame or CancelFrame.

​
Usage

​
Basic Setup

from pipecat.serializers.telnyx import TelnyxFrameSerializer
from pipecat.transports.network.websocket_server import WebSocketServerTransport

serializer = TelnyxFrameSerializer(
    stream_id=stream_id,
    outbound_encoding="PCMU",
    inbound_encoding="PCMU",
    call_control_id=call_control_id,
    api_key=os.getenv("TELNYX_API_KEY"),
)

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

​
Without Auto Hang-up

serializer = TelnyxFrameSerializer(
    stream_id=stream_id,
    outbound_encoding="PCMU",
    inbound_encoding="PCMU",
    params=TelnyxFrameSerializer.InputParams(
        auto_hang_up=False,
    ),
)

​
Notes

  • Multiple audio encodings: Telnyx supports both PCMU (mu-law) and PCMA (A-law) encodings. The inbound_encoding and outbound_encoding must be specified as constructor arguments and will override any values set in InputParams.
  • Auto hang-up credentials: When auto_hang_up is enabled (the default), call_control_id and api_key are required to terminate the call via Telnyx’s REST API. If missing, a warning is logged and the hang-up is skipped.
  • DTMF support: Touch-tone digit events from callers are converted to InputDTMFFrame objects.