Send a Meta-approved WhatsApp template
POST/v1/whatsapp/templates
x-scope: "whatsapp:send"
Templates can be sent at any time, including outside the 24-hour
customer-service window. The template must be pre-approved by Meta
for the agent's WhatsApp Business Account; listWhatsAppTemplates
shows each template's status and what to fill in. Before queuing,
Mojeeb checks the name and language against the number's templates
(422 template_not_found or template_not_found_for_language). That
check accepts a template whatever its status, so one that isn't
approved fails at Meta instead. The check is skipped when Mojeeb can't
read the templates from Meta, and when the number has more than 100
templates and the name or language isn't among the 100 Mojeeb reads:
the send is then accepted (202) and Meta's verdict shows in its
status.
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),
template_not_found and template_not_found_for_language (the template name or language
isn't among the number's templates; see sendWhatsAppTemplate),
template_header_media_url_invalid (a header media URL that isn't a public https link) 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.