Merge pull request #110 from pipecat-ai/mb/twilio-outbound-updates

Twilio Outbound: Improve the FastAPI server

Author: markbackman

twilio-chatbot/outbound/README.md

@@ -6,7 +6,7 @@ This project is a Pipecat-based chatbot that integrates with Twilio to make outb
 
 When you want to make an outbound call:
 
-1. **Send POST request**: `POST /start` with a phone number to call
+1. **Send POST request**: `POST /dialout` with a phone number to call
 2. **Server initiates call**: Uses Twilio's REST API to make the outbound call
 3. **Call answered**: When answered, Twilio fetches TwiML from your server's `/twiml` endpoint
 4. **Server returns TwiML**: Tells Twilio to start a WebSocket stream to your bot
@@ -16,7 +16,7 @@ When you want to make an outbound call:
 ## Architecture
 
 ```
-curl request → /start endpoint → Twilio REST API → Call initiated →
+curl request → /dialout endpoint → Twilio REST API → Call initiated →
 TwiML fetched → WebSocket connection → Bot conversation
 ```
 
@@ -30,7 +30,7 @@ TwiML fetched → WebSocket connection → Bot conversation
 
 ### AI Services
 
-- OpenAI API key for the LLM inference
+- Google API key for the LLM inference
 - Deepgram API key for speech-to-text
 - Cartesia API key for text-to-speech
 
@@ -97,7 +97,7 @@ The server will start on port 7860.
 
    > Tip: Use the `--subdomain` flag for a reusable ngrok URL.
 
-   Copy the ngrok URL (e.g., `https://abc123.ngrok.io`)
+   Copy the ngrok URL (e.g., `https://abc123.ngrok.io`) and update `LOCAL_SERVER_URL` in your `.env` file.
 
 3. No additional Twilio configuration needed
 
@@ -107,41 +107,22 @@ The server will start on port 7860.
 
 With the server running and exposed via ngrok, you can initiate outbound calls:
 
-### Basic Call
-
-```bash
-curl -X POST https://your-ngrok-url.ngrok.io/start \
-  -H "Content-Type: application/json" \
-  -d '{
-    "phone_number": "+1234567890"
-  }'
-```
-
-### Call with Body Data
-
-You can include arbitrary body data that will be available to your bot:
-
 ```bash
-curl -X POST https://your-ngrok-url.ngrok.io/start \
+curl -X POST https://your-ngrok-url.ngrok.io/dialout \
   -H "Content-Type: application/json" \
   -d '{
-    "phone_number": "+1234567890",
-    "body": {
-      "user": {
-        "id": "user123",
-        "name": "John Doe",
-        "account_type": "premium"
-      }
-    }
+    "to_number": "+15551234567",
+    "from_number": "+15559876543"
   }'
 ```
 
-The body data can be any JSON structure - nested objects, arrays, etc. Your bot will receive this data automatically.
-
 Replace:
 
 - `your-ngrok-url.ngrok.io` with your actual ngrok URL
-- `+1234567890` with the phone number you want to call
+- `+15551234567` with the phone number to call (E.164 format)
+- `+15559876543` with your Twilio phone number (E.164 format)
+
+> Note: the `from_number` must be a phone number owned by your Twilio account
 
 ## Production Deployment
 
@@ -181,31 +162,6 @@ As you did before, initiate a call via `curl` command to trigger your bot to dia
 
 ## Accessing Call Information in Your Bot
 
-Your bot automatically receives call information and body data through Twilio's Parameters:
-
-- **Body Data**: Any data you include in the `body` field is passed as a JSON string in the `body` parameter
-
-The Pipecat development runner extracts this data using the `parse_telephony_websocket` function:
-
-```python
-async def bot(runner_args: RunnerArguments):
-    transport_type, call_data = await parse_telephony_websocket(runner_args.websocket)
-
-    if transport_type == "twilio":
-        # Body data (JSON string parameter)
-        import json
-        body_param = call_data["custom_parameters"].get("body")
-        if body_param:
-            body_data = json.loads(body_param)
-
-            # Access nested data
-            user_data = body_data.get("user", {})
-            user_id = user_data.get("id")
-            user_name = user_data.get("name")
-            user_account_type = user_data.get("account_type")
-
-            # Use this data to personalize the conversation
-            print(f"User: {user_name} (ID: {user_id}, Type: {user_account_type})")
-```
+Your bot automatically receives call information through Twilio Stream Parameters. In this example, the phone numbers (`to_number` and `from_number`) are passed as parameters and extracted by the `parse_telephony_websocket` function.
 
-This allows your bot to provide personalized responses based on the body data and context.
+You can extend the `DialoutRequest` model in `server_utils.py` to include additional custom data (customer info, campaign data, etc.) and pass it through as stream parameters for personalized conversations. See `bot.py` for implementation details.

twilio-chatbot/outbound/bot.py

@@ -13,13 +13,14 @@
 from pipecat.pipeline.pipeline import Pipeline
 from pipecat.pipeline.runner import PipelineRunner
 from pipecat.pipeline.task import PipelineParams, PipelineTask
-from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
 from pipecat.runner.types import RunnerArguments
 from pipecat.runner.utils import parse_telephony_websocket
 from pipecat.serializers.twilio import TwilioFrameSerializer
 from pipecat.services.cartesia.tts import CartesiaTTSService
 from pipecat.services.deepgram.stt import DeepgramSTTService
-from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.services.google.llm import GoogleLLMService
 from pipecat.transports.base_transport import BaseTransport
 from pipecat.transports.websocket.fastapi import (
     FastAPIWebsocketParams,
@@ -33,7 +34,7 @@
 
 
 async def run_bot(transport: BaseTransport, handle_sigint: bool):
-    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
+    llm = GoogleLLMService(api_key=os.getenv("GOOGLE_API_KEY"))
 
     stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
 
@@ -53,8 +54,8 @@ async def run_bot(transport: BaseTransport, handle_sigint: bool):
         },
     ]
 
-    context = OpenAILLMContext(messages)
-    context_aggregator = llm.create_context_aggregator(context)
+    context = LLMContext(messages)
+    context_aggregator = LLMContextAggregatorPair(context)
 
     pipeline = Pipeline(
         [
@@ -95,10 +96,18 @@ async def on_client_disconnected(transport, client):
 
 async def bot(runner_args: RunnerArguments):
     """Main bot entry point compatible with Pipecat Cloud."""
-
     transport_type, call_data = await parse_telephony_websocket(runner_args.websocket)
     logger.info(f"Auto-detected transport: {transport_type}")
 
+    # Access custom stream parameters passed from TwiML
+    # Use the body data to personalize the conversation
+    # by loading customer data based on the to_number or from_number
+    body_data = call_data.get("body", {})
+    to_number = body_data.get("to_number")
+    from_number = body_data.get("from_number")
+
+    logger.info(f"Call metadata - To: {to_number}, From: {from_number}")
+
     serializer = TwilioFrameSerializer(
         stream_sid=call_data["stream_id"],
         call_sid=call_data["call_id"],

twilio-chatbot/outbound/env.example

@@ -1,11 +1,14 @@
-OPENAI_API_KEY=
+# Service keys
+GOOGLE_API_KEY=
 DEEPGRAM_API_KEY=
 CARTESIA_API_KEY=
+
+# Twilio credentials
 TWILIO_ACCOUNT_SID=
 TWILIO_AUTH_TOKEN=
-TWILIO_PHONE_NUMBER=
 
 # Environment configuration
 ENV=local
 AGENT_NAME=twilio-chatbot-dial-out
-ORGANIZATION_NAME=
+ORGANIZATION_NAME=
+LOCAL_SERVER_URL=https://your-url.ngrok.io

twilio-chatbot/outbound/pyproject.toml

@@ -5,7 +5,7 @@ description = "Twilio dial-out example for Pipecat"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-  "pipecat-ai[websocket,cartesia,openai,silero,deepgram,runner]>=0.0.85",
-  "pipecatcloud>=0.2.4",
+  "pipecat-ai[websocket,cartesia,google,silero,deepgram,runner]>=0.0.91",
+  "pipecatcloud>=0.2.7",
   "twilio"
 ]