This project is a FastAPI-based chatbot that integrates with Twilio to handle WebSocket connections and provide real-time communication. The project includes endpoints for starting a call and handling WebSocket connections.
Learn how to connect your Pipecatbot to a phone number so users can call and have voice conversations. This example shows the complete setup for telephone-based AI interactions using Twilio's telephony services. At the end, you'll be able to talk to your bot on the phone.
## Table of Contents
## Prerequisites
-[Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
-[Configure Twilio URLs](#configure-twilio-urls)
- [Running the Application](#running-the-application)
- [Twilio Account](https://www.twilio.com/login) and [phone number](https://help.twilio.com/articles/223135247-How-to-Search-for-and-Buy-a-Twilio-Phone-Number-from-Console)
-AI Service API keys for: [Deepgram](https://console.deepgram.com/signup), [OpenAI](https://auth.openai.com/create-account), and [Cartesia](https://play.cartesia.ai/sign-up)
## Features
## Setup
- **FastAPI**: A modern, fast (high-performance), web framework for building APIs with Python 3.6+.
- **WebSocket Support**: Real-time communication using WebSockets.
- **CORS Middleware**: Allowing cross-origin requests for testing.
- **Dockerized**: Easily deployable using Docker.
This example requires running both a server and ngrok tunnel in **two separate terminal windows**.
## Requirements
### Terminal 1: Start ngrok and Configure Twilio
- Python 3.10
- Docker (for containerized deployment)
- ngrok (for tunneling)
- Twilio Account
## Installation
1.**Set up a virtual environment** (optional but recommended):
```sh
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
```
2. **Install dependencies**:
```sh
pip install -r requirements.txt
```
3. **Create .env**:
Copy the example environment file and update with your settings:
```sh
cp env.example .env
```
4. **Install ngrok**:
Follow the instructions on the [ngrok website](https://ngrok.com/download) to download and install ngrok.
## Configure Twilio URLs
1. **Start ngrok**:
1. Start ngrok:
In a new terminal, start ngrok to tunnel the local server:
```sh
ngrok http 8765
```bash
ngrok http 7860
```
2. **Update the Twilio Webhook**:
> Want a fixed ngrok URL? Use the `--subdomain` flag:
> `ngrok http --subdomain=your_ngrok_name 7860`
2. Update the Twilio Webhook:
- Go to your Twilio phone number's configuration page
- Under "Voice Configuration", in the "A call comes in" section:
- Select "Webhook" from the dropdown
- Enter your ngrok URL (e.g., http://<ngrok_url>)
- Enter your ngrok URL: `https://your-ngrok-url.ngrok.io`
- Ensure "HTTP POST" is selected
- Click Save at the bottom of the page
3. **Configure streams.xml**:
3. Configure streams.xml:
- Copy the template file to create your local version:
To start a call, simply make a call to your configured Twilio phone number. The webhook URL will direct the call to your FastAPI application, which will handle it accordingly.
Create a `.env` file:
## Testing
```bash
cp env.example .env
```
It is also possible to test the server without making phone calls by using one of these clients.
- [python](client/python/README.md): This Python client enables automated testing of the server via WebSocket without the need to make actual phone calls.
- [typescript](client/typescript/README.md): This typescript client enables manual testing of the server via WebSocket without the need to make actual phone calls.
Then, 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 auto-hangup.
4. Run the Application
```bash
python server.py
```
### Test Your Phone Bot
**Call your Twilio phone number** to start talking with your AI bot! 🚀
> 💡 **Tip**: Check your server terminal for debug logs showing Pipecat's internal workings.
## Troubleshooting
- **Call doesn't connect**: Verify your ngrok URL is correctly set in both Twilio webhook and `streams.xml`
- **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 each restart - remember to update both Twilio and `streams.xml`
## Understanding the Call Flow
1.**Incoming Call**: User dials your Twilio number
2.**Webhook**: Twilio sends call data to your ngrok URL
3.**WebSocket**: Your server establishes real-time audio connection via Websocket and exchanges Media Streams with Twilio
4.**Processing**: Audio flows through your Pipecat Pipeline
5.**Response**: Synthesized speech streams back to caller
## Next Steps
- **Deploy to production**: Replace ngrok with a proper server deployment
- **Explore other telephony providers**: Try [Telnyx](https://github.com/pipecat-ai/pipecat-examples/tree/main/telnyx-chatbot) or [Plivo](https://github.com/pipecat-ai/pipecat-examples/tree/main/plivo-chatbot) examples
- **Advanced telephony features**: Check out [pipecat-examples](https://github.com/pipecat-ai/pipecat-examples) for call recording, transfer, and more
- **Join Discord**: Connect with other developers on [Discord](https://discord.gg/pipecat)
@@ -37,9 +37,7 @@ source .venv/bin/activate # On Windows: .venv\Scripts\activate
> Using `uv`? Create your venv using: `uv venv && source .venv/bin/activate`.
2. Install packages
Then, install the requirements:
2. Install dependencies
```bash
pip install -r requirements.txt
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Mark Backman