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

[ryanrouleau]

Summary

Developers using TAC's voice channel previously couldn't customize TwiML beyond welcome_greeting — the rest of the ConversationRelay surface was hardcoded. This PR opens it up.

What you can do now

Configure TwiML once on VoiceChannelConfig:

VoiceChannelConfig(
    default_twiml_options=TwiMLOptions(
        voice="en-US-Journey-D",
        language="en-US",
        interruptible="speech",
        languages=[LanguageConfig(code="es-MX", voice="es-MX-Neural2-A")],
    ),
)

Or hook in per-call logic for inbound:

async def by_country(req: TwiMLRequest) -> TwiMLOptions:
    if req.caller_country == "MX":
        return TwiMLOptions(language="es-MX", welcome_greeting="¡Hola!")
    return TwiMLOptions()

voice_channel.on_inbound_call_twiml(by_country)

For outbound, pass per-call data at the call site:

await voice_channel.initiate_outbound_conversation(
    InitiateVoiceConversationOptions(
        to="+1...",
        twiml_options=TwiMLOptions(custom_parameters={"campaign_id": "abc"}),
    )
)

Both directions share default_twiml_options. Per-call layers win over channel defaults; layers merge per-field (only fields you explicitly set override lower layers).

Centralized URL construction

Voice URL construction (websocket + action URLs) moved from TACFastAPIServer to TACConfig + VoiceChannel. The server registers routes; the channel owns the URLs. This makes the voice channel usable from custom adapters (Flask/Django/etc.) without re-plumbing URLs through the server. See Breaking changes for the API shape.

Breaking changes

URL construction moved off TACFastAPIServer. If you've configured TAC for voice before, the changes you'll notice:

• TACFastAPIServer no longer accepts welcome_greeting or public_domain. Those fields are gone from TACServerConfig. Set TACConfig.voice_public_domain (or TWILIO_VOICE_PUBLIC_DOMAIN) for the public domain, and VoiceChannelConfig.default_twiml_options for the greeting.
• InitiateVoiceConversationOptions no longer accepts welcome_greeting, action_url, or custom_parameters as flat fields. Pass them on twiml_options: InitiateVoiceConversationOptions(to=..., twiml_options=TwiMLOptions(welcome_greeting=...)) or on the VoiceChannelConfig's default_twiml_options.
• TACFastAPIServer raises ValueError at construction when a voice channel is attached but no public URL is configured (no voice_public_domain, no websocket_url override). Previously the server would start and the misconfiguration only surfaced as a 500 on the first inbound call.
• VoiceChannelConfig.websocket_url and action_url validate their schemes. websocket_url must start with ws:// or wss://; action_url must start with http:// or https://. Bare domains and mismatched schemes now raise at construction.

For custom adapters (Flask/Django/etc.) that bypass TACFastAPIServer and call the voice channel APIs directly:

• VoiceEndpoints is removed. The channel reads URLs from its own config now instead of receiving them per-call.
• VoiceChannel.handle_incoming_call(endpoints, twiml_request=None) → handle_incoming_call(twiml_request=None). URLs are derived from TACConfig.voice_public_domain + VoiceChannelConfig paths.
• generate_twiml(options) → generate_twiml(websocket_url, options=None). WebSocket URL is now a required positional argument.
• VoiceChannel raises ValueError on first request if it can't resolve a WebSocket URL. Previously the server emitted a soft warning that produced malformed TwiML at runtime.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring

Checklist

• Tests added/updated — full attribute coverage, <Language> emission, merge semantics across all layers, action_url precedence, deprecation forwarding, and an end-to-end server→channel→customizer flow.
• Documentation updated — docstrings on VoiceChannelConfig, VoiceChannel.handle_incoming_call, initiate_outbound_conversation, TACFastAPIServer, and all new models. Example at getting_started/examples/features/voice_twiml_customization.py.
• Tested E2E

SDK Parity

This is the Python SDK. If this change affects shared functionality, ensure the TypeScript SDK is updated as well.

• Change is Python-specific (no TypeScript update needed)
• TypeScript SDK PR created:

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR expands the voice channel’s TwiML customization surface so applications can control most (or all) ConversationRelay attributes without reimplementing the FastAPI server. It introduces structured request context parsing for Twilio’s /twiml webhook, adds static + per-request TwiML option layering on VoiceChannel, and widens TwiMLOptions to cover many more ConversationRelay attributes (including <Language> children).

Changes:

• Added TwiMLRequest parsing + VoiceEndpoints to separate server-owned URLs from channel-owned TwiML options.
• Expanded TwiMLOptions (and LanguageConfig) and updated TwiML generation to emit the new attributes and children.
• Added per-channel static TwiML options plus an async customizer callback, and adjusted server/tests/examples accordingly.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/tac/models/voice.py	Adds TwiMLRequest, VoiceEndpoints, LanguageConfig, and significantly widens TwiMLOptions.
src/tac/channels/voice/twiml.py	Refactors TwiML generation to accept websocket_url separately and emit many more ConversationRelay attributes + <Language> children.
src/tac/channels/voice/config.py	Introduces static twiml_options and async customize_twiml_options on VoiceChannelConfig.
src/tac/channels/voice/channel.py	Implements layered merge semantics, moves action_url resolution into the channel, and updates handle_incoming_call API.
src/tac/server/fastapi_server.py	Parses Twilio form data into TwiMLRequest and passes VoiceEndpoints into the channel.
src/tac/server/config.py	Deprecates TACServerConfig.welcome_greeting with a warning and changes its default to None.
tests/test_voice_models.py	Adds unit tests for TwiMLRequest.from_form, LanguageConfig, and VoiceEndpoints.
tests/test_voice_channel.py	Updates existing tests and adds coverage for expanded TwiML attributes and merge semantics.
tests/test_server.py	Updates server defaults and adds end-to-end customizer + deprecated welcome_greeting forwarding tests.
tests/test_relay_only_mode.py	Updates relay-only TwiML tests to use VoiceEndpoints + channel static options.
getting_started/examples/features/voice_twiml_customization.py	Adds a usage example showing static and per-call TwiML customization.

Comments suppressed due to low confidence (1)

src/tac/server/fastapi_server.py:212

• Since post_twiml() now points at conversation_relay_callback_path by default, that callback endpoint becomes part of the normal call flow. It currently has no Twilio signature validation dependency, unlike /twiml and /webhook. Consider adding the same http signature dependency to the conversation_relay_callback route to prevent spoofed cleanup callbacks.

                endpoints = VoiceEndpoints(
                    websocket_url=f"wss://{config.public_domain}{config.websocket_path}",
                    action_url=(
                        f"https://{config.public_domain}{config.conversation_relay_callback_path}"
                    ),
                )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

[ryanrouleau]

Putting this callback here, in anticipation of more crelay callbacks being added to the voice channel in the near future, like:

voice_channel.on_inbound_call_twiml()
voice_channel.on_interrupt() # move from tac.on_interrupt()
voice_channel.on_dtmf()
...

Idea being omnichanell / TAC wide callbacks are registered directly on tac like on_message_ready. Channel specific lifecycle is on channel specifically to keep things clean / don't spread crelay stuff to core TAC

[ryanrouleau]

websocket_url and action_url is constructed by the channel so no need to construct manually and pass in

[ryanrouleau]

Adding types for all crelay twiml options. There's an optional extra field if crelay adds new twiml that we don't have typed

[ryanrouleau]

welcome_greeting set here instead of on the server

[ryanrishi]

Is there a way to deprecate the fields likewelcome_greeting, action_url, custom_parameters? Otherwise these fields will be silently ignored since the model config doesn't set extra="forbid". Callers migrating from v1.0.1 won't get any signal that their code stopped working.

We can add a deprecated_fields class decorator + utility that:

• Sets extra="allow" so Pydantic captures unknown fields in model_extra
• Injects a model_validator(mode="after") that emits DeprecationWarning for recognized old field names
• Stores metadata in __deprecated_fields__ (PEP 702 convention) for future doc generator support

# src/tac/utils/deprecation.py

@dataclass(frozen=True)
class DeprecatedInfo:
    since: str
    removal: str | None = None
    alternative: str | None = None

    @property
    def message(self) -> str:
        msg = f"Deprecated in tac {self.since}."
        if self.removal:
            msg += f" Will be removed in {self.removal}."
        if self.alternative:
            msg += f" Use {self.alternative} instead."
        return msg


def deprecated_fields(**fields: DeprecatedInfo):
    """Class decorator for Pydantic models with removed fields."""
    ...

Call site:

@deprecated_fields(
    welcome_greeting=DeprecatedInfo(
        since="1.0.2", removal="2.0",
        alternative="twiml_options=TwiMLOptions(welcome_greeting=...)",
    ),
    action_url=DeprecatedInfo(
        since="1.0.2", removal="2.0",
        alternative="twiml_options=TwiMLOptions(action_url=...)",
    ),
    custom_parameters=DeprecatedInfo(
        since="1.0.2", removal="2.0",
        alternative="twiml_options=TwiMLOptions(custom_parameters=...)",
    ),
)
class InitiateVoiceConversationOptions(BaseModel):
    model_config = {"populate_by_name": True, "extra": "allow"}
    ...

Warning output:

InitiateVoiceConversationOptions.welcome_greeting was deprecated in tac 1.0.2 and will be removed in 2.0. Use twiml_options=TwiMLOptions(welcome_greeting=...) instead. The value passed here is being ignored.

This also works as a standalone decorator for methods/classes (@deprecated(since="1.0.2", ...)), and supports per-field version timelines when fields are deprecated at different points.

This won't be the last time we deprecate something so it might be worth wiring a deprecation util up now so we can reuse it in the future.

[ryanrishi]

Is there any way to inherit these from the TACServerConfig (if using TAC Server), or enforce that the paths match somehow?

[ryanrouleau]

I'm taking a second look at this. Originally split to support the case where TAC's public URL may not match it's internal URL (e.g. like behind a proxy or gateway) but it's complicating things

[ryanrouleau]

Ok I simplified this and abandoned the use case of splitting the URLs (can revisit if needed). The source of truth of the paths are now on TACConfig which everything reads from

[ryanrouleau]

@ryanrishi

Is there a way to deprecate the fields likewelcome_greeting, action_url, custom_parameters? Otherwise these fields will be silently ignored since the model config doesn't set extra="forbid". Callers migrating from v1.0.1 won't get any signal that their code stopped working.

Added extra="forbid" here to throw an error for users that upgrade. Originally had these fields deprecated throughout but ended up just removing them after our stand up discussion a few days ago