pipecat/examples/telnyx-chatbot

Telnyx Chatbot

This project is a FastAPI-based chatbot that integrates with Telnyx to handle WebSocket connections and provide real-time communication. The project includes endpoints for starting a call and handling WebSocket connections.

Table of Contents

• Telnyx Chatbot
  • Table of Contents
  • Features
  • Requirements
  • Installation
  • Configure Telnyx TeXML application
  • Running the Application
    • Using Python (Option 1)
    • Using Docker (Option 2)
  • 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)
• Telnyx 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 Telnyx TeXML application

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

   ngrok http 8765
   

2. Purchase a number

   If you haven't already, purchase a number from Telnyx.

   • Log in to the Telnyx developer portal: https://portal.telnyx.com/
   • Buy a number: https://portal.telnyx.com/#/numbers/buy-numbers

3. Update the Telnyx TeXML applications Webhook:

   • Go to your TeXML configuration page: https://portal.telnyx.com/#/call-control/texml
   • Create a new TeXML app, if one doesn't exist already:
     • Add an application name
     • Under Webhooks, select POST as the "Voice Method"
     • Select "Custom URL" under Webhook URL Method
     • Enter your ngrok URL in the "Webhook URL" field (e.g. https://your-name.ngrok.io)
     • Click "Create" to save Note: You'll see subsequent pages to set up SIP and Outbound, both are not required, so just skip.
   • Navigate to "Manage Numbers" (https://portal.telnyx.com/#/numbers/my-numbers) and under SIP connection, select the pencil icon to edit and select the TeXML application that you just created.

   Now your number is ready to call.

4. 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. This needs to be the same URL that you added to your TeXML app above.
   • The encoding (bidirectionalCodec) should be PCMU or PCMA depending on your needs. Based on selected encoding, set the outbound_encoding in server.py when the bot is initialized. (No changes are required by default.)
   • The inbound encoding can be controlled from the application configuration for inbound calls and dial/transfer commands for outbound calls.

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 telnyx-chatbot .
   

2. Run the Docker container:

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

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

Usage

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