Skip to content

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.

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-message
  • channel-whatsapp:write:record-status
SecretScopeHint
channel-whatsapp:secret:access-tokentenantSystem-user access token of the Meta app. Used to send messages and to download media.
channel-whatsapp:secret:app-secrettenantApp secret of the Meta app. Verifies the signature of every incoming webhook.
channel-whatsapp:secret:verify-tokentenantAny string you also enter in the Meta webhook settings; answers Meta’s subscription handshake.
  • Registers extension: tenantData → whatsapp-retention-cursor