One contract for
SMS, WhatsApp, and OTP.

01 / Authentication

A token carries permissions, not just an identity.

Send the token in the Authorization header. Permissions are checked per endpoint, so a token with only sms:read cannot create a batch. Create one token per integration so you can revoke it without touching the others.

Authorization: Bearer notif.<64 hex characters>Content-Type: application/jsonAccept: application/jsonIdempotency-Key: <unique per write operation>

# Create a token on the API Tokens page in the dashboard.# Every token has its own permission list:# sms:create, sms:read, rcs:create, rcs:read,# mms:create, mms:read,# whatsapp:create, whatsapp:read,# otp-sms:create, otp-sms:verify, otp-sms:read,# otp-whatsapp:create, otp-whatsapp:verify, otp-whatsapp:read# Never put a token in browser code or a client bundle.

02 / OTP

Send, verify, track.

SMS and WhatsApp use the same request shape. Templates are capped at 255 characters and must contain {otp} or {code}. Codes stay valid for 60 to 900 seconds.

curl -s -X POST "$NOTIF_API_URL/api/v1/otp/sms/send" \  -H "Authorization: Bearer $NOTIF_TOKEN" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: login-2026-11-07-001" \  -d '{"recipient":"081234567890","ttl":300}'

curl -s -X POST "$NOTIF_API_URL/api/v1/otp/verify" \  -H "Authorization: Bearer $NOTIF_TOKEN" \  -H "Content-Type: application/json" \  -d '{"recipient":"081234567890","code":"123456","channel":"sms"}'

03 / SMS, RCS, MMS

One endpoint, three message types.

The Idempotency-Key header is required when creating a batch. Set type to SMS, RCS, or MMS. RCS allows media, MMS requires it. Each request takes 1 to 1,000 recipients, and they must be unique.

04 / WhatsApp

One recipient per request.

The WhatsApp endpoint creates a batch with a single recipient. For large lists, use a blast session in the dashboard. Media is sent as an HTTPS URL, not base64.

05 / Virtual Numbers

Order statuses you need to know.

Virtual numbers are managed from the notif. panel, not from the public SMS or WhatsApp endpoints. Order status and OTP codes appear in the dashboard, and the code can be forwarded to a WhatsApp device through the integration.

06 / Webhooks

Verify the signature before you trust the payload.

Batch webhooks send sms.batch.updated and whatsapp.batch.updated events to a public HTTPS URL on port 443. Every request carries X-Webhook-Id, X-Webhook-Timestamp, and X-Webhook-Signature in the format sha256=HMAC(timestamp.body, secret).

{  "id": "9a51d6de-7f0c-4c1b-9f8a-2f7b5a6d8c31",  "event": "sms.batch.updated",  "created_at": "2026-11-07T09:30:00+00:00",  "data": {    "id": "01JBCDEFGHJKMNPQRSTVWXYZ",    "status": "running",    "lifecycle_status": "running"  }}

import { createHmac, timingSafeEqual } from "node:crypto";const timestamp = request.headers["x-webhook-timestamp"];const signature = request.headers["x-webhook-signature"];const expected =  "sha256=" +  createHmac("sha256", process.env.NOTIF_WEBHOOK_SECRET)    .update(`${timestamp}.${rawBody}`)    .digest("hex");const valid = timingSafeEqual(  Buffer.from(expected),  Buffer.from(String(signature)),);

Verify signatures against the raw body, not the parsed JSON. Reject requests with an old timestamp, and do not follow redirects.

07 / Limits

The numbers that define the API contract.

08 / Error codes

Decide what to do from the error code, not the message.

Error messages can change. Error codes are a stable enum, and they are what you should branch on.

The full list, including channel-specific codes, is in the app documentation.