Vitlycare Twilio Inbound

This project is a Pipecat-based chatbot that integrates with Twilio to handle inbound phone calls via WebSocket connections and provide real-time voice conversations.

Table of Contents

• How It Works
• Prerequisites
• Setup
• Environment Configuration
• Local Development
• Customizing your Bot

How It Works

When someone calls your Twilio number:

1. Twilio sends WebSocket messages: Twilio processes the associated TwiML Bin and starts a WebSocket stream to your bot (local or Pipecat Cloud)
2. Parse the WebSocket messages: Your bot parses the WebSocket connection messages to set up the corresponding Pipecat transport
3. (Optional) Look up the caller: Optionally, look up the caller using Twilio's REST API to retrieve custom information about the call and personalize your bot's behavior
4. Bot starts responding: Once the pipeline is started, your bot will initiate the conversation

Prerequisites

Twilio

• A Twilio account with:
  • Account SID and Auth Token
  • A purchased phone number that supports voice calls

AI Services

• OPENAI API key for the LLM inference
• Deepgram API key for speech-to-text and text-to-speech is required

System

• Python 3.10+
• uv package manager
• ngrok (for local development)

Setup

1. Set up a virtual environment and install dependencies:

   cd vitlycare-inbound 
   uv sync

2. Create an .env file and add API keys:

   cp env.example .env

Local Development

Configure Twilio

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

   ngrok http 7860

   Tip: Use the --subdomain flag for a reusable ngrok URL.

2. Create a TwiML Bin:

   • Go to your Twilio Console: https://console.twilio.com/

   • Navigate to TwiML Bins > My TwiML Bins

   • Click the + to create a new TwiML Bin

   • Name your bin and add the TwiML containing your ngrok URL:

     <?xml version="1.0" encoding="UTF-8"?>
     <Response>
     <Connect>
        <Stream url="wss://your-url.ngrok.io/ws" />
     </Connect>
     </Response>

   • Click "Save"

3. Assign the TwiML Bin to your number:

   • Navigate to Phone Numbers > Manage > Active numbers
   • Click on your Twilio phone number
   • In the "Voice Configuration" section:
     • Set "A call comes in" to "TwiML Bin"
     • Select the name of your TwiML Bin from step 2
   • Click "Save configuration"

Run your Bot

Run your bot by passing in the twilio command line arg

uv run bot.py --transport twilio

Note: This bot uses Pipecat's development runner, which runs a FastAPI server that handles and routes incoming WebSocket messages to your bot.

Call your Bot

Place a call to the number associated with your bot. The bot will answer and start the conversation.

Customizing your Bot

The bot.py example file is configured to look up the caller's phone number by calling Twilio's REST API using the Call SID. With this information, you can:

• Perform a lookup in your own database to retrieve customer information
• Personalize the bot's greeting and behavior based on the caller