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

# TelnyxFrameSerializer

> Serializer for Telnyx WebSocket media streaming protocol

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

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

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

  <Card title="Telnyx Documentation" icon="book" href="https://developers.telnyx.com/docs/voice/media-streaming">
    Official Telnyx media streaming documentation
  </Card>

  <Card title="Telnyx Portal" icon="microphone" href="https://portal.telnyx.com/">
    Manage phone numbers and streaming configuration
  </Card>
</CardGroup>

## Installation

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

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

## Prerequisites

### Telnyx Account Setup

Before using TelnyxFrameSerializer, you need:

1. **Telnyx Account**: Sign up at [Telnyx Portal](https://portal.telnyx.com/)
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

<ParamField path="stream_id" type="str" required>
  The Telnyx Stream ID.
</ParamField>

<ParamField path="outbound_encoding" type="str" required>
  The encoding type for outbound audio received from Telnyx (e.g., `"PCMU"`,
  `"PCMA"`).
</ParamField>

<ParamField path="inbound_encoding" type="str" required>
  The encoding type for inbound audio sent to Telnyx (e.g., `"PCMU"`, `"PCMA"`).
</ParamField>

<ParamField path="call_control_id" type="str" default="None">
  The Telnyx Call Control ID. Required when `auto_hang_up` is enabled.
</ParamField>

<ParamField path="api_key" type="str" default="None">
  Telnyx API key. Required when `auto_hang_up` is enabled.
</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                                                                                         |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `telnyx_sample_rate` | `int`  | `8000`   | Sample rate used by Telnyx (Hz).                                                                    |
| `sample_rate`        | `int`  | `None`   | Optional override for pipeline input sample rate. When `None`, uses the pipeline's configured rate. |
| `inbound_encoding`   | `str`  | `"PCMU"` | Audio encoding for data sent to Telnyx.                                                             |
| `outbound_encoding`  | `str`  | `"PCMU"` | Audio encoding for data received from Telnyx.                                                       |
| `auto_hang_up`       | `bool` | `True`   | Whether to automatically terminate the call on `EndFrame` or `CancelFrame`.                         |

## Usage

### Basic Setup

```python theme={null}
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

```python theme={null}
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 requires credentials**: When `auto_hang_up` is enabled (the default), you must provide `call_control_id` and `api_key`. A `ValueError` is raised at initialization if any are missing.
* **DTMF support**: Touch-tone digit events from callers are converted to `InputDTMFFrame` objects.