WhatsApp notifications with PDP 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, registers the service provider, and adds these environment variables:

COMMERCE_WHATSAPP_ACCESS_TOKEN=
COMMERCE_WHATSAPP_PHONE_NUMBER_ID=
COMMERCE_WHATSAPP_API_VERSION=vN.N

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.

Record narrowly scoped consent

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.

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

• Follow the PDP operations runbook for rights, retention, legal holds, and incidents.
• Review the broader Indonesia capability map.
• Configure durable work in deployment and operations.
• Use troubleshooting for queue, provider, and webhook failures.