Update phone-bot-twilio README
This commit is contained in:
Mark Backman
@@ -1,115 +1,116 @@
|
||||
# Twilio Chatbot
|
||||
# Phone Bot Twilio
|
||||
|
||||
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 Pipecat bot 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)
|
||||
- [Usage](#usage)
|
||||
- Python 3.10+
|
||||
- [ngrok](https://ngrok.com/docs/getting-started/) (for tunneling)
|
||||
- [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:
|
||||
```sh
|
||||
```bash
|
||||
cp templates/streams.xml.template templates/streams.xml
|
||||
```
|
||||
- In `templates/streams.xml`, replace `<your server url>` with your ngrok URL (without `https://`)
|
||||
- In `templates/streams.xml`, replace `<your_server_url>` with your ngrok URL (without `https://`)
|
||||
- The final URL should look like: `wss://abc123.ngrok.io/ws`
|
||||
|
||||
## Running the Application
|
||||
### Terminal 2: Server Setup
|
||||
|
||||
Choose one of these two methods to run the application:
|
||||
1. Set up a virtual environment
|
||||
|
||||
### Using Python (Option 1)
|
||||
From the `examples/phone-bot-twilio` directory, run:
|
||||
|
||||
**Run the FastAPI application**:
|
||||
|
||||
```sh
|
||||
# Make sure you’re in the project directory and your virtual environment is activated
|
||||
python server.py
|
||||
```
|
||||
|
||||
### Using Docker (Option 2)
|
||||
|
||||
1. **Build the Docker image**:
|
||||
|
||||
```sh
|
||||
docker build -t twilio-chatbot .
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
```
|
||||
|
||||
2. **Run the Docker container**:
|
||||
```sh
|
||||
docker run -it --rm -p 8765:8765 twilio-chatbot
|
||||
> Using `uv`? Create your venv using: `uv venv && source .venv/bin/activate`.
|
||||
|
||||
2. Install dependencies
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
The server will start on port 8765. Keep this running while you test with Twilio.
|
||||
> Using `uv`? Install requirements using: `uv pip install -r requirements.txt`.
|
||||
|
||||
## Usage
|
||||
3. Configure environment variables
|
||||
|
||||
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)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<Response>
|
||||
<Connect>
|
||||
<Stream url="wss://<your server url>/ws"></Stream>
|
||||
<Stream url="wss://<your_server_url>/ws"></Stream>
|
||||
</Connect>
|
||||
<Pause length="40"/>
|
||||
</Response>
|
||||
|
||||
Reference in New Issue
Block a user