feat(voice): outbound Calls API passthrough, call events & AMD

[ryanrouleau]

Summary

Enables AMD and recording on outbound ConversationRelay calls, and reports call disposition (unanswered / busy / failed) — for outbound chase campaigns that need to hang up on voicemail and know which calls went unreached.

Four surfaces:

1. CallOptions — InitiateVoiceConversationOptions.call_options carries the calls.create parameters (machine_detection, async_amd, record, timeout, SIP auth, …). Typed for the ones outbound ConversationRelay reaches for, open for the rest. Unknown keys are rejected at construction against the installed SDK's signature, so a typo fails there rather than as a TypeError inside the Twilio client. to / from_ / twiml / url / application_sid are TAC-owned and refused.

2. Per-callback handlers — on_call_status / on_amd / on_recording, each with its own typed event (CallStatusEvent / AmdEvent / RecordingEvent), each independently optional. TACFastAPIServer serves one route per callback under voice_call_event_path (/status, /amd, /recording), so the route identifies the event — no payload sniffing. AmdEvent.is_machine and CallStatusEvent.is_unreached keep callers off mode-specific strings (unknown is not a machine, so a call is never hung up on a guess).

3. end_call(call_sid) — hangs up (works on CallSid alone, in any mode, before a session exists) and best-effort tears down the ConversationRelay session. Returns whether Twilio accepted it; never raises, since hanging up an already-ended call is routine. Call it from on_amd to drop voicemail.

4. get_conversation_session_by_call_sid(call_sid) — call events carry only the CallSid, but the session-facing methods (send_response, get_websocket) are keyed by conversation id, which is the Orchestrator conversation id in orchestrator mode. This crosses that gap for handlers that need more than end_call.

Callback URL auto-wiring. A URL derives from voice_public_domain + voice_call_event_path only when its handler is registered — otherwise TAC would point Twilio at a 404 (error 11200) on every outbound call for anyone not using TACFastAPIServer. Precedence, highest first: per-call call_options > VoiceChannelConfig.default_call_options > derived URL. Set the URLs in default_call_options for a custom server or non-default routes. TACConfig.call_event_path() is the single source for both the URL handed to Twilio and the route serving it, so they can't drift.

AMD requires both machine_detection and async_amd — enforced at construction. machine_detection turns detection on; without async_amd, Twilio returns AnsweredBy on the TwiML request, which inline TwiML can't receive. Either flag alone is a silent dead end.

Session correlation. ConversationSession.call_sid is populated on the Voice channel, matching the call events and the outbound result. Sessions are created on the caller's first prompt, so on_call_status / on_recording resolve one while on_amd under machine_detection="Enable" fires too early and usually won't — which is why end_call needs none.

Also: <Parameter> values are masked in the outbound TwiML debug log (they carry arbitrary custom_parameters — profile IDs, caller names), and voice_call_event_path is validated at server construction for a leading slash and for sub-paths colliding with another POST route.

New config: voice_call_event_path / TWILIO_VOICE_CALL_EVENT_PATH.

Tested E2E

Outbound call to a mobile that went to voicemail; orchestrator mode, ngrok, machine_detection="Enable" + record=True. Timings relative to answer:

• All three callbacks hit their auto-wired routes — AMD +4s, status +4s, recording +8s
• answered_by=machine_start → is_machine → end_call hung up ~4s after answer, instead of monologuing at a machine
• Recording delivered with a fetchable URL
• Disposition reported completed, correctly not is_unreached — the call was answered, just by a machine. Counting voicemails needs the AMD event; the status disposition alone can't distinguish it from a human.

Not yet exercised: the human-answer path and ring-out (is_unreached).

Type of Change

• New feature

Checklist

• Tests added/updated
• Documentation updated (docstrings + example)
• Tested E2E

SDK Parity

This is the Python SDK. The same surfaces should land in the TypeScript SDK.

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

[Copilot]

Pull request overview

This PR extends the Voice channel’s outbound calling support by forwarding Twilio Calls API parameters via typed call_options, adding first-class call-event webhooks (status / AMD / recording) with per-event handlers and FastAPI routes, and enabling best-effort call hangup + session cleanup via end_call(call_sid). It also adds TwiML log redaction for <Parameter value="..."> to reduce accidental logging of developer-supplied data.

Changes:

• Add CallOptions + InitiateVoiceConversationOptions.call_options passthrough to client.calls.create(...), including auto-wiring of callback URLs when handlers are registered.
• Add call event models (CallStatusEvent, AmdEvent, RecordingEvent) + VoiceChannel handlers (on_call_status, on_amd, on_recording) and FastAPI routes under voice_call_event_path.
• Add ConversationSession.call_sid correlation + VoiceChannel.end_call(call_sid) and a getting-started example for call events.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_voice_channel.py	Adds unit tests for call-event paths, event models/predicates, handlers, end_call, and call-sid session lookup.
tests/test_server.py	Adds FastAPI server validation and routing tests for call-event endpoints.
tests/test_redaction.py	Adds tests for TwiML <Parameter> value redaction.
tests/test_outbound.py	Adds outbound call-option passthrough + auto-wiring + default-call-options layering tests.
src/tac/utils/redaction.py	Introduces redact_twiml_parameters() for masking <Parameter value="..."> in TwiML logs.
src/tac/server/fastapi_server.py	Registers 3 call-event POST routes and validates voice_call_event_path expansion/collisions.
src/tac/models/voice.py	Adds typed call-event webhook models and parsing with from_form(...).
src/tac/models/session.py	Adds ConversationSession.call_sid for correlating calls and events.
src/tac/models/outbound.py	Adds CallOptions, SDK-signature validation, AMD invariants, and serialization behavior.
src/tac/models/init.py	Re-exports CallOptions and call-event models at package level.
src/tac/core/config.py	Adds voice_call_event_path, call_event_path/url, and CALL_EVENT_KINDS.
src/tac/channels/voice/config.py	Adds default_call_options and handler type aliases for call events.
src/tac/channels/voice/channel.py	Implements handler registration, event dispatch, auto-wiring, TwiML redaction logging, end_call, and session lookup by CallSid.
src/tac/channels/voice/init.py	Exposes call-event types/handlers and CallOptions from the voice channel package.
getting_started/README.md	Documents the new voice_call_events.py example.
getting_started/examples/features/voice_call_events.py	Adds an end-to-end example demonstrating status/AMD/recording handlers + voicemail hangup.
CLAUDE.md	Updates architecture notes to include call-event routing/scaling implications.

---

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