Call lifecycle
What happens between a caller dialling and an order appearing on the POS.
Worth understanding before you integrate: most of the interesting state is created by the voice runtime calling into the API mid-conversation, not by anything you initiate.
Sequence
Caller Twilio Platform API Voice runtime Clover
│ │ │ │ │
│──dials─────►│ │ │ │
│ │──inbound webhook─►│ │ │
│ │ │ resolve restaurant by number │
│ │ │ blocked caller? → reject │
│ │ │ active plan? → reject if not │
│ │◄──redirect────────│ │ │
│ │──────────── start run ───────────────────►│ │
│ │ │◄── fetch call context ─ │
│ │ │ open/closed, menu, caller history │
│◄══════════════════ live audio ══════════════════════════│ │
│ │ │◄── menu search ──────── │
│ │ │◄── create order ─────── │
│ │ │ upsert customer ────────────────────────►│
│ │ │ create order ───────────────────────────►│
│ │◄─confirmation SMS─│ │ │
│ │ │ push notification to staff │
│──hangs up──►│ │ │ │
│ │ │◄── transcript + QA ──── │Before the agent speaks
Three checks run on the inbound webhook, and any of them can end the call:
- Restaurant resolution — the dialled number is matched to a restaurant.
- Blocked caller — the caller's number is compared, digits-only, against the restaurant's block list. A match is rejected.
- Subscription — the restaurant needs an
activeortrialingsubscription. Without one, the call is rejected.
Only then does the runtime start.
The context fetch
The runtime asks the API for everything the agent needs to open the conversation:
- Restaurant name, address and hours
- Whether it is currently open or closed — decided server-side, before the first word
- Categories and best-selling items
- The caller's history, if the number is a known customer
That open/closed flag is what selects order mode or inquiry mode.
Opening hours are evaluated in America/Toronto. There is no per-restaurant timezone field today, so restaurants outside Eastern Time must express their hours in Eastern Time.
During the call
The agent calls back into the API as the conversation goes:
| Purpose | Endpoint |
|---|---|
| Search the menu | /api/menu-items/search |
| Item detail | /api/menu-items/detail |
| Place the order | /api/create-order |
Order placement upserts the customer, writes the order, pushes it to Clover, sends the confirmation SMS and fires a web push to staff devices.
After the call
The runtime posts back the transcript and run details. The platform stores the recording, transcript, AI summary, sentiment, quality score and tags against the call. Twilio's recording callback arrives separately and the audio is moved to CDN storage.
This is why call records are not complete the instant a call ends — the transcript and the recording land on two different callbacks.
Webhooks the platform receives
| Source | What for |
|---|---|
| Twilio | Inbound calls and recording status |
| Stripe | Subscription lifecycle, per business and per platform |
The platform sends no outbound webhooks. If you need to know when an order arrives,
poll /api/orders.