channel-whatsapp
WhatsApp Business (Meta Cloud API) as a two-way channel, not a delivery channel. Inbound: mount createWhatsappWebhookRoutes() via extraRoutes (default path /api/channel-whatsapp/webhook/:tenantId, the tenant id is part of the URL because the secrets are tenant-scoped); GET answers Meta’s hub.challenge handshake, POST checks X-Hub-Signature-256 over the raw body and normalizes each message and status. Events: channel-whatsapp:event:message-received (sender, wamid, type text|audio|image|interactive_button|other, text, button payload, contextWamid, media id and mime type, phoneNumberId), status-updated (sent|delivered|read|failed|other) and throttled (sender over the per-number limit). Sender number, text, button payload and status recipient are PII, stored as ciphertext under a record key per stream; with eventRetentionDays set the maintenance job whatsapp-event-retention erases those keys after that many days (no job without it), and tenant destroy erases all of them, so a consuming job reads them with readWhatsappMessagePii (and readWhatsappStatusPii, readWhatsappThrottledPii) and copies what it keeps into its own entities. A redelivered wamid is stored once and answered 200; a failed dispatch answers 500 so Meta redelivers. Outbound: createWhatsappClient(opts) gives sendText, sendTemplate, sendButtons, sendMedia (each takes the sending phoneNumberId and answers { ok: true, wamid } or a typed failure) and fetchMedia (media id to bytes and mime type; the URL from the Graph answer is checked against allowedHosts before the token is sent). Tenant secrets channel-whatsapp:secret:access-token, app-secret and verify-token. App options of createChannelWhatsappFeature(opts): apiBaseUrl, apiVersion (default v21.0), allowedHosts (default graph.facebook.com and lookaside.fbsbx.com), requireHttps (default true; boot fails on a mismatch), timeoutMs, mediaMaxBytes, transport (in-memory Meta for tests), senderRateLimits (default 30 per hour and 200 per day per sender and tenant) and rateLimit (flood guard of the inbound handlers; cannot be disabled while a sender limit is set). Requires secrets and tenant-lifecycle. A worker-run job triggered by message-received attaches the business process.
How it fits
Section titled “How it fits”What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).
flowchart TB
n_channel_whatsapp["channel-whatsapp"]
subgraph how_reqs["Requires"]
n_secrets["secrets"]
n_tenant_lifecycle["tenant-lifecycle"]
end
subgraph how_provides["Provides"]
n_cmd_channel_whatsapp_write_receive_message(["receive-message"])
n_cmd_channel_whatsapp_write_record_status(["record-status"])
end
n_secrets --> n_channel_whatsapp
n_tenant_lifecycle --> n_channel_whatsapp
n_channel_whatsapp --> n_cmd_channel_whatsapp_write_receive_message
n_channel_whatsapp --> n_cmd_channel_whatsapp_write_record_status
Provides — write commands this feature registers (dispatch them through the command bus):
channel-whatsapp:write:receive-messagechannel-whatsapp:write:record-status
Dependencies
Section titled “Dependencies”- Requires:
secrets,tenant-lifecycle - Activation: always on (not toggleable)
Secrets
Section titled “Secrets”| Secret | Scope | Hint |
|---|---|---|
channel-whatsapp:secret:access-token | tenant | System-user access token of the Meta app. Used to send messages and to download media. |
channel-whatsapp:secret:app-secret | tenant | App secret of the Meta app. Verifies the signature of every incoming webhook. |
channel-whatsapp:secret:verify-token | tenant | Any string you also enter in the Meta webhook settings; answers Meta’s subscription handshake. |
Extensions & cross-feature APIs
Section titled “Extensions & cross-feature APIs”- Registers extension:
tenantData→whatsapp-retention-cursor