Send a broadcast
POST/v1/agents/:agentId/broadcasts
x-scope: "broadcasts:write"
x-rate-limit-per-minute: 10
Sends one approved template from one of the agent's WhatsApp numbers to many numbers, right
away, as the dashboard's Broadcasts page does. The answer is 201 with the broadcast,
sending; Mojeeb sends in the background, and each message's delivery comes back on
listBroadcastRecipients. Each recipient lands in their conversation with the agent (one
is started if they have none), so a reply reaches the AI.
A broadcast fills only the template's body variables: parameters for everyone, and a
recipient's own parameters over them. Its header keeps the sample it was approved with,
and no button gets a value, so a template with a header variable or a button that needs a
value per send is 422 template_not_broadcastable (send those one by one with
sendWhatsAppTemplate), and so is one with a location header, which Mojeeb can't send
yet. A template the number doesn't have is 422 template_not_found with
available_templates, or template_not_found_for_language with available_languages.
Only an approved template can be broadcast
(422 template_not_approved). A number listed twice gets one message; recipient_count
says how many will be sent. Mojeeb refuses a broadcast with more recipients than the
number's WhatsApp daily messaging limit allows (422 invalid_request).
Send an Idempotency-Key: a retry after a timeout then never sends the broadcast twice.
It checks the template with Meta, so it shares the WhatsApp template endpoints' budget of
10 requests a minute per key. Plans with broadcasts only.
Request
Responses
- 201
- 401
- 403
- 404
- 409
- 413
- 422
- 429
- 500
- 503
The broadcast, sending (a replay of it when Idempotent-Replayed is true).
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.
Authenticated, but not allowed. insufficient_scope (the key lacks
broadcasts:read or broadcasts:write), agent_not_authorized (the key
is limited to other agents) or feature_not_available (broadcasts aren't
on your company's plan).
Response Headers
Correlation id for this request — paste into support tickets.
not_found when the broadcast isn't the agent's, or (sending) the
connection_id isn't one of the agent's WhatsApp numbers;
agent_not_found when the agent is not one of your company's agents.
Response Headers
Correlation id for this request — paste into support tickets.
Nothing was sent. idempotency_key_in_progress: a request with this
Idempotency-Key is still running (wait Retry-After). connection_inactive
or connection_needs_reconnection: the WhatsApp number must be reconnected in
the dashboard before its templates can be checked. broadcast_still_sending
(retryBroadcast): the broadcast hasn't finished; retry when it has.
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.
Nothing was sent. invalid_request_body when the body breaks its schema
(param names the field, such as recipients[3].phone).
template_not_found when the number has no template with that name
(available_templates lists its names), template_not_found_for_language
when it has none in that language (available_languages lists its languages);
a number with more templates than the 100 Mojeeb reads answers
template_not_found without the list when the template isn't among them.
template_not_approved when it isn't approved; template_not_broadcastable
when its header has a variable or a location, or a button needs a value per send. invalid_request when a recipient lacks a body value
(param: recipients[1].parameters), or the audience is larger than the
number's WhatsApp daily messaging limit.
idempotency_key_in_use_with_different_params when the Idempotency-Key
was used for another request.
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 the WhatsApp template endpoints and sendBroadcast, which share one
that 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.
A temporary fault; nothing was changed, so retry with backoff. One exception: a template
create, edit or delete that Meta didn't answer in time may still have been made, so read the
template before trying again.
meta_unavailable: Meta didn't return what was asked (an outage, a
timeout or Meta's own rate limit). access_unavailable: Mojeeb
couldn't check this key's access.
Response Headers
Correlation id for this request — paste into support tickets.