Twilio Chatbot

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.

Table of Contents

• Features
• Requirements
• Installation
• Configure Twilio URLs
• Running the Application
• Usage

Features

• 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.

Requirements

• Python 3.10
• Docker (for containerized deployment)
• ngrok (for tunneling)
• Twilio Account

Installation

1. Set up a virtual environment (optional but recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

2. Install dependencies:

   pip install -r requirements.txt

3. Create .env: Copy the example environment file and update with your settings:

   cp env.example .env

4. Install ngrok: Follow the instructions on the ngrok website to download and install ngrok.

Configure Twilio URLs

1. Start ngrok: In a new terminal, start ngrok to tunnel the local server:

   ngrok http 8765

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>)
     • Ensure "HTTP POST" is selected
   • Click Save at the bottom of the page

3. Configure streams.xml:

   • Copy the template file to create your local version:

     cp templates/streams.xml.template templates/streams.xml

   • 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

Choose one of these two methods to run the application:

Using Python (Option 1)

Run the FastAPI application:

# Make sure you’re in the project directory and your virtual environment is activated
python server.py

Make an Outbound Call with twilio:

python outbound_call.py

Using Docker (Option 2)

1. Build the Docker image:

   docker build -t twilio-chatbot .

2. Run the Docker container:

   docker run -it --rm -p 8765:8765 twilio-chatbot

The server will start on port 8765. Keep this running while you test with Twilio.

Usage

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.

Note

This is a demo version based off examples from pipecat https://github.com/pipecat-ai/pipecat/tree/main/examples