Webhooks, TwiML and the anatomy of an AI call
Agentric Team ·
For those who like knowing how the sausage is made: here's the actual lifecycle of a call to your Agentric number, webhook by webhook.
The call lifecycle
**1. Inbound call → POST /api/voice/inbound.** Your customer dials. The telephony provider (Twilio-compatible) hits our webhook with the caller's number, the called number, and a call ID. We identify the tenant from the number, load the agent config, and return TwiML: greet with the AI disclosure, record-notice, then open the conversation loop (speech gather or media stream depending on provider).
**2. Utterance → POST /api/voice/respond.** Each time the caller speaks, the provider transcribes (or streams audio) and posts back. Our runtime loads the conversation state, runs the agent loop (with knowledge, memory, tools), and returns the next TwiML: play the response, keep listening, or act (transfer, hangup, record).
3. Tool calls mid-call. When the agent needs to check availability or book, the runtime executes the tool server-side, and the result feeds back into the response — all inside the same turn, so the caller hears "let me check… we have Thursday at 10."
**4. Call end → POST /api/voice/status.** The provider reports completion. We finalise the call record, write the summary, notify you.
**5. Recording → POST /api/voice/recording.** If recording is on, the audio callback stores the recording reference alongside the transcript.
The failure design
- Provider can't reach us → telephony retry + voicemail fallback instructions.
- Agent errors mid-call → graceful "let me take a message" fallback, not a dropped call.
- Every step logged — the call lifecycle is auditable end-to-end.
Why this matters
Understanding the seams is how you trust it: the call is a series of well-defined exchanges, each with a fallback. There's no magic — just a pipeline where every failure mode has a designed behaviour.