Packages · SMS

`@notifkit/provider-twilio`

The Twilio SMS transport. Sends through the Twilio Messages API and verifies status callbacks with X-Twilio-Signature, feeding delivery receipts, hard bounces and STOP replies into notifkit's delivery log and suppression list.

npm install @notifkit/provider-twilio

import { NotifkitServer } from "notifkit";
import { TwilioTransport } from "@notifkit/provider-twilio";

const server = new NotifkitServer({
  services: ["all"],
  providers: [
    new TwilioTransport({
      accountSid: process.env.TWILIO_ACCOUNT_SID!,
      authToken: process.env.TWILIO_AUTH_TOKEN!,
      from: "+15550000001",
      statusCallbackUrl: "https://api.example.com/webhooks/twilio",
    }),
  ],
});

Options

Option	Required	Notes
`accountSid`	yes	Your Twilio Account SID.
`authToken`	yes	Your Twilio Auth Token. Used for API authentication and webhook validation.
`from`	yes	Default sender phone number in E.164 format (e.g. `+15550000001`). A template can override this.
`statusCallbackUrl`	no	The public URL where Twilio sends message status updates. Required for webhook signature verification.
`logger`	no	A notifkit logger instance.
`limits`	no	Provider sliding-window rate limit. Defaults to `{ limit: 1000, windowSeconds: 10 }`.

Which template keys it reads

Template key	Lands as
`text` or `body`	The SMS body text message.
`from`	Overrides the constructor's sender phone number for this template. Useful for short codes vs long codes.

Status callbacks & suppressions

With statusCallbackUrl configured, the transport sets webhookPath = "/webhooks/twilio". Twilio signs the URL and POST body with HMAC-SHA1 using your Auth Token, in the X-Twilio-Signature header.

Twilio Callback Event	Becomes	Effect
`delivered`	`delivered`	Marks message delivered in delivery log.
`undelivered` / `failed` (Hard bounce)	`bounced`	Suppresses destination if code indicates invalid number or unreachable carrier (codes 21211, 21612, 21614, 30005, 30006).
`failed` (Error 21610: STOP reply)	`unsubscribed`	Automatically suppresses recipient from future SMS notifications.

Exact URL match required

Twilio signs against the exact URL in statusCallbackUrl. If your reverse proxy or load balancer strips trailing slashes or rewrites headers, verification fails and webhooks are rejected.