Telnyx WebSocket Integration

Things you’ll need

An active Telnyx account with API credentials
One or more Telnyx provisioned phone numbers
A public-facing server or tunneling service like ngrok (for dial-out only)
API keys for speech-to-text, text-to-speech, and LLM services

Telnyx Dial-in Example

Complete dial-in implementation using Telnyx Media Streaming over WebSocket

Telnyx Dial-out Example

Outbound calling using Telnyx Media Streaming with WebSocket transport

Phone Number Setup

You’ll need Telnyx phone numbers for both dial-in and dial-out functionality:

Visit telnyx.com and purchase phone numbers
Ensure your numbers support Voice capabilities
Configure TeXML applications for dial-in numbers (covered below)

Environment Setup

Configure your environment variables for Telnyx and AI services:

.env

TELNYX_API_KEY=...
OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...

Dial-in

Dial-in allows users to call your Telnyx number and connect to your Pipecat bot via WebSocket Media Streaming. Unlike Twilio, Telnyx automatically provides caller information (to/from numbers) in the WebSocket messages, so no custom server is needed for basic dial-in functionality.

How It Works

Here’s the sequence of events when someone calls your Telnyx number:

Telnyx receives an incoming call to your phone number
Telnyx executes your TeXML application which establishes a WebSocket connection
Telnyx opens a WebSocket to your server with real-time audio and call metadata
Your bot processes the audio using the Pipecat pipeline
The bot responds with audio sent back to Telnyx over WebSocket
Telnyx plays the audio to the caller in real-time

Set up your TeXML application

Telnyx uses TeXML (Telnyx Extensible Markup Language) to control call flow. For dial-in, you create a TeXML application that establishes a WebSocket connection directly to your bot:

TeXML for dial-in

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://your-server.com/ws" bidirectionalMode="rtp"></Stream>
  </Connect>
  <Pause length="40"/>
</Response>

The bidirectionalMode="rtp" parameter enables real-time audio streaming in both directions.

Personalizing Your Bot with Caller Information

Telnyx automatically includes caller information (to/from numbers) in the WebSocket messages. You can use the caller’s phone number to:

Look up customer information in your database
Personalize greetings and responses based on caller identity
Route calls to different bot behaviors (e.g., VIP handling, support vs sales)
Implement custom business logic based on the caller

The example bot demonstrates how to extract caller information from Telnyx’s WebSocket messages and use it to personalize the conversation.

Configure your Pipecat bot for dial-in

Your bot receives the WebSocket connection and automatically gets call information from Telnyx’s WebSocket messages. The key components are: WebSocket Parsing: Pipecat’s built-in parser extracts call data from Telnyx’s WebSocket messages:

bot.py

from pipecat.runner.utils import parse_telephony_websocket

async def run_bot(websocket: WebSocket):
    # Parse Telnyx WebSocket data
    transport_type, call_data = await parse_telephony_websocket(websocket)

    # Extract call information (automatically provided by Telnyx)
    # Data format: {
    #     "stream_id": str,
    #     "call_control_id": str,
    #     "outbound_encoding": str,
    #     "from": str,
    #     "to": str,
    # }
    stream_id = call_data["stream_id"]
    call_control_id = call_data["call_control_id"]
    outbound_encoding = call_data["outbound_encoding"]
    from_number = call_data["from"]  # Caller's number
    to_number = call_data["to"]      # Your Telnyx number

Transport Creation: Configure the WebSocket transport with Telnyx serialization:

bot.py

# Create Telnyx serializer with call details
serializer = TelnyxFrameSerializer(
    stream_id=stream_id,
    call_control_id=call_control_id,
    api_key=os.getenv("TELNYX_API_KEY"),
)

# Configure WebSocket transport
transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        add_wav_header=False,
        vad_analyzer=SileroVADAnalyzer(),
        serializer=serializer,
    ),
)

# Your bot pipeline setup here...

Complete Bot Implementation

See the full bot.py with WebSocket parsing, transport setup, and pipeline configuration

Set up Telnyx TeXML application

Configure your Telnyx phone number to use your TeXML application:

Go to the Telnyx Portal
Navigate to Voice → Programmable Voice → TeXML Applications
Create a new TeXML Application with your WebSocket URL
Assign the TeXML Application to your phone number

Complete Setup Instructions

See the full README with step-by-step setup, TeXML configuration, and testing

Dial-out

Dial-out allows your bot to initiate calls to phone numbers using Telnyx’s outbound calling capabilities with WebSocket Media Streaming.

How It Works

Here’s the sequence of events for dial-out calls:

Your application triggers a dial-out (via API call or user action)
Server initiates a Telnyx call using the Call Control API
Telnyx establishes the call and opens a WebSocket connection
Your bot joins the WebSocket and sets up the pipeline
The recipient answers and is connected to your bot
The bot handles the conversation with real-time audio streaming

Set up your server for dial-out

The dial-out server creates outbound calls and manages WebSocket connections. When you trigger a dial-out call, your server:

Receives the dial-out request with target phone number and parameters
Creates a Telnyx call using the Call Control API with a webhook URL
Accepts the WebSocket connection from Telnyx
Parses call data including call control information
Runs the Pipecat bot with the call information

Complete Server Implementation

See the full FastAPI server code with outbound call creation and WebSocket handling

Configure your Pipecat bot for dial-out

The dial-out bot configuration is similar to dial-in, with Telnyx automatically providing call information. Call Information: Telnyx provides call details in the WebSocket messages:

bot.py

# Parse WebSocket data (same as dial-in)
transport_type, call_data = await parse_telephony_websocket(websocket)

# Extract call information
stream_id = call_data["stream_id"]
call_control_id = call_data["call_control_id"]
from_number = call_data["from"]  # Your Telnyx number
to_number = call_data["to"]      # Target number you're calling

# Customize bot behavior for outbound calls
greeting = f"Hi! This is an automated call from {from_number}. How are you today?"

Custom Parameters for Dial-out: You can pass custom data to your bot by adding query parameters to the WebSocket URL in your TeXML:

server.py

# When creating the TeXML for outbound calls, include custom parameters
texml = f"""<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://your-server.com/ws?campaign_id=summer_sale&user_id={user_id}&priority=high" bidirectionalMode="rtp"></Stream>
  </Connect>
  <Pause length="40"/>
</Response>"""

These parameters are accessible in your server code and can be used to customize your bot’s behavior based on the specific call context.

Complete Bot Implementation

See the full bot.py with outbound call handling and call information usage

Run the Example

To test dial-out functionality:

Start your server: Run your FastAPI server
Trigger a call: Make an API request to start an outbound call
Answer your phone: The bot will call the specified number
Talk to your bot: Have a conversation with your AI agent

Complete Setup Instructions

See the full README with step-by-step setup, API usage, and outbound call configuration

Key Features

Audio Format and Sample Rate

Telnyx Media Streaming uses 8kHz mono audio with 16-bit PCM encoding. Configure your pipeline accordingly:

task = PipelineTask(
    pipeline,
    params=PipelineParams(
        audio_in_sample_rate=8000,
        audio_out_sample_rate=8000,
        allow_interruptions=True,
    ),
)

Automatic Call Termination

When you provide Telnyx API credentials to the TelnyxFrameSerializer, it automatically ends calls when your pipeline ends:

serializer = TelnyxFrameSerializer(
    stream_id=stream_id,
    call_control_id=call_control_id,
    api_key=os.getenv("TELNYX_API_KEY"),  # Enables auto-termination
)

Built-in Call Information

Unlike other providers, Telnyx automatically includes caller information (to/from numbers) in the WebSocket messages, eliminating the need for custom webhook servers in basic dial-in scenarios.

Deployment

Pipecat Cloud Deployment

For production deployment without managing your own infrastructure, use Pipecat Cloud:

Telnyx WebSocket on Pipecat Cloud

Deploy Telnyx WebSocket bots with automatic scaling and managed infrastructure

Self-Hosted Production Deployment

For fully self-hosted production deployment, ensure your servers are:

Publicly accessible with HTTPS
Able to handle concurrent WebSocket connections
Properly configured with Telnyx API credentials
Implementing proper error handling and logging

Next Steps

Explore the complete examples for full implementations
Learn about Daily + Twilio SIP integration for advanced telephony scenarios
Check out Daily PSTN integration for direct phone number provisioning

Learning Pipecat

Fundamentals

Features

Telephony

Telnyx WebSocket Integration

Things you’ll need

Telnyx Dial-in Example

Telnyx Dial-out Example

Phone Number Setup

Environment Setup

Dial-in

How It Works

Set up your TeXML application

Personalizing Your Bot with Caller Information

Configure your Pipecat bot for dial-in

Complete Bot Implementation

Set up Telnyx TeXML application

Complete Setup Instructions

Dial-out

How It Works

Set up your server for dial-out

Complete Server Implementation

Configure your Pipecat bot for dial-out

Complete Bot Implementation

Run the Example

Complete Setup Instructions

Key Features

Audio Format and Sample Rate

Automatic Call Termination

Built-in Call Information

Deployment

Pipecat Cloud Deployment

Telnyx WebSocket on Pipecat Cloud

Self-Hosted Production Deployment

Next Steps

Learning Pipecat

Fundamentals

Features

Telephony

​Things you’ll need

Telnyx Dial-in Example

Telnyx Dial-out Example

​Phone Number Setup

​Environment Setup

​Dial-in

​How It Works

​Set up your TeXML application

​Personalizing Your Bot with Caller Information

​Configure your Pipecat bot for dial-in

Complete Bot Implementation

​Set up Telnyx TeXML application

Complete Setup Instructions

​Dial-out

​How It Works

​Set up your server for dial-out

Complete Server Implementation

​Configure your Pipecat bot for dial-out

Complete Bot Implementation

​Run the Example

Complete Setup Instructions

​Key Features

​Audio Format and Sample Rate

​Automatic Call Termination

​Built-in Call Information

​Deployment

​Pipecat Cloud Deployment

Telnyx WebSocket on Pipecat Cloud

​Self-Hosted Production Deployment

​Next Steps

Things you’ll need

Phone Number Setup

Environment Setup

Dial-in

How It Works

Set up your TeXML application

Personalizing Your Bot with Caller Information

Configure your Pipecat bot for dial-in

Set up Telnyx TeXML application

Dial-out

How It Works

Set up your server for dial-out

Configure your Pipecat bot for dial-out

Run the Example

Key Features

Audio Format and Sample Rate

Automatic Call Termination

Built-in Call Information

Deployment

Pipecat Cloud Deployment

Self-Hosted Production Deployment

Next Steps