Add PlivoFrameSerializer

examples/plivo-chatbot/README.md

@@ -0,0 +1,128 @@
+# 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)