Overview

The Public Broadcast API lets your server send approved WhatsApp templates at scale and send supported free-form messages. This guide covers the organization-scoped v2 endpoints.

Base configuration

Setting	Value
Base URL	`https://cerberus.eazybe.com/prod/api/v2`
Base path	`/broadcast/public`
Authentication	`x-api-key` header
Request format	`application/json`

Keep your API key on your server. It grants send access to the WhatsApp numbers connected to your organization, so do not expose it in browser or mobile code.

Authenticate your requests

You can find the organization auth key in Workspace → Staff. Add it to the x-api-key header on every endpoint except the health check.

x-api-key: YOUR_API_KEY

The key identifies your organization. When a request includes fromPhoneNumber or phone_number, the API also verifies that the number belongs to that organization and has a complete WABA configuration.

A complete WABA configuration contains waba_id, phone_number_id, phone_number, and access_token. An organization mismatch or incomplete configuration returns 401.

Integration flow

Get phone numbers to find the senders available to your organization.
Get templates and confirm that the template you need is approved.
Send a template broadcast, or send a free-form message.
If a template broadcast contains more than 1,000 recipients, use the returned jobId to get its status.
Use the health check when you need to confirm that the service is reachable.

Endpoint index

Method	Endpoint	Purpose	Authentication
`GET`	`/broadcast/public/phone-numbers`	List your organization’s WABA numbers	Required
`GET`	`/broadcast/public/templates`	List approved templates for a number	Required
`POST`	`/broadcast/public/send-template-broadcast`	Send a template to up to 10,000 recipients	Required
`POST`	`/broadcast/public/send-freeform`	Send one supported free-form message	Required
`GET`	`/broadcast/public/status/:jobId`	Check a large broadcast job	Required
`GET`	`/broadcast/public/health`	Check service availability	None

Validation rules

Validation happens before a message or broadcast is queued. If one recipient or field is invalid, correct the request and submit it again.

Input	Rule
Sender and recipient numbers	Digits only; do not include `+`, spaces, or punctuation
Template recipients	Between 1 and 10,000 recipients
Duplicate template recipients	Duplicate recipient numbers cause the entire request to fail
Template	Must exist for the sender and have `APPROVED` status
Template parameters	Must match the numbered placeholders in the selected template
Text message	`text` must not be empty
Media URL	Must use `http` or `https` and end with a supported file extension
Location	Latitude must be from `-90` to `90`; longitude from `-180` to `180`
Interactive message	`interactive.type` must be `button` or `list`
Reply buttons	Between 1 and 3 buttons
List rows	Between 1 and 10 rows across all sections

For media, the API reads the extension from the URL path and ignores query parameters. A URL without a path extension is rejected even when it returns a supported media type.

Rate limits

Rate-limit windows are fixed at 60 seconds.

Operation	Limit	Scope
Send template broadcast	10 requests per minute	API key + `fromPhoneNumber`
Send free-form message	20 requests per minute	API key + `fromPhoneNumber`
Get templates	20 requests per minute	API key + `phone_number`
Get phone numbers	30 requests per minute	API key
Get broadcast status	30 requests per minute	API key

When you receive 429, wait for the number of seconds stated in the error message before retrying. Sending more requests during the same window does not reset it.

Error handling

Errors use the same response envelope across the v2 endpoints:

{
  "status": false,
  "status_code": 400,
  "message": "Request validation failed",
  "data": {
    "error": {
      "message": "Correct the invalid request field and try again."
    }
  }
}

Status	Meaning	What to do
`200`	Request succeeded or a broadcast was queued	Read the returned `data`
`202`	A large broadcast was accepted	Save `jobId` and poll the status endpoint
`400`	A field, recipient, template, or request limit is invalid	Correct the request; do not retry unchanged
`401`	The key, organization resource, or job ownership check failed	Check the key and use resources from the same organization
`404`	The requested broadcast job was not found	Check `jobId`
`409`	The same idempotency key is already being processed	Wait for the existing request rather than sending a duplicate
`429`	The rate limit was exceeded	Wait for the stated interval
`500`	The service or a downstream dependency failed	Retry with exponential backoff and the same idempotency key
`503`	Authentication storage timed out	Retry with exponential backoff

Common 401 messages distinguish the configuration problem:

API key is required
Invalid API key. Organization not found.
No WABA account found for this organization.
WABA account is incomplete. Missing fields: …

Safe retries

For template broadcasts, send a unique Idempotency-Key header and reuse that value when retrying the same request. This prevents a transient failure from creating a second broadcast.

Retry 500 and 503 with exponential backoff.
For 429, wait for the interval in the response.
Do not retry 400 or 401 without changing the request or configuration.

This section documents the organization-scoped v2 integration only. Older per-number endpoints are intentionally excluded from the supported integration guide.

WABA API Documentation

Webhook

Overview

Base configuration

Authenticate your requests

Integration flow

Endpoint index

Validation rules

Rate limits

Error handling

Safe retries

​Base configuration

​Authenticate your requests

​Integration flow

​Endpoint index

​Validation rules

​Rate limits

​Error handling

​Safe retries

Base configuration

Authenticate your requests

Integration flow

Endpoint index

Validation rules

Rate limits

Error handling

Safe retries