Exotel WebSocket Integration

Things you’ll need

An active Exotel account with voice streaming enabled
One or more Exotel 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

Exotel Dial-in Example

Complete dial-in implementation using Exotel Voice Streaming over WebSocket

Exotel Dial-out Example

Outbound calling using Exotel Voice Streaming with WebSocket transport

Phone Number Setup

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

Visit exotel.com and purchase phone numbers
Complete KYC verification if required
Ensure voice streaming is enabled on your account (contact Exotel support if needed)

Environment Setup

Configure your environment variables for Exotel and AI services:

.env

EXOTEL_ACCOUNT_SID=...
EXOTEL_API_KEY=...
EXOTEL_API_TOKEN=...
OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...

Dial-in

Dial-in allows users to call your Exotel number and connect to your Pipecat bot via WebSocket Voice Streaming. Unlike other providers, Exotel 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 Exotel number:

Exotel receives an incoming call to your phone number
Exotel executes your App Bazaar flow which includes a Voicebot applet
Exotel 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 Exotel over WebSocket
Exotel plays the audio to the caller in real-time

Set up your App Bazaar flow

Exotel uses App Bazaar to configure call flows. For dial-in, you create an app with a Voicebot applet that establishes a WebSocket connection directly to your bot:

Navigate to App Bazaar in your Exotel dashboard
Create a new app or edit an existing one
Add a Voicebot applet (not “Stream” or “Passthru”)
Configure the WebSocket URL: wss://your-server.com/ws
Add a Hangup applet at the end to properly terminate calls

Your flow should look like: Call Start → [Voicebot Applet] → [Hangup Applet]

Custom Data Limitations

Currently, there are limitations with passing custom data through query parameters in Exotel’s WebSocket URLs. While the platform theoretically supports query parameters, they may be stripped during call processing. This is an ongoing limitation that may be addressed in future Exotel updates.

If you need to pass custom data, consider these alternatives:

Use different WebSocket endpoints for different call types
Configure multiple App Bazaar flows for different scenarios
Handle customization based on the called number (available in WebSocket messages)

Configure your Pipecat bot for dial-in

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

bot.py

from pipecat.runner.utils import parse_telephony_websocket

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

    # Extract call information (automatically provided by Exotel)
    stream_id = call_data["stream_id"]
    call_id = call_data["call_id"]  # Exotel's CallSid
    account_sid = call_data["account_sid"]
    from_number = call_data["from"]  # Caller's number
    to_number = call_data["to"]      # Your Exotel number

Transport Creation: Configure the WebSocket transport with Exotel serialization:

bot.py

# Create Exotel serializer with call details
serializer = ExotelFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    account_sid=account_sid,
    api_key=os.getenv("EXOTEL_API_KEY"),
    api_token=os.getenv("EXOTEL_API_TOKEN"),
)

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

Call Information Usage: Use the extracted call information to personalize your bot’s behavior:

bot.py

# Customize bot behavior based on call information
greeting = f"Hello! I see you're calling from {from_number}. How can I help you today?"

# Use call information for logging or routing
logger.info(f"Incoming call from {from_number} to {to_number}")

Complete Bot Implementation

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

Set up Exotel phone number

Configure your Exotel phone number to use your App Bazaar flow:

Go to the Exotel Dashboard
Navigate to ExoPhones
Find your phone number and click the edit icon
Under “App”, select your App Bazaar flow
Save the configuration

Run the Example

For dial-in, you can run your bot directly without a separate server:

# Start your bot directly
python bot.py

# For local development, use ngrok to expose your WebSocket
ngrok http 8000
# Use the ngrok WebSocket URL (wss://abc123.ngrok.io/ws) in your App Bazaar flow

Complete Setup Instructions

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

Dial-out

Dial-out allows your bot to initiate calls to phone numbers using Exotel’s outbound calling capabilities with WebSocket Voice 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 an Exotel call using the Voice API
Exotel 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 an Exotel call using the Voice API with a callback URL
Accepts the WebSocket connection from Exotel
Parses call data from the WebSocket messages
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 Exotel automatically providing call information. Note the Custom Data Limitations section above. Call Information: Extract call details from Exotel’s 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_id = call_data["call_id"]
account_sid = call_data["account_sid"]
from_number = call_data["from"]  # Your Exotel 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?"

Transport Configuration: Same transport setup as dial-in:

bot.py

# Create Exotel serializer
serializer = ExotelFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    account_sid=account_sid,
    api_key=os.getenv("EXOTEL_API_KEY"),
    api_token=os.getenv("EXOTEL_API_TOKEN"),
)

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

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

Exotel Voice 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,
    ),
)

Built-in Call Information

Like Telnyx, Exotel automatically includes comprehensive call information (to/from numbers, account details) in the WebSocket messages, eliminating the need for custom webhook servers in basic dial-in scenarios.

Deployment

Local Development

Use ngrok to expose your local server for testing:

python server.py  # For dial-out
# OR
python bot.py     # For dial-in

ngrok http 8000
# Use the ngrok URL in your App Bazaar Voicebot applet

Pipecat Cloud Deployment

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

Exotel WebSocket on Pipecat Cloud

Deploy Exotel 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 Exotel 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

Exotel WebSocket Integration

Things you’ll need

Exotel Dial-in Example

Exotel Dial-out Example

Phone Number Setup

Environment Setup

Dial-in

How It Works

Set up your App Bazaar flow

Custom Data Limitations

Configure your Pipecat bot for dial-in

Complete Bot Implementation

Set up Exotel phone number

Run the Example

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

Built-in Call Information

Deployment

Local Development

Pipecat Cloud Deployment

Exotel WebSocket on Pipecat Cloud

Self-Hosted Production Deployment

Next Steps

Learning Pipecat

Fundamentals

Features

Telephony

​Things you’ll need

Exotel Dial-in Example

Exotel Dial-out Example

​Phone Number Setup

​Environment Setup

​Dial-in

​How It Works

​Set up your App Bazaar flow

​Custom Data Limitations

​Configure your Pipecat bot for dial-in

Complete Bot Implementation

​Set up Exotel phone number

​Run the Example

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

​Built-in Call Information

​Deployment

​Local Development

​Pipecat Cloud Deployment

Exotel 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 App Bazaar flow

Custom Data Limitations

Configure your Pipecat bot for dial-in

Set up Exotel phone number

Run the Example

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

Built-in Call Information

Deployment

Local Development

Pipecat Cloud Deployment

Self-Hosted Production Deployment

Next Steps