Skip to main content

​
Integration and operations

  • Validate that the WhatsApp number is connected before testing sends.
  • For any non-2xx response, record the statusCode and response body — it makes debugging much easier.
  • For 429 and 5xx errors, retry with exponential backoff and jitter.
  • Use webhooks to observe the full lifecycle (sent/delivered/read/failed) in real time instead of polling.

​
Security

  • Keep the API key on the backend only — never ship it to a browser or mobile app.
  • Avoid logging sensitive data (the full key, or message content if your policy requires).

​
Quick FAQ

​
Got 403 with code TENANT_SCOPE_NOT_ALLOWED

You used a tenant-scoped key on a per-number endpoint (e.g. POST /v1/messages/send). Use the number-scoped key from the API Keys page (/api-keys) instead.

​
Got 403 with code NUMBER_SCOPE_NOT_ALLOWED

You used a number-scoped key on a tenant-only endpoint (e.g. /v1/numbers/*, /v1/branding). Use the tenant-scoped key from Profile → API.

​
READ status / message.read never arrives

The read event only fires when the recipient has WhatsApp read receipts enabled (Settings → Privacy). Otherwise the lifecycle stops at DELIVERED — this is a WhatsApp behavior, not a delivery failure.