From a22bebd174fd0f6604c12d57458eff4906a7cd04 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 29 Jul 2025 18:44:24 -0400 Subject: [PATCH] Update phone-bot-twilio README --- examples/client-server-web/README.md | 6 +- examples/phone-bot-twilio/README.md | 163 +++++++++--------- .../templates/streams.xml.template | 2 +- examples/quickstart/README.md | 4 +- 4 files changed, 87 insertions(+), 88 deletions(-) diff --git a/examples/client-server-web/README.md b/examples/client-server-web/README.md index aa6318334..026cbc8b4 100644 --- a/examples/client-server-web/README.md +++ b/examples/client-server-web/README.md @@ -35,9 +35,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 @@ -97,6 +95,8 @@ npm run dev 4. **Open http://localhost:5173 in your browser** and click `Connect` to start talking to your bot. +> ๐Ÿ’ก **Tip**: Check your server terminal for debug logs showing Pipecat's internal workings. + ## Troubleshooting - **Browser permissions**: Make sure to allow microphone access when prompted by your browser. diff --git a/examples/phone-bot-twilio/README.md b/examples/phone-bot-twilio/README.md index 9c7a4be95..c3d340e0c 100644 --- a/examples/phone-bot-twilio/README.md +++ b/examples/phone-bot-twilio/README.md @@ -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://) + - 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 `` with your ngrok URL (without `https://`) + - In `templates/streams.xml`, replace `` 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. \ No newline at end of file + 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) diff --git a/examples/phone-bot-twilio/templates/streams.xml.template b/examples/phone-bot-twilio/templates/streams.xml.template index 3d81d53d7..e69cc9db1 100644 --- a/examples/phone-bot-twilio/templates/streams.xml.template +++ b/examples/phone-bot-twilio/templates/streams.xml.template @@ -1,7 +1,7 @@ - + diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index d56aca703..eb811239c 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -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