WhatsApp Calling with ElevenLabs as the handler

2Outbound — permission first, then call

The tab's Test outbound panel drives both steps through one endpoint: POST /api/calls/trigger (auth + idempotency middleware). Numbers are normalized to E.164; the connector must exist and be enabled.

1. Settings UI→Zen API→Meta→User

   {action: "request_permission"} → Zen sends an interactive call_permission_request message via POST /{phone-number-id}/messages (“We'd like to call you on WhatsApp. Tap to allow.”). The user taps to allow.

2. Settings UI→Zen API→ElevenLabs

   {action: "call"} → Zen calls the ElevenLabs SIP trunk with the stored key + agent IDs (see below) and returns conversation_id + sip_call_id. The agent talks to the user; Meta bridges the audio.

// POST https://api.elevenlabs.io/v1/convai/sip-trunk/outbound-call
// Header: xi-api-key: <stored per-number key>
{ "agent_id": "ag_…",
  "agent_phone_number_id": "pn_…",
  "to_number": "+15551212" }
// → { "success": true, "conversation_id": "conv_1", "sip_call_id": "sip_1" }

3Inbound — user calls, agent answers

No Zen code runs in the media path. Provisioning (step 1) already told Meta where to send calls, so inbound is pure SIP between Meta and ElevenLabs.

1. User→Meta

   The user taps the call icon on the WhatsApp business number (visibility DEFAULT, set during connect).

2. Meta→ElevenLabs

   Meta sends a SIP INVITE to the configured server (hostname:port, SDES key exchange, G.711 PCMA/PCMU codecs). ElevenLabs routes it to the BYO agent, which runs the IVR conversation.

3. Meta→Zen pipeline

   In parallel, Meta emits field=calls webhooks (connect, terminate, …) so Zen still observes the call — see next section.

4Call events — every ring lands in Zen

Both directions (inbound USER_INITIATED and outbound) report lifecycle through the same pipe: Meta → ingress → queue → processor → Mongo + customer webhook.

1. Meta→webhook-ingress

   meta_cloud_handler now accepts field: "calls" (previously only "messages") and parses the calls[] array: id, from/to, event, status, direction, duration, timestamp.

2. webhook-ingress→queue

   Publishes webhook_type: "call_event" on the events routing key, deduped as meta_call_<call-id>_<event> so redeliveries collapse.

3. queue→webhook-processor→MongoDB

   A new 7th parallel lane (processCallEventWebhookBatch) upserts call_sessions keyed by call_id: latest event/status, parties, duration, started_at (or ended_at when event: "terminate"), owner + WABA + phone-number IDs.

4. webhook-ingress→Customer

   Ingress also forwards to subscribed customer webhooks under the new topic zen.upstream.call (“WhatsApp Calling lifecycle events … for inbound and outbound voice calls”), listed in the topics catalog.

// call_sessions — one row per call, upserted on every event (migration 0060:
// unique index on call_id; index on project_owner_id + created_at)
{ "call_id": "wacid.abc", "direction": "USER_INITIATED",
  "event": "connect", "status": "CONNECTED",
  "from": "15551212", "to": "PN1", "duration_seconds": 0,
  "started_at": "…", "ended_at": "… (on terminate)" }