Things you’ll need
- An active Twilio account with API credentials
- One or more Twilio provisioned phone numbers
- A tunneling service like ngrok for local development
- API keys for speech-to-text, text-to-speech, and LLM services
Twilio Dial-in Example
Complete dial-in implementation using Twilio Media Streams over WebSocket
Twilio Dial-out Example
Outbound calling using Twilio Media Streams with WebSocket transport
Phone Number Setup
You’ll need Twilio phone numbers for both dial-in and dial-out functionality:- Visit console.twilio.com and purchase phone numbers
- Ensure your numbers support Voice capabilities
- Configure webhook URLs for dial-in numbers (covered below)
Environment Setup
Configure your environment variables for Twilio and AI services:.env
Dial-in
Dial-in allows users to call your Twilio number and connect to your Pipecat bot via WebSocket Media Streams.How It Works
Here’s the sequence of events when someone calls your Twilio number:- Twilio sends WebSocket messages: Twilio processes the associated TwiML Bin and starts a WebSocket stream to your bot (local or Pipecat Cloud)
- Parse the WebSocket messages: Your bot parses the WebSocket connection messages to set up the corresponding Pipecat transport
- (Optional) Look up the caller: Optionally, look up the caller using Twilio’s REST API to retrieve custom information about the call and personalize your bot’s behavior
- Bot starts responding: Once the pipeline is started, your bot will initiate the conversation
Setting Up Twilio
1. Create a TwiML Bin
A TwiML Bin tells Twilio how to handle incoming calls. You’ll create one that establishes a WebSocket connection to your bot.- Go to the Twilio Console
- Navigate to TwiML Bins → My TwiML Bins
- Click the + to create a new TwiML Bin
- Name your bin and add the TwiML:
- Local Development
- Pipecat Cloud
your-url.ngrok.io with your ngrok URL.- Click Save
2. Assign TwiML Bin to Your Phone Number
- Navigate to Phone Numbers → Manage → Active Numbers
- Click on your Twilio phone number
- In the “Voice Configuration” section:
- Set “A call comes in” to TwiML Bin
- Select the TwiML Bin you created
- Click Save configuration
Running the Example
You’ll need two terminal windows to run the example.-
In your first terminal, start ngrok to expose your local server:
Tip: Use the
--subdomainflag for a reusable ngrok URL. -
In your second terminal, install dependencies:
-
Then run the bot:
- Call your bot by placing a call to the number associated with your bot. The bot will answer and start the conversation.
Personalizing Your Bot with Caller Information
When a call comes in, your bot receives a Call SID from Twilio. You can use this Call SID to fetch caller information from Twilio’s REST API, including the caller’s phone number. With this information, you can:- 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
aiohttp to avoid blocking the event loop, ensuring your bot remains responsive even with multiple concurrent calls.
Complete Dial-in Example
See the full implementation with WebSocket parsing, REST API integration, and
caller personalization
Dial-out
Dial-out allows your bot to initiate calls to phone numbers using Twilio’s outbound calling capabilities with WebSocket Media Streams.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 Twilio call to the target phone number
- Twilio 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 Twilio call using the REST API with TwiML that establishes WebSocket
- Accepts the WebSocket connection from Twilio
- Parses call data including any custom parameters
- 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, but you can pass custom parameters when creating the outbound call: Custom Parameters for Dial-out: Pass information to your bot through TwiML parameters:server.py
bot.py
Complete Bot Implementation
See the full bot.py with outbound call handling and parameter 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
Twilio Media Streams uses 8kHz mono audio with 16-bit PCM encoding. To avoid resampling, set the audio input and output sample rate to 8000 Hz:Automatic Call Termination
When you provide Twilio credentials to theTwilioFrameSerializer, it automatically ends calls when your pipeline ends:
Deployment
Pipecat Cloud Deployment
For production deployment without managing your own infrastructure, use Pipecat Cloud:Twilio WebSocket on Pipecat Cloud
Deploy Twilio 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 Twilio 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