Packages · Chat

`@notifkit/provider-whatsapp`

The WhatsApp transport. Delivers messages via Meta's WhatsApp Cloud API to recipient phone numbers with zero per-message markup, complete with GET webhook handshake and HMAC-SHA256 signature verification.

npm install @notifkit/provider-whatsapp

import { NotifkitServer } from "notifkit";
import { WhatsAppTransport } from "@notifkit/provider-whatsapp";

const server = new NotifkitServer({
  services: ["all"],
  providers: [
    new WhatsAppTransport({
      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
      accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
      verifyToken: process.env.WHATSAPP_VERIFY_TOKEN,
      appSecret: process.env.META_APP_SECRET,
    }),
  ],
});

Options

Option	Required	Notes
`phoneNumberId`	yes	Your WhatsApp Business Phone Number ID from Meta App Dashboard > WhatsApp > API Setup.
`accessToken`	yes	Meta System User access token with `whatsapp_business_messaging` permission.
`apiVersion`	no	Meta Graph API version. Defaults to `v21.0`.
`verifyToken`	no	Custom token string configured in Meta Webhook subscription. Required to answer Meta's `hub.challenge` handshake.
`appSecret`	no	Meta App Secret. Required to verify `X-Hub-Signature-256` headers on inbound webhook POSTs.
`limits`	no	Provider sliding-window rate limit. Defaults to `{ limit: 1000, windowSeconds: 10 }`.

Recipient targeting & templates

The WhatsApp transport targets the recipient's standard E.164 phone number (the same phone contact used by SMS).

await notifkit.addContact("usr_123", {
  channel: "whatsapp",
  target: "+15550000002",
});

await notifkit.syncTemplates({
  templates: [
    {
      id: "support-update",
      channel: "whatsapp",
      content: { text: "Hello {{name}}, your ticket #{{ticketId}} has been resolved." },
    },
  ],
});

24-hour customer care window

Meta permits free-form text messages within 24 hours of the recipient's last incoming message. For cold, business-initiated outreach outside this window, Meta requires pre-approved template messages.

Webhooks

Mounts automatically at /webhooks/whatsapp. Point your Meta App Webhook subscription to https://your-domain.com/webhooks/whatsapp.

GET: Answers Meta's hub.challenge verification using your configured verifyToken.
POST: Verifies the X-Hub-Signature-256 header using appSecret and logs delivery status updates.