Skip to content

WhatsApp notifications with PDP consent

Send Indonesian commerce updates through approved WhatsApp Cloud templates while enforcing purpose- and notice-specific consent.

@adocommercekit/whatsapp connects order, payment, and shipment events to WhatsApp Business Cloud templates. Delivery is intentionally coupled to @adocommercekit/id consent receipts: current consent is checked before a job is enqueued and again before it is sent.

Install and configure

pnpm add @adocommercekit/id @adocommercekit/whatsapp
node ace configure @adocommercekit/id
node ace configure @adocommercekit/whatsapp
node ace migration:run

The WhatsApp configure hook publishes config/commerce_whatsapp.ts, the webhook controller/routes, and a send-log migration, registers the service provider, and adds these environment variables:

COMMERCE_WHATSAPP_ACCESS_TOKEN=
COMMERCE_WHATSAPP_PHONE_NUMBER_ID=
COMMERCE_WHATSAPP_API_VERSION=vN.N
COMMERCE_WHATSAPP_APP_SECRET=
COMMERCE_WHATSAPP_VERIFY_TOKEN=

Configuration is disabled by default. Before enabling it:

  1. Pin the Graph API version used by the merchant’s approved integration.
  2. Replace the example noticeVersion with the exact privacy notice shown to customers.
  3. Map each supported commerce event to an approved WhatsApp template and locale.
  4. Configure a durable queue through the core jobs port.
  5. Add a host fallback only when its channel, purpose, and data-processing basis are independently valid.

Set appSecret from COMMERCE_WHATSAPP_APP_SECRET (Meta app secret) and verifyToken from COMMERCE_WHATSAPP_VERIFY_TOKEN (your handshake token). These are distinct from the access token. Run the published migrations before sending or receiving status callbacks.

Configure Meta webhooks

Register the HTTPS callback URL <APP_URL>/commerce/webhooks/whatsapp in Meta and the same verify token as host configuration. The published GET route verifies hub.mode=subscribe and the token before returning hub.challenge; the POST route ingests messages/statuses only when configuration is enabled.

POST authentication uses x-hub-signature-256: sha256=...: HMAC-SHA256 over the exact raw body bytes, keyed by appSecret, with constant-time comparison. Preserve raw body availability through the host body-parser/proxy path. Never authenticate parsed/re-serialized JSON or use the GET verify token as the POST HMAC secret.

Keep this server-to-server POST route outside Shield’s browser CSRF enforcement. Configure attempts to add /commerce/webhooks/whatsapp to a standard exceptRoutes array, but custom Shield configurations may require manual exclusion (configure warns when it cannot update the array). Inspect the result and exempt only the exact webhook route, not unrelated browser routes.

loadWhatsAppUpgradeArtifacts() and whatsappUpgradeManifest from @adocommercekit/whatsapp/upgrade identify reviewable config/controller/route publications for commerce:upgrade. Package repository metadata points to the upstream monorepo with directory packages/whatsapp; use the matching release for incident/source review.

Use the package purpose order_updates_whatsapp. Present the channel, purpose, notice version, processor, withdrawal path, and material data use before recording an affirmative action.

A notice update does not inherit an old grant. Record a new receipt when the host’s reviewed policy requires fresh consent. Withdrawal appends a new receipt; it does not rewrite historical evidence.

const hasConsent = await consentReceipts.hasValidPurpose(
  customerId,
  "order_updates_whatsapp",
  noticeVersion,
)

Do not use marketing consent as a substitute for transactional notification consent, or transactional consent as permission for marketing.

Resolve approved templates

The host provides the template resolver because Meta approval, language, parameter order, and merchant wording live outside the package. Resolve only approved templates for the selected event and locale.

Keep template variables minimal. Prefer order number, a short state label, and an authenticated or signed host URL over full addresses, item detail, payment instructions, or sensitive provider data.

If a template is unapproved or retries are exhausted, the package invokes only the host-configured fallback. It does not silently send free-form content or choose another channel.

Delivery lifecycle

  1. A supported order, payment, or shipment event reaches WhatsAppNotificationService.
  2. The service verifies current purpose and notice consent.
  3. A minimized job is dispatched through the configured jobs port.
  4. The worker rechecks consent immediately before send.
  5. WhatsAppCloudClient sends the resolved approved template.
  6. Logs retain useful identifiers and outcomes without raw recipients, tokens, or full provider payloads.

This second consent check is load-bearing: a customer can withdraw after an event is enqueued but before a delayed worker runs.

Persisted attempts, statuses, and retries

The registered provider supplies a database-backed WhatsAppSendLogService automatically. Direct WhatsAppNotificationService callers must provide options.sendLog; it is not an optional logger. Each (reference, event, attempt) persists queued/sent/failed state, the Meta message ID, and classified error code without storing recipients or template variables in the send log.

Verified status callbacks correlate the Meta ID to that attempt and update sent, delivered, read, or failed while preventing stale timestamps/state regressions. A status received before the send response is persisted remains a failed/replayable inbox receipt; replay it after message-ID correlation is available instead of acknowledging and losing it.

Permanent authentication, permission, invalid-recipient, and template errors are not retried (including provider codes 190, 10, 100, 200, 131026, 131030, 131047, 131049, 132000, 132001, 132005, 132007, 132012, 132015, and 132016). Transient transport, rate-limit, and server failures can retry up to maxAttempts (default 3, bounded to 1–10). Delays are milliseconds, exponentially increasing from retryDelayMs (default 1000) and capped at 3600000. Permanent failures and exhaustion invoke only the configured fallback.

A persistence error after Meta accepts a send is not classified as a retryable provider failure. Reconcile the accepted message before retrying work; do not immediately send a duplicate because the database write failed.

Production checks

  • Verify grant, withdrawal, changed notice version, missing recipient, and unapproved-template behavior.
  • Exercise retry exhaustion and the configured fallback without exposing personal data.
  • Redact phone numbers, access tokens, template parameters, and provider response bodies from logs.
  • Keep the access token in the host secret store and rotate it through the merchant’s incident process.
  • Review processor terms, retention, international transfer, and incident obligations with Indonesian counsel.
  • Do not reuse WhatsApp delivery receipts as proof that a customer read or legally accepted a notice.

Continue

Navigation

Type to search…

↑↓ navigate↵ selectEsc close