Merge pull request #197 from pipecat-ai/twilio-sip-explicit-room-config

Use explicit Daily room config with SIP provider for Twilio bots

Author: markbackman

phone-chatbot/daily-pstn-cold-transfer/server.py

@@ -79,7 +79,9 @@ async def handle_incoming_daily_webhook(request: Request) -> JSONResponse:
 
         # Create a Daily room with dial-in capabilities
         try:
-            room_details = await configure(request.app.state.session, sip_caller_phone=caller_phone)
+            room_details = await configure(
+                request.app.state.session, sip_caller_phone=caller_phone, enable_dialout=True
+            )
         except Exception as e:
             logger.error(f"Error creating Daily room: {e}")
             raise HTTPException(status_code=500, detail=f"Failed to create Daily room: {str(e)}")

phone-chatbot/daily-pstn-dial-out/bot.py

@@ -87,7 +87,7 @@ async def attempt_dialout(self) -> bool:
         )
 
         # Build dialout settings with phone number and optional caller ID
-        dialout_params = {"phoneNumber": self._phone_number}
+        dialout_params = {"phoneNumber": self._phone_number, "displayName": self._phone_number}
         if self._caller_id:
             dialout_params["callerId"] = self._caller_id
             logger.info(f"Using caller ID: {self._caller_id}")

phone-chatbot/daily-pstn-dial-out/server_utils.py

@@ -107,7 +107,9 @@ async def create_daily_room(
     """
     try:
         return await configure(
-            session, sip_caller_phone=dialout_request.dialout_settings.phone_number
+            session,
+            sip_caller_phone="Test",
+            enable_dialout=True,
         )
     except Exception as e:
         logger.error(f"Error creating Daily room: {e}")

phone-chatbot/daily-pstn-warm-transfer/bot.py

@@ -190,7 +190,10 @@ async def process_frame(self, frame: Frame, direction: FrameDirection) -> None:
 
             # Dial the agent
             if self._transfer_target:
-                dialout_params = {"phoneNumber": self._transfer_target.phone_number}
+                dialout_params = {
+                    "phoneNumber": self._transfer_target.phone_number,
+                    "displayName": self._transfer_target.phone_number,
+                }
                 logger.info(f"Dialing agent: {self._transfer_target.phone_number}")
                 try:
                     await self._transport.start_dialout(dialout_params)

phone-chatbot/daily-twilio-sip-dial-in/README.md

@@ -1,17 +1,23 @@
-# Daily + Twilio SIP dial-in Voice Bot
+# Twilio Phone Number → Daily SIP → Pipecat Bot (Dial-in)
 
-This project demonstrates how to create a voice bot that can receive phone calls via Twilio and use Daily's SIP capabilities to enable voice conversations.
+This example shows how to receive inbound phone calls on a **Twilio phone number** and route them through **Daily's SIP infrastructure** to a **Pipecat voice bot**. The `provider="daily"` setting tells Daily to use its own SIP servers for the media path, so no external SIP trunk is required.
+
+> **Using a Daily phone number instead of Twilio?** See the [`daily-pstn-dial-in`](../daily-pstn-dial-in) example.
 
 ## How It Works
 
-1. Twilio receives an incoming call to your phone number
-2. Twilio calls your webhook server (`/call` endpoint in `server.py`)
-3. The server creates a Daily room with SIP capabilities
-4. The server starts the bot process with the room details (locally or via Pipecat Cloud)
-5. The caller is put on hold with music (a US ringtone in this example)
-6. The bot joins the Daily room and signals readiness
-7. Twilio forwards the call to Daily's SIP endpoint
-8. The caller and the bot are connected, and the bot handles the conversation
+```
+Caller → Twilio Phone Number → Webhook (server.py) → Daily SIP Room → Pipecat Bot
+```
+
+1. A caller dials your **Twilio phone number**
+2. Twilio sends a webhook to your server (`/call` endpoint in `server.py`)
+3. The caller hears hold music while the server handles the webhook
+4. The server creates a **Daily room** with SIP enabled (`provider="daily"`)
+5. The server starts the Pipecat bot (locally or via Pipecat Cloud)
+6. The bot joins the Daily room and signals readiness (`dialin-ready` fires)
+7. TwiML is invoked that asks Twilio to forward the call to Daily's SIP endpoint
+8. The caller and the bot are connected for a voice conversation
 
 ## Project Structure
 
@@ -175,6 +181,7 @@ class AgentRequest(BaseModel):
     token: str
     call_sid: str
     sip_uri: str
+    to_phone: str
     # Add your custom fields here
     customer_name: str | None = None
     account_id: str | None = None
@@ -191,6 +198,7 @@ agent_request = AgentRequest(
     token=sip_config.token,
     call_sid=call_data.call_sid,
     sip_uri=sip_config.sip_endpoint,
+    to_phone=call_data.to_phone,
     customer_name=customer_info.name,
     account_id=customer_info.id,
 )

phone-chatbot/daily-twilio-sip-dial-in/bot.py

@@ -98,7 +98,16 @@ async def on_dialin_ready(transport, sip_endpoint):
         logger.info(f"Forwarding call {request.call_sid} to {request.sip_uri}")
 
         try:
-            twilio_client = Client(os.getenv("TWILIO_ACCOUNT_SID"), os.getenv("TWILIO_AUTH_TOKEN"))
+            # Use to_phone to select Twilio credentials if you have multiple
+            # accounts (e.g., US vs EU). For now, we use a single set of credentials.
+            to_phone = request.to_phone
+            logger.info(f"Dialing in to {to_phone}")
+
+            account_sid = os.getenv("TWILIO_ACCOUNT_SID")
+            auth_token = os.getenv("TWILIO_AUTH_TOKEN")
+            logger.info(f"Using Twilio credentials for {to_phone}")
+
+            twilio_client = Client(account_sid, auth_token)
 
             # Update the Twilio call with TwiML to forward to the Daily SIP endpoint
             twilio_client.calls(request.call_sid).update(
@@ -114,6 +123,12 @@ async def on_dialin_error(transport, data):
         logger.error(f"Dial-in error: {data}")
         await task.cancel()
 
+    @transport.event_handler("on_dtmf_event")
+    async def on_dtmf_event(transport, data):
+        logger.info(f"DTMF event: {data}")
+        # Echo back the DTMF tone to the caller
+        # await transport.send_dtmf({"tones": data["tone"], "duration": 100})
+
     @transport.event_handler("on_client_connected")
     async def on_client_connected(transport, client):
         logger.info("Client connected")

phone-chatbot/daily-twilio-sip-dial-in/server.py

@@ -78,7 +78,9 @@ async def handle_call(request: Request):
 
     call_data = await twilio_call_data_from_request(request)
 
-    sip_config = await create_daily_room(call_data, request.app.state.http_session)
+    sip_config = await create_daily_room(
+        call_data, request.app.state.http_session, sip_provider="daily"
+    )
 
     # Make sure we have a SIP endpoint.
     if not sip_config.sip_endpoint:
@@ -89,6 +91,7 @@ async def handle_call(request: Request):
         token=sip_config.token,
         call_sid=call_data.call_sid,
         sip_uri=sip_config.sip_endpoint,
+        to_phone=call_data.to_phone,
     )
 
     # Start bot locally or in production.

phone-chatbot/daily-twilio-sip-dial-in/server_utils.py

@@ -41,6 +41,7 @@ class AgentRequest(BaseModel):
     token: str
     call_sid: str
     sip_uri: str
+    to_phone: str
 
 
 async def twilio_call_data_from_request(request: Request):
@@ -67,13 +68,16 @@ async def twilio_call_data_from_request(request: Request):
 
 
 async def create_daily_room(
-    call_data: TwilioCallData, session: aiohttp.ClientSession
+    call_data: TwilioCallData,
+    session: aiohttp.ClientSession,
+    sip_provider: str | None = None,
 ) -> DailyRoomConfig:
     """Create a Daily room configured for PSTN dial-in.
 
     Args:
         call_data: Call data containing caller phone number and call details
         session: Shared aiohttp session for making HTTP requests
+        sip_provider: Optional SIP provider name (e.g., "daily")
 
     Returns:
         DailyRoomConfig: Configuration object with room_url and token
@@ -82,7 +86,13 @@ async def create_daily_room(
         HTTPException: If room creation fails
     """
     try:
-        return await configure(session, sip_caller_phone=call_data.from_phone)
+        return await configure(
+            session,
+            sip_caller_phone=call_data.from_phone,
+            sip_provider=sip_provider,
+            enable_dialout=True,
+            room_geo="us-east-1",  # can set this to the same region as your Twilio number
+        )
     except Exception as e:
         logger.error(f"Error creating Daily room: {e}")
         raise HTTPException(status_code=500, detail=f"Failed to create Daily room: {e!s}")

phone-chatbot/daily-twilio-sip-dial-out/README.md

@@ -1,15 +1,21 @@
-# Daily + Twilio SIP dial-out Voice Bot
+# Pipecat Bot → Daily SIP → Twilio Phone Number (Dial-out)
 
-This project demonstrates how to create a voice bot that uses Daily's SIP capabilities with Twilio to make outbound calls to phone numbers.
+This example shows how a **Pipecat voice bot** can make outbound phone calls through **Daily's SIP infrastructure** to a **Twilio phone number**. The `provider="daily"` setting in the dial-out request tells Daily to use its own SIP servers for the media path.
+
+> **Using a Daily phone number instead of Twilio?** See the [`daily-pstn-dial-out`](../daily-pstn-dial-out) example — no Twilio SIP domain/TwiML configuration needed. However, Twilio has phone numbers in multiple regions.
 
 ## How It Works
 
-1. The server receives a dial-out request with the SIP URI to call
-2. The server creates a Daily room with SIP capabilities
-3. The server starts the bot process (locally or via Pipecat Cloud based on ENV)
-4. The bot joins the room and initiates the dial-out to the specified SIP URI
-5. Twilio receives the SIP request and processes it via configured TwiML
-6. Twilio rings the number found within the SIP URI
+```
+API Request (curl) → server.py → Spins up Pipecat Bot → Daily SIP dial-out → Twilio SIP Domain → Phone
+```
+
+1. Your server receives a dial-out request with the SIP URI and `provider`
+2. The server creates a **Daily room** with dial-out enabled
+3. The server starts the Pipecat bot (locally or via Pipecat Cloud)
+4. The bot joins the room and initiates the dial-out (`provider="daily"`)
+5. **Daily's SIP** sends the call to your **Twilio SIP domain**
+6. Twilio processes the call via your TwiML bin or webhook handler and rings the destination number
 7. The bot automatically retries on failure (up to 5 attempts)
 8. When the call is answered, the bot conducts the conversation
 
@@ -95,6 +101,8 @@ This example is organized to be production-ready and easy to customize:
    - callerId must be a valid number that you own on [Twilio](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming)
    - answerOnBridge="true|false" based on your use-case
    - Save the file. We will use this when creating the SIP domain
+ 
+note: `callerid` is hardcoded in the TwiML bin, to set it dynamically, the username field of the SIP URI can be overloaded to contain both the callerId and the destination number. `+1DESTINATION_+1CALLERID`.
 
 4. Create and configure a SIP domain
 
@@ -171,7 +179,8 @@ You'll need two terminal windows open:
      -H "Content-Type: application/json" \
      -d '{
        "dialout_settings": {
-         "sip_uri": "sip:+1234567890@daily.sip.twilio.com"
+         "sip_uri": "sip:+1234567890@daily.sip.twilio.com",
+         "provider": "daily"
        }
      }'
    ```
@@ -269,3 +278,5 @@ agent_request = AgentRequest(
 - Make sure both IP ACLs (0.0.0.0/1 and 128.0.0.0/1) are created and selected
 - Verify that the TwiML bin has a valid caller ID from your Twilio account
 - Check that the SIP domain name matches what you're using in the SIP URI
+
+Note: Setting Daily Provider come with the advantage of using Static IPs, which means you can set a smaller set of IP in the ACLs and have reliable SIP connectivity.

phone-chatbot/daily-twilio-sip-dial-out/bot.py

@@ -51,6 +51,7 @@ def __init__(
     ):
         self._transport = transport
         self._sip_uri = dialout_settings.sip_uri
+        self._provider = dialout_settings.provider
         self._max_retries = max_retries
         self._attempt_count = 0
         self._is_successful = False
@@ -79,8 +80,16 @@ async def attempt_dialout(self) -> bool:
         logger.info(
             f"Attempting dialout (attempt {self._attempt_count}/{self._max_retries}) to: {self._sip_uri}"
         )
-
-        await self._transport.start_dialout({"sipUri": self._sip_uri})
+        sip_uri = self._sip_uri
+        display_name = sip_uri  # fallback
+        if sip_uri.startswith("sip:") and "@" in sip_uri:
+            phone_part = sip_uri[4:]  # Remove 'sip:' prefix
+            display_name = phone_part.split("@")[0]  # Get everything before '@'
+
+        params = {"sipUri": sip_uri, "displayName": display_name}
+        if self._provider:
+            params["provider"] = self._provider
+        await self._transport.start_dialout(params)
         return True
 
     def mark_successful(self):
@@ -169,6 +178,25 @@ async def on_dialout_answered(transport, data):
         logger.debug(f"Dial-out answered: {data}")
         dialout_manager.mark_successful()
 
+    @transport.event_handler("on_dialout_connected")
+    async def on_dialout_connected(transport, data):
+        logger.debug(f"Dial-out connected: {data}")
+
+    @transport.event_handler("on_dialout_stopped")
+    async def on_dialout_stopped(transport, data):
+        logger.debug(f"Dial-out stopped: {data}")
+        await task.cancel()
+
+    @transport.event_handler("on_dialout_warning")
+    async def on_dialout_warning(transport, data):
+        logger.debug(f"Dial-out warning: {data}")
+
+    @transport.event_handler("on_dtmf_event")
+    async def on_dtmf_event(transport, data):
+        logger.info(f"DTMF event: {data}")
+        # Echo back the DTMF tone to the caller
+        # await transport.send_dtmf({"tones": data["tone"], "duration": 100})
+
     @transport.event_handler("on_dialout_error")
     async def on_dialout_error(transport, data: Any):
         logger.error(f"Dial-out error, retrying: {data}")