​
Overview

Learn how to connect your Pipecat bot to a phone number so users can call and have voice conversations. This guide covers different telephony integration options and shows you how to implement telephone-based AI interactions.

​
Telephony Integration Options

Pipecat provides flexible integration with telephony providers through multiple connection mechanisms. Choose the approach that best fits your use case:

​
WebSocket + Media Streams

Best for: Quick prototypes and production applications that need simple call handling
  • Simplicity: Fast setup with minimal configuration
  • Supported providers: Twilio, Telnyx, Plivo, Exotel
  • Limitations: Basic call control (no transfers, reconnects, or advanced call center features)
Examples:

Twilio WebSocket

Complete setup guide using Twilio’s Media Streams (shown below)

Telnyx WebSocket

WebSocket integration with Telnyx telephony services

Plivo WebSocket

WebSocket integration with Plivo telephony platform

​
Daily PSTN Calling

Best for: Simple telephony needs without external provider setup
  • Ease of use: Built-in PSTN connectivity through Daily
  • Quick setup: No additional telephony account required
  • Limitations: Fewer customization options compared to dedicated providers
Examples:

Daily PSTN: Dial-in

Simple inbound calling using Daily’s built-in PSTN connectivity

Daily PSTN: Dial-out

Make outbound calls using Daily’s PSTN service

​
SIP + Daily WebRTC

Best for: Advanced call flows and call center integration
  • Advanced features: Call transfers, reconnection, sophisticated routing
  • Audio quality: Superior audio quality and reliability
  • Call center integration: Connect to existing telephony infrastructure
  • Complexity: More complex setup and configuration
Examples:

Daily + Twilio SIP: Dial-in

Advanced dial-in calling with SIP integration for better call control

Daily + Twilio SIP: Dial-out

Make outbound calls with advanced telephony features

​
WebSocket Example with Twilio

This example demonstrates the WebSocket approach using Twilio’s Media Streams. It’s the fastest way to get your bot answering phone calls.

​
Prerequisites

​
Python 3.10+

Pipecat requires Python 3.10 or newer. Check your version with: 
python --version
If you need to upgrade Python, we recommend using a version manager like uv or pyenv.

​
Required Services

You’ll need accounts and API keys for the following services:

Twilio Account

Telephony Provider Create an account and purchase a phone number for your bot

ngrok

Local Tunneling Create secure tunnels to your local development server

Deepgram (STT)

Create an account and generate your API key for real-time speech recognition.

OpenAI (LLM)

Create an account and generate an API key for intelligent conversation responses.

Cartesia (TTS)

Sign up and generate your API key for natural voice synthesis.

​
Setup

This example requires running both a server and ngrok tunnel in two separate terminal windows.

​
1. Clone the quickstart repository

git clone https://github.com/pipecat-ai/quickstart-phone-bot.git
cd quickstart-phone-bot

​
2. Set up your environment

Create your environment file: 
cp env.example .env
Open the .env file in your text editor and add your API keys: 
DEEPGRAM_API_KEY=your_deepgram_api_key
OPENAI_API_KEY=your_openai_api_key
CARTESIA_API_KEY=your_cartesia_api_key
Optional: Add your TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN to enable automatic call hangup features.

​
3. Install dependencies

Set up your virtual environment and install dependencies: 
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
Using uv? Create and activate with: uv venv && source .venv/bin/activate, then install with: uv pip install -r requirements.txt

​
4. Start ngrok tunnel (Terminal 1)

In your first terminal window, start ngrok to create a tunnel to your local server: 
ngrok http 7860
Want a consistent URL? Use the --subdomain flag: ngrok http --subdomain=your-bot-name 7860
Copy your ngrok URL (e.g., https://abc123.ngrok.io). You’ll need it for the next step.

​
5. Configure Twilio webhook

  1. Go to your Twilio phone number’s configuration page
  2. Under “Voice Configuration”, in the “A call comes in” section:
    • Select “Webhook” from the dropdown
    • Enter your ngrok URL: https://your-ngrok-url.ngrok.io
    • Ensure “HTTP POST” is selected
  3. Click “Save” at the bottom of the page

​
6. Run your phone bot (Terminal 2)

In your second terminal window, start your bot server: 
python bot.py --transport twilio --proxy your-ngrok-url.ngrok.io
Replace your-ngrok-url.ngrok.io with your actual ngrok domain (without https://).
Using uv? Run with: uv run bot.py --transport twilio --proxy your-ngrok-url.ngrok.io
You should see output confirming your server is running and ready to receive calls.

​
7. Test your phone bot

Call your Twilio phone number to start talking with your AI bot! 🚀 The bot will answer, introduce itself, and engage in conversation based on what you say.

​
Understanding the Call Flow

When someone calls your Twilio number, here’s what happens:
  1. Incoming Call: User dials your Twilio phone number
  2. Webhook: Twilio sends call data to your ngrok URL
  3. WebSocket: Your server establishes a real-time audio connection via WebSocket and exchanges Media Streams with Twilio
  4. Processing: Audio flows through your Pipecat pipeline (STT → LLM → TTS)
  5. Response: Synthesized speech streams back to the caller in real-time
This WebSocket approach provides low-latency, real-time audio processing perfect for natural conversation flow.

​
Deployment Patterns

This example uses Pipecat’s development runner for local testing. The runner automatically handles server setup and connection management. For Pipecat Cloud deployment: Your code can remain this simple. Pipecat Cloud handles all server infrastructure, requiring no additional setup in your code. For self-hosting: You’ll need to implement your own server to handle webhooks and WebSocket connections. See the WebSocket examples above for full implementation references in the pipecat-examples repository.

​
Troubleshooting

  • Call doesn’t connect: Verify your ngrok URL is correctly set in the Twilio webhook configuration
  • No audio or bot doesn’t respond: Check that all API keys are correctly set in your .env file
  • Webhook errors: Ensure your server is running and ngrok tunnel is active before making calls
  • ngrok tunnel issues: Free ngrok URLs change on each restart. Remember to update your Twilio webhook URL

​
Next Steps

Now that you have a working phone bot, you can explore more advanced telephony features:
  • Deploy to production: Replace ngrok with a proper server deployment and update your Twilio webhook
  • Try advanced call flows: Explore the Daily + SIP examples for call transfers, reconnection, and call center integration
  • Advanced features: Check out pipecat-examples for call recording, analytics, and more
  • Join the community: Connect with other developers on Discord to share your projects and get help