Split transfer into transfer_to_number and transfer_to_sip, expand messaging examples

bevenky · bevenky · commit c4cc7b32b0ef · 2026-03-04T15:55:09.000-08:00
- Replace session.transfer() with transfer_to_number() (phone numbers)
  and transfer_to_sip() (SIP URI via Dial XML with custom headers)
- Expand send_sms.py with MMS single and multi-media examples
- Rewrite whatsapp.py with all 7 message types: text, media, template,
  interactive buttons, list, CTA URL, and location
- Add 4 new transfer tests (73 total)
diff --git a/README.md b/README.md
@@ -89,8 +89,8 @@ Sign up at [cx.plivo.com/signup](https://cx.plivo.com/signup) to get your `PLIVO
 - [**Background audio**](examples/background_audio.py) - ambient office/typing sounds mixed with agent speech
 - [**Pipeline modes**](examples/pipeline_modes.py) - all five config combinations in one file
 - [**Metrics & observability**](examples/metrics.py) - per-turn latency breakdown, VAD and turn events
-- [**SMS**](examples/send_sms.py) - send an SMS message
-- [**WhatsApp**](examples/whatsapp.py) - WhatsApp templates and interactive messages
+- [**SMS & MMS**](examples/send_sms.py) - text messages and MMS with media attachments
+- [**WhatsApp**](examples/whatsapp.py) - text, media, templates, buttons, lists, CTA, location
 - [**Buy a number**](examples/buy_number.py) - search and purchase a phone number
 - [**Callback server**](examples/callback_server.py) - FastAPI HTTP webhook receiver for call events
 - [**FastAPI integration**](examples/agent_fastapi.py) - embed VoiceApp inside an existing FastAPI app
diff --git a/examples/full_pipeline.py b/examples/full_pipeline.py
@@ -256,7 +256,7 @@ def on_tool_call(session, event: ToolCall):
 
     elif event.name == "transfer_to_human":
         session.speak("Let me transfer you to a specialist. One moment please.")
-        session.transfer("+18005551234")
+        session.transfer_to_number("+18005551234")
 
     elif event.name == "play_hold_music":
         session.play("hold_music.wav", allow_interruption=False)
diff --git a/examples/pipeline_modes.py b/examples/pipeline_modes.py
@@ -222,7 +222,7 @@ def on_tts_dtmf(session, event: Dtmf):
         session.speak("Your balance is forty two dollars and seventeen cents.")
     elif event.digit == "2":
         session.speak("Transferring you to an agent.")
-        session.transfer("+18005551234")
+        session.transfer_to_number("+18005551234")
     elif event.digit == "#":
         session.speak("Goodbye.")
         session.hangup()
diff --git a/examples/send_sms.py b/examples/send_sms.py
@@ -1,31 +1,75 @@
-"""Send an SMS message using the Plivo Agent SDK.
-
-Prerequisites:
-    pip install plivo_agent
+"""
+SMS & MMS Examples — Text and Media Messages
 
-Environment variables:
-    PLIVO_AUTH_ID      -- Your Plivo auth ID
-    PLIVO_AUTH_TOKEN   -- Your Plivo auth token
+Demonstrates sending SMS (text only) and MMS (with media attachments)
+using the Plivo Agent SDK.
 
-Run:
-    python send_sms.py
+Usage:
+  1. pip install plivo_agent
+  2. Set PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN env vars
+  3. python send_sms.py [sms | mms | mms-multi]
 """
 
 import asyncio
+import sys
 
 from plivo_agent import AsyncClient
 
+SRC = "+14155551234"  # your Plivo number
+DST = "+14155559876"  # recipient
+
+
+# --- SMS: plain text ---
 
-async def main():
+async def send_sms():
     async with AsyncClient() as client:
         response = await client.messages.create(
-            src="+14155551234",
-            dst="+14155559876",
+            src=SRC,
+            dst=DST,
             text="Hello from the Plivo Agent SDK!",
         )
-        print("Message UUID:", response["message_uuid"])
-        print("API ID:", response["api_id"])
+        print("SMS sent:", response["message_uuid"])
+
+
+# --- MMS: single image ---
+
+async def send_mms():
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            text="Check out this image!",
+            type_="mms",
+            media_urls=["https://media.plivo.com/demo/image-sample.jpg"],
+        )
+        print("MMS sent:", response["message_uuid"])
+
+
+# --- MMS: multiple media (image + PDF) ---
+
+async def send_mms_multi():
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            text="Here are your documents.",
+            type_="mms",
+            media_urls=[
+                "https://media.plivo.com/demo/image-sample.jpg",
+                "https://media.plivo.com/demo/invoice.pdf",
+            ],
+        )
+        print("MMS (multi) sent:", response["message_uuid"])
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    examples = {
+        "sms": send_sms,
+        "mms": send_mms,
+        "mms-multi": send_mms_multi,
+    }
+    choice = sys.argv[1] if len(sys.argv) > 1 else "sms"
+    if choice not in examples:
+        print(f"Usage: python send_sms.py [{' | '.join(examples)}]")
+        sys.exit(1)
+    asyncio.run(examples[choice]())
diff --git a/examples/whatsapp.py b/examples/whatsapp.py
@@ -1,43 +1,183 @@
-"""Send a WhatsApp template message using the Plivo Agent SDK.
-
-Prerequisites:
-    pip install plivo_agent
+"""
+WhatsApp Examples — All Message Types
 
-Environment variables:
-    PLIVO_AUTH_ID      -- Your Plivo auth ID
-    PLIVO_AUTH_TOKEN   -- Your Plivo auth token
+Demonstrates every WhatsApp message type supported by the SDK:
+text, media, template, interactive buttons, list, CTA URL, and location.
 
-Run:
-    python whatsapp.py
+Usage:
+  1. pip install plivo_agent
+  2. Set PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN env vars
+  3. python whatsapp.py [text | media | template | buttons | list | cta | location]
 """
 
 import asyncio
+import sys
 
 from plivo_agent import AsyncClient
-from plivo_agent.messaging import Template
+from plivo_agent.messaging import InteractiveMessage, Location, Template
+
+SRC = "+14155551234"  # your WhatsApp Business number
+DST = "+14155559876"  # recipient
+
+
+# --- Text message ---
+
+async def send_text():
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            text="Hello from the Plivo Agent SDK!",
+        )
+        print("Text sent:", response["message_uuid"])
+
 
+# --- Media message (image with caption) ---
 
-async def main():
+async def send_media():
     async with AsyncClient() as client:
-        # Build a WhatsApp template with body parameters
-        tpl = (
-            Template("order_confirmation", language="en")
-            .add_body_param("Alice")
-            .add_body_param("ORD-42")
-            .add_body_currency("$12.99", "USD", 12990)
-            .add_body_datetime("2026-03-07T10:30:00Z")
-            .add_button_param("url", 0, "https://example.com/track/ORD-42")
-            .build()
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            text="Here is your receipt.",
+            media_urls=["https://media.plivo.com/demo/image-sample.jpg"],
         )
+        print("Media sent:", response["message_uuid"])
+
 
+# --- Template message (with body params, currency, datetime, button) ---
+
+async def send_template():
+    tpl = (
+        Template("order_confirmation", language="en")
+        .add_header_media("https://media.plivo.com/demo/banner.jpg")
+        .add_body_param("Alice")
+        .add_body_param("ORD-42")
+        .add_body_currency("$12.99", "USD", 12990)
+        .add_body_datetime("2026-03-07T10:30:00Z")
+        .add_button_param("url", 0, "https://example.com/track/ORD-42")
+        .build()
+    )
+    async with AsyncClient() as client:
         response = await client.messages.create(
-            src="+14155551234",
-            dst="+14155559876",
+            src=SRC,
+            dst=DST,
             type_="whatsapp",
             template=tpl,
         )
-        print("Message UUID:", response["message_uuid"])
+        print("Template sent:", response["message_uuid"])
+
+
+# --- Interactive: quick reply buttons ---
+
+async def send_buttons():
+    interactive = InteractiveMessage.button(
+        body_text="How would you rate your experience?",
+        buttons=[
+            {"id": "great", "title": "Great"},
+            {"id": "okay", "title": "Okay"},
+            {"id": "poor", "title": "Poor"},
+        ],
+        header={"type": "text", "text": "Feedback"},
+        footer_text="Powered by Plivo",
+    )
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            interactive=interactive,
+        )
+        print("Buttons sent:", response["message_uuid"])
+
+
+# --- Interactive: list message ---
+
+async def send_list():
+    interactive = InteractiveMessage.list(
+        body_text="Browse our menu and pick your favorite.",
+        button_text="View Menu",
+        sections=[
+            {
+                "title": "Pizza",
+                "rows": [
+                    {"id": "margherita", "title": "Margherita", "description": "$10"},
+                    {"id": "pepperoni", "title": "Pepperoni", "description": "$12"},
+                ],
+            },
+            {
+                "title": "Sides",
+                "rows": [
+                    {"id": "fries", "title": "Fries", "description": "$4"},
+                    {"id": "salad", "title": "Garden Salad", "description": "$6"},
+                ],
+            },
+        ],
+        header_text="Mario's Pizza",
+        footer_text="Prices include tax",
+    )
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            interactive=interactive,
+        )
+        print("List sent:", response["message_uuid"])
+
+
+# --- Interactive: CTA URL ---
+
+async def send_cta():
+    interactive = InteractiveMessage.cta_url(
+        body_text="Track your order in real time.",
+        button_title="Track Order",
+        url="https://example.com/track/ORD-42",
+        footer_text="Powered by Plivo",
+    )
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            interactive=interactive,
+        )
+        print("CTA sent:", response["message_uuid"])
+
+
+# --- Location message ---
+
+async def send_location():
+    location = Location.build(
+        37.7749,
+        -122.4194,
+        name="Plivo HQ",
+        address="201 Spear St, San Francisco, CA 94105",
+    )
+    async with AsyncClient() as client:
+        response = await client.messages.create(
+            src=SRC,
+            dst=DST,
+            type_="whatsapp",
+            location=location,
+        )
+        print("Location sent:", response["message_uuid"])
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    examples = {
+        "text": send_text,
+        "media": send_media,
+        "template": send_template,
+        "buttons": send_buttons,
+        "list": send_list,
+        "cta": send_cta,
+        "location": send_location,
+    }
+    choice = sys.argv[1] if len(sys.argv) > 1 else "text"
+    if choice not in examples:
+        print(f"Usage: python whatsapp.py [{' | '.join(examples)}]")
+        sys.exit(1)
+    asyncio.run(examples[choice]())
diff --git a/src/plivo_agent/agent/session.py b/src/plivo_agent/agent/session.py
@@ -136,17 +136,17 @@ def play(self, file_path: str, *, allow_interruption: bool = True) -> None:
             msg["allow_interruption"] = False
         self._enqueue(msg)
 
-    def transfer(
+    def transfer_to_number(
         self,
         destination: str | list[str],
         *,
         dial_mode: str = "parallel",
         timeout: int = 30,
     ) -> None:
-        """Transfer the call to one or more destinations.
+        """Transfer the call to one or more phone numbers.
 
         Args:
-            destination: Phone number or list of numbers.
+            destination: Phone number or list of numbers (E.164 format).
             dial_mode: "parallel" (ring all at once, first to answer wins)
                        or "sequential" (try each in order).
             timeout: Ring timeout per destination in seconds.
@@ -160,6 +160,33 @@ def transfer(
             "timeout": timeout,
         })
 
+    def transfer_to_sip(
+        self,
+        sip_uri: str,
+        *,
+        sip_headers: dict[str, str] | None = None,
+        timeout: int = 30,
+    ) -> None:
+        """Transfer the call to a SIP endpoint via Plivo Dial XML.
+
+        Plivo uses ``<Dial><User>sip_uri</User></Dial>`` internally.
+
+        Args:
+            sip_uri: SIP URI (e.g. ``"sip:agent@phone.plivo.com"``).
+            sip_headers: Optional custom SIP headers (alphanumeric keys,
+                         max 24 chars each).
+            timeout: Ring timeout in seconds.
+        """
+        msg: dict = {
+            "type": "agent_session.transfer",
+            "destination": [sip_uri],
+            "sip": True,
+            "timeout": timeout,
+        }
+        if sip_headers:
+            msg["sip_headers"] = sip_headers
+        self._enqueue(msg)
+
     def hangup(self) -> None:
         """End the call."""
         self._enqueue({"type": "agent_session.hangup"})
diff --git a/tests/test_agent/test_session.py b/tests/test_agent/test_session.py
