​
Overview

TelnyxFrameSerializer enables integration with Telnyx’s WebSocket media streaming protocol, allowing your Pipecat application to handle phone calls via Telnyx’s voice services.

​
Features

  • Bidirectional audio conversion between Pipecat and Telnyx
  • DTMF (touch-tone) event handling
  • Automatic call termination via Telnyx’s REST API
  • Support for multiple audio encodings (PCMU, PCMA)

​
Installation

The TelnyxFrameSerializer does not require any additional dependencies beyond the core Pipecat library.

​
Configuration

​
Constructor Parameters

​
stream_id
str
required

The Stream ID for Telnyx

​
outbound_encoding
str
required

The encoding type for outbound audio (e.g., “PCMU”, “PCMA”)

​
inbound_encoding
str
required

The encoding type for inbound audio (e.g., “PCMU”, “PCMA”)

​
call_control_id
Optional[str]
default:"None"

The Call Control ID for the Telnyx call (required for auto hang-up)

​
api_key
Optional[str]
default:"None"

Your Telnyx API key (required for auto hang-up)

​
params
InputParams
default:"InputParams()"

Configuration parameters

​
InputParams Configuration

​
telnyx_sample_rate
int
default:"8000"

Sample rate used by Telnyx (typically 8kHz)

​
sample_rate
int | None
default:"None"

Optional override for pipeline input sample rate

​
inbound_encoding
str
default:"PCMU"

Audio encoding for data sent to Telnyx

​
outbound_encoding
str
default:"PCMU"

Audio encoding for data received from Telnyx

​
auto_hang_up
bool
default:"True"

Whether to automatically terminate call on EndFrame

​
Basic Usage

from pipecat.serializers.telnyx import TelnyxFrameSerializer
from pipecat.transports.network.fastapi_websocket import (
    FastAPIWebsocketTransport,
    FastAPIWebsocketParams
)

# Extract required values from Telnyx WebSocket connection
stream_id = call_data["stream_id"]
call_control_id = call_data["start"]["call_control_id"]
outbound_encoding = call_data["start"]["media_format"]["encoding"]

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

# Use with FastAPIWebsocketTransport
transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_out_enabled=True,
        vad_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
        vad_audio_passthrough=True,
        serializer=serializer,
    )
)

​
Hang-up Functionality

When auto_hang_up is enabled, the serializer will automatically hang up the Telnyx call when an EndFrame or CancelFrame is processed, using Telnyx’s REST API:

# Properly configured with hang-up support
serializer = TelnyxFrameSerializer(
    stream_id=stream_id,
    outbound_encoding=outbound_encoding,
    inbound_encoding="PCMU",
    call_control_id=call_control_id,    # Required for auto hang-up
    api_key=os.getenv("TELNYX_API_KEY") # Required for auto hang-up
)

​
Server Code Example

Here’s a complete example of handling a Telnyx WebSocket connection:

from fastapi import FastAPI, WebSocket
from pipecat.serializers.telnyx import TelnyxFrameSerializer
import json
import os

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    # Read initial messages from Telnyx
    start_data = websocket.iter_text()
    await start_data.__anext__()  # Skip first message

    # Parse the second message to get call details
    call_data = json.loads(await start_data.__anext__())

    # Extract Telnyx-specific IDs and encoding
    stream_id = call_data["stream_id"]
    call_control_id = call_data["start"]["call_control_id"]
    outbound_encoding = call_data["start"]["media_format"]["encoding"]

    # Create serializer with API key for auto hang-up
    serializer = TelnyxFrameSerializer(
        stream_id=stream_id,
        outbound_encoding=outbound_encoding,
        inbound_encoding="PCMU",
        call_control_id=call_control_id,
        api_key=os.getenv("TELNYX_API_KEY"),
    )

    # Continue with transport and pipeline setup...

See the Telnyx Chatbot example for a complete implementation.


## 3. Update the FastAPIWebsocketTransport Documentation

You may want to add a bit more detail to the serializer section in your FastAPIWebsocketTransport documentation:

```markdown
<ParamField path="serializer" type="FrameSerializer" required>
  
Frame serializer for WebSocket messages.

Common options include:

- [`TwilioFrameSerializer`](/server/utilities/serializers/twilio) - For Twilio Media Streams integration
- [`TelnyxFrameSerializer`](/server/utilities/serializers/telnyx) - For Telnyx WebSocket streaming integration

See the [Frame Serializers](/server/utilities/serializers/introduction) documentation for more details.

</ParamField>