Packages · Chat

`@notifkit/provider-whatsapp`

The WhatsApp transport. Sends to phone numbers through Meta's WhatsApp Cloud API with zero per-message markup, plus the 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

It targets the recipient's E.164 phone number, the same phone contact SMS uses.

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 allows free-form text within 24 hours of the recipient's last incoming message. Outside that window, business-initiated messages must use pre-approved templates.

Webhooks

Mounted automatically at /webhooks/whatsapp. Point your Meta App Webhook subscription at 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 with appSecret and logs delivery status updates.