Send a free-form WhatsApp text message
POST/v1/whatsapp/messages
Free-form text is restricted to Meta's 24-hour customer-service window
(the customer must have messaged the agent within the last 24 hours).
Outside the window, use POST /v1/whatsapp/templates instead.
Request
Responses
- 202
- 401
- 403
- 409
- 422
- 429
- 500
Accepted for asynchronous processing. The message is queued; final
delivery happens via the WhatsApp Business Cloud API. Poll
GET /v1/whatsapp/messages/{id} to track status.
Response Headers
Correlation id for this request — paste into support tickets.
Present and true when the response is a replay of a prior request.
Authentication failed. Single code (invalid_api_key) covers every
sub-case: missing header, wrong scheme, malformed/unknown/revoked
key. The message field disambiguates for humans debugging.
Response Headers
Correlation id for this request — paste into support tickets.
Authenticated, but not authorized. insufficient_scope (key lacks
the required scope) or agent_not_authorized (key is restricted to
specific agents and this one isn't allowlisted).
Response Headers
Correlation id for this request — paste into support tickets.
A request with this Idempotency-Key is currently being processed.
Wait Retry-After seconds and try again with the same key + body.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
Request body or fields failed validation. code identifies the
specific failure; param (when present) names the offending field.
Response Headers
Correlation id for this request — paste into support tickets.
Per-key rate limit hit. Default is 60/min/key. Retry-After tells
you when to retry; X-RateLimit-Reset is the Unix timestamp of the
next window.
Per-success-response
X-RateLimit-*headers are a known gap; on 2xx responses these headers are NOT currently emitted. Customers should rely on 429 +Retry-Afterfor backoff signals.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
The configured per-minute limit on this API key.
Remaining requests in the current window. 0 on rejection.
Unix timestamp at which the current window resets.
Unexpected server-side failure. Retry with exponential backoff. If
the failure persists, send us the correlation_id.
Response Headers
Correlation id for this request — paste into support tickets.