feat(voice): full ConversationRelay TwiML customization for inbound and outbound

getting_started/examples/features/outbound.py

@@ -41,8 +41,8 @@
 )
 from tac.models.session import ConversationSession
 from tac.models.tac import TACMemoryResponse
+from tac.models.voice import TwiMLOptions
 from tac.server import TACFastAPIServer
-from tac.server.config import TACServerConfig
 
 load_dotenv()
 set_tracing_disabled(True)
@@ -91,7 +91,17 @@ def parse_args() -> argparse.Namespace:
     if tac.config.whatsapp_number
     else None
 )
-voice_channel = VoiceChannel(tac, config=VoiceChannelConfig(memory_mode="always"))
+voice_channel = VoiceChannel(
+    tac,
+    config=VoiceChannelConfig(
+        memory_mode="once",
+        # Channel-wide TwiML applied to every call (inbound + outbound).
+        default_twiml_options=TwiMLOptions(
+            voice="en-US-Journey-D",
+            welcome_greeting="Hi! How can I help?",
+        ),
+    ),
+)
 
 
 async def handle_message_ready(
@@ -162,18 +172,11 @@ async def initiate_outbound(args: argparse.Namespace) -> None:
             print("\nWaiting for replies... (Ctrl+C to exit)\n")
 
         elif args.channel == "voice":
-            server_config = TACServerConfig.from_env()
-            public_domain = server_config.public_domain
-            if not public_domain:
-                print("TWILIO_VOICE_PUBLIC_DOMAIN is required for voice calls.")
-                sys.exit(1)
-
             voice_result = await voice_channel.initiate_outbound_conversation(
                 InitiateVoiceConversationOptions(
                     to=args.to,
-                    websocket_url=f"wss://{public_domain}/ws",
-                    welcome_greeting=args.welcome_greeting,
-                    action_url=f"https://{public_domain}/conversation-relay-callback",
+                    # Per-call TwiML overrides for this outbound call. Overrides channel defaults
+                    twiml_options=TwiMLOptions(welcome_greeting=args.welcome_greeting),
                 )
             )
             print(f"Call placed to {args.to} (SID: {voice_result.call_sid})")

getting_started/examples/features/voice_twiml_customization.py

@@ -0,0 +1,82 @@
+"""
+Feature: ConversationRelay TwiML customization
+
+Two layers (highest precedence first):
+
+1. Per-call customizer — register on the channel via
+   ``voice_channel.on_inbound_call_twiml(...)``. Async callable that
+   receives a TwiMLRequest (parsed Twilio webhook fields: From, To,
+   CallerCountry, …). Inbound only. For outbound, pass per-call
+   TwiMLOptions on InitiateVoiceConversationOptions.
+2. ``VoiceChannelConfig.default_twiml_options`` — static TwiMLOptions
+   applied to every call (inbound and outbound).
+
+Layers merge per-field: the customizer overrides only the fields it
+explicitly sets; everything else falls through to ``default_twiml_options``
+and then to TAC defaults (websocket URL, action URL, conversation_configuration).
+
+This example shows both layers together — channel-wide defaults plus a
+country-based customizer that overrides language/voice/greeting for
+specific callers.
+"""
+
+from dotenv import load_dotenv
+
+from tac import TAC, TACConfig
+from tac.channels.voice import VoiceChannel, VoiceChannelConfig
+from tac.models.session import ConversationSession
+from tac.models.tac import TACMemoryResponse
+from tac.models.voice import TwiMLOptions, TwiMLRequest
+from tac.server import TACFastAPIServer
+
+load_dotenv()
+
+tac = TAC(config=TACConfig.from_env())
+
+
+async def handle_message_ready(
+    user_message: str,
+    context: ConversationSession,
+    memory_response: TACMemoryResponse | None,
+) -> str:
+    return f"You said: {user_message}"
+
+
+tac.on_message_ready(handle_message_ready)
+
+
+async def customize_twiml(req: TwiMLRequest) -> TwiMLOptions:
+    """Per-call overrides for inbound calls. Only the fields you set here
+    override the channel default; the rest fall through."""
+    if req.caller_country == "MX":
+        return TwiMLOptions(
+            language="es-MX",
+            welcome_greeting="¡Hola! ¿En qué puedo ayudarte?",
+        )
+    if req.caller_country == "FR":
+        return TwiMLOptions(
+            language="fr-FR",
+            welcome_greeting="Bonjour ! Comment puis-je vous aider ?",
+        )
+    return TwiMLOptions()  # fall through to default_twiml_options
+
+
+voice_channel = VoiceChannel(
+    tac,
+    config=VoiceChannelConfig(
+        # Channel-wide defaults — apply to every call (inbound + outbound).
+        default_twiml_options=TwiMLOptions(
+            welcome_greeting="Hello! This is a default greeting.",
+            interruptible="speech",
+            # Escape hatch for ConversationRelay attributes TAC hasn't typed yet:
+            # extra={"newRelayAttribute": "value"},
+        ),
+    ),
+)
+# Register the per-call inbound customizer.
+voice_channel.on_inbound_call_twiml(customize_twiml)
+
+
+if __name__ == "__main__":
+    server = TACFastAPIServer(tac=tac, voice_channel=voice_channel)
+    server.start()

src/tac/channels/voice/__init__.py

@@ -1,7 +1,22 @@
 """Voice channel for handling voice-based conversations."""
 
 from tac.channels.voice.channel import VoiceChannel
-from tac.channels.voice.config import VoiceChannelConfig
+from tac.channels.voice.config import InboundCallTwiMLHandler, VoiceChannelConfig
 from tac.channels.voice.twiml import generate_twiml
+from tac.models.voice import (
+    InterruptMode,
+    LanguageConfig,
+    TwiMLOptions,
+    TwiMLRequest,
+)
 
-__all__ = ["VoiceChannel", "VoiceChannelConfig", "generate_twiml"]
+__all__ = [
+    "InboundCallTwiMLHandler",
+    "InterruptMode",
+    "LanguageConfig",
+    "TwiMLOptions",
+    "TwiMLRequest",
+    "VoiceChannel",
+    "VoiceChannelConfig",
+    "generate_twiml",
+]