Send a free-form WhatsApp text message
POST/v1/whatsapp/messages
x-scope: "whatsapp:send"
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
- 402
- 403
- 404
- 409
- 413
- 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 or
expired key. The message field disambiguates for humans debugging.
One exception: when the key could not be checked because of a server-side
fault, the status is still 401 but type is internal_error and code
is internal_server_error; retry with backoff.
Response Headers
Correlation id for this request — paste into support tickets.
Reserved. The organization's monthly message quota is exhausted. Quota
enforcement for API sends is switched off today, so this response does
not occur yet; it is documented so clients handle it once enforcement is
enabled. limit, used and resets_at carry the numbers.
Response Headers
Correlation id for this request — paste into support tickets.
insufficient_scope (the key lacks whatsapp:send), agent_not_authorized (the key is
limited to agents other than agent_id), or agent_id_required (the key is limited to some
agents and Mojeeb couldn't read an agent id from the body's agent_id).
Response Headers
Correlation id for this request — paste into support tickets.
agent_not_found when agent_id is not one of your company's agents (the API never
confirms whether another company's agent exists).
Response Headers
Correlation id for this request — paste into support tickets.
A request with this Idempotency-Key is still running, or one with it
that was refused or failed after claiming the key (for example a
422 messaging_window_closed on sendConversationMessage) started less
than 60 seconds ago (whatever the body). Wait Retry-After seconds and
retry, or send a corrected request with a new key.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
The request body is larger than 1 MB.
Response Headers
Correlation id for this request — paste into support tickets.
invalid_request_body when the body isn't valid JSON, a field has the wrong type or
format, or a field breaks a limit in its schema; param names the field.
invalid_agent_id (agent_id isn't a UUID), invalid_from_phone (from isn't
E.164), invalid_phone_number (to isn't E.164), from_phone_not_found_for_agent
(from isn't one of the agent's active WhatsApp numbers; available_phones lists
them) and idempotency_key_in_use_with_different_params (an Idempotency-Key reused
with another body or on another endpoint).
Response Headers
Correlation id for this request — paste into support tickets.
Per-key rate limit hit. Default is 60/min/key; an endpoint with an
x-rate-limit-per-minute of its own counts in a budget of its own
(today listWhatsAppTemplates, which allows 10/min/key, and
sendConversationMessage, which allows 20/min/key), and its 429
reports that limit in X-RateLimit-Limit. 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 per-minute request limit of the endpoint called. Every key has the same limits today.
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.