pipecat/examples/plivo-chatbot/README.md

Plivo Chatbot

This project is a FastAPI-based chatbot that integrates with Plivo 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 Plivo 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)
• Plivo 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 Plivo URLs

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

   ngrok http 8765
   

2. Update the Plivo Application:

   • Go to your Plivo console and navigate to Voice > Applications > XML
   • Select "Add New Application" or edit an existing one
   • Set the Primary Answer URL to your ngrok URL (e.g., https://<ngrok_url>/)
   • Ensure the Answer Method is set to POST
   • Save the application
   • Configure your number to use the newly created (or updated) application
     • Phone Numbers > Active > Your number
     • Select Application Type: XML Application
     • Plivo Application: Your application
     • Click "Update" to save

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

4. Assign the Application to a Plivo Number:

   • Go to Phone Numbers > Your Numbers in the Plivo console
   • Edit your Plivo number
   • Select the application you created/updated in the previous step
   • Save the configuration

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

Using Docker (Option 2)

1. Build the Docker image:

   docker build -t plivo-chatbot .
   

2. Run the Docker container:

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

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

Usage

To start a call, simply make a call to your configured Plivo phone number. The Answer URL will direct the call to your FastAPI application, which will handle it accordingly.

Key Differences from Twilio

• Plivo uses streamId instead of streamSid
• Plivo uses callId instead of callSid
• Plivo uses <Stream> element instead of <Connect><Stream>
• Plivo's Stream element has bidirectional, keepCallAlive, and contentType attributes
• Plivo API authentication uses Auth ID and Auth Token (similar to Twilio's Account SID and Auth Token)