# QAF WhatsApp API

> QAF is a multi-tenant gateway for the WhatsApp Cloud API. Integrators send text, template, media, quick-reply, list, location and bulk template messages, manage contacts and the 24h customer-service window, and receive HMAC-signed webhooks for inbound messages, delivery status and calls. Base URL https://api.qaf-sender.qafdev.com, path prefix /v1, Bearer account token. Last updated: 2026-11-03.

Rules to apply when writing code against this API:

- Base URL is https://api.qaf-sender.qafdev.com; every path starts with /v1/whatsapp. Never use the unversioned /whatsapp alias.
- Authenticate with `Authorization: Bearer <account API token>`. Read secrets from environment variables; never commit them.
- Send `Idempotency-Key: <uuid>` on every POST /v1/whatsapp/messages/* request.
- Phone numbers are E.164 (`+966501234567`). `phoneNumber` is the business sender line, `recipientPhoneNumber` is the customer.
- Templates: use the local template `id` from GET /v1/whatsapp/templates together with `languageCode`.
- Sends return 202 with `status: "queued"`, not delivered. Track delivery with status webhooks or by polling the returned `uri`.
- Free-form text, media, quick-reply, location and list sends need an open 24h customer-service window (contact `freeformAllowed`, fetched with `phoneNumberId`); otherwise send an approved template.
- Webhooks: verify `X-QafLab-Signature` (HMAC-SHA256 of the raw body with `webhookSecret`, constant-time compare) before trusting a payload, then respond 2xx quickly. Deduplicate retries on `X-QafLab-Delivery-Id`.
- Treat 429 as retryable: wait `retryAfterSeconds` when present, otherwise back off. 409 = idempotent request still in flight; 422 = idempotency key reused with a different body, template not APPROVED, or 24h window closed.

## Docs

- [Developer guide (Markdown)](https://qaf-sender.qafdev.com/developers.md): Authentication, quick start, concepts, message resource, full endpoint reference, interactive and bulk template sends, the 24h window, webhooks and signature verification, idempotency, errors and rate limits, code samples, go-live checklist.
- [Developer guide (HTML)](https://qaf-sender.qafdev.com/developers): Same content rendered for people.
- [Everything in one file](https://qaf-sender.qafdev.com/llms-full.txt): This index followed by the complete guide.

## Optional

- [Privacy policy](https://qaf-sender.qafdev.com/privacy)
- [Data deletion](https://qaf-sender.qafdev.com/data-deletion)