Packages · SMS

`@notifkit/provider-twilio`

The Twilio SMS transport. Sends through the Twilio Messages API and verifies status callback webhooks with X-Twilio-Signature, feeding delivery receipts, hard bounces, and STOP replies directly 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

The transport sets webhookPath = "/webhooks/twilio" when statusCallbackUrl is configured. Twilio signs the request 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 validates signatures against the exact URL registered in statusCallbackUrl. If your reverse proxy or load balancer strips trailing slashes or rewrites headers, signature verification will fail and webhooks will be rejected.