129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# 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](#features)
|
|
- [Requirements](#requirements)
|
|
- [Installation](#installation)
|
|
- [Configure Plivo URLs](#configure-plivo-urls)
|
|
- [Running the Application](#running-the-application)
|
|
- [Usage](#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):
|
|
|
|
```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 Plivo URLs
|
|
|
|
1. **Start ngrok**:
|
|
In a new terminal, start ngrok to tunnel the local server:
|
|
|
|
```sh
|
|
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:
|
|
```sh
|
|
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**:
|
|
|
|
```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 plivo-chatbot .
|
|
```
|
|
|
|
2. **Run the Docker container**:
|
|
```sh
|
|
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)
|