Public Broadcast API

Overview

The Public Broadcast API gives external systems access to your organization’s WhatsApp Business numbers. Every request is scoped to one organization by the API key, and every WABA phone number you reference must belong to that organization — a key from one organization cannot send from another organization’s number. Two families of endpoints exist on /broadcast/public:

v2 endpoints authenticate with your organization auth key. These are the ones documented here.
Legacy endpoints still authenticate with the older per-number WABA key and are unchanged. See Legacy endpoints.

Base Configuration

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

Before You Start

Keep the key server-side. It grants send access to every WhatsApp number your organization owns. Store it in environment variables or a secrets manager, never in browser or mobile code, and use separate keys per environment.

Start here. Call Get phone numbers to discover which WABA numbers your key can send from, then Get templates to confirm a template is approved. Both are cheap, read-only, and confirm your key works before you send anything.

Authentication Flow

Use Auth Key in Request Headers

All broadcast endpoints require the generated Auth key in the x-api-key header, and you can find it inside the Workspace → Staff section.

x-api-key: YOUR_API_KEY

Store your API key securely. Avoid regenerating it unnecessarily.

Find your organization authentication key in the Staff section

What the key resolves to

The key identifies your organization. On endpoints that take a fromPhoneNumber or phone_number, the API additionally verifies that the number is registered to that organization and that its WABA record is complete — waba_id, phone_number_id, phone_number, and access_token must all be present. A mismatch returns 401, not 403.

Endpoint index

Method	Endpoint	Purpose	Auth
`GET`	`/broadcast/public/phone-numbers`	List WABA numbers on your organization	Required
`GET`	`/broadcast/public/templates`	List approved templates for a number	Required
`POST`	`/broadcast/public/send-template-broadcast`	Send a template to many recipients	Required
`POST`	`/broadcast/public/send-freeform`	Send one free-form message	Required
`GET`	`/broadcast/public/status/:jobId`	Poll a large broadcast job	Required
`GET`	`/broadcast/public/health`	Service status and endpoint list	None

Get phone numbers

Lists every WhatsApp Business number registered to your organization. Use the returned phone_number as fromPhoneNumber on the send endpoints.

Endpoint

GET /broadcast/public/phone-numbers

Request

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/phone-numbers" \
  -H "x-api-key: $API_KEY"

Response

200 — Phone numbers fetched successfully

{
  "status": true,
  "status_code": 200,
  "message": "Phone numbers fetched successfully",
  "data": [
    {
      "phone_number": "14844634680",
      "waba_id": "1099052972334241",
      "phone_number_id": "894234333763517"
    }
  ]
}

An empty data array means the key is valid but no WABA number is connected to the organization yet. That is a configuration state, not an error.

Get templates

Returns the approved WhatsApp templates available to one of your numbers. Call this before a broadcast — sending an unapproved or misspelled template name fails the whole request.

Endpoint

GET /broadcast/public/templates

Query parameters

Parameter	Type	Required	Description
`phone_number`	string	Required	A WABA number belonging to your organization, digits only

Request

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/templates?phone_number=14844634680" \
  -H "x-api-key: $API_KEY"

Response

200 — Templates fetched successfully

{
  "status": true,
  "status_code": 200,
  "message": "Templates fetched successfully",
  "data": [
    {
      "name": "eazybe_temp",
      "status": "APPROVED",
      "category": "MARKETING",
      "language": "en",
      "components": [
        { "type": "BODY", "text": "Hello {{1}}, your code is {{2}}." }
      ]
    }
  ]
}

Count the {{n}} placeholders in the body — that is exactly how many values each recipient’s templateParams array must supply.

Send template broadcast

Sends an approved template to a list of recipients. Behavior changes with list size: up to 1,000 recipients the broadcast is queued synchronously; above that it is split into chunks and processed as a background job you poll for status.

Endpoint

POST /broadcast/public/send-template-broadcast

Headers

Header	Required	Description
`x-api-key`	Required	Organization auth key
`Content-Type`	Required	`application/json`
`Idempotency-Key`	Optional	Unique string, safe to retry with

Body

Field	Type	Required	Description
`broadcastName`	string	Required	Campaign label shown in reporting
`fromPhoneNumber`	string	Required	Your WABA number, from Get phone numbers
`templateName`	string	Required	Approved template name
`templateLanguage`	string	Required	Language code, e.g. `en`
`templateType`	string	Required	`MARKETING`, `UTILITY`, and so on
`templateId`	string	Optional	WhatsApp template ID
`globalTemplateParams`	string[]	Optional	Defaults applied to recipients without their own params
`data`	object[]	Required	Recipients, 1 to 10,000

Recipient object

Field	Type	Required	Description
`countryCode`	string	Required	Digits only, no `+`. e.g. `91`
`toPhoneNumber`	string	Required	Digits only, without country code
`templateParams`	string[]	Optional	Values for `{{1}}`, `{{2}}`… Overrides globals.

Request

curl -X POST "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-template-broadcast" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: festive-run-1" \
  -d '{
    "broadcastName": "Festive Offer Campaign",
    "fromPhoneNumber": "14844634680",
    "templateName": "eazybe_temp",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "1530766784804741",
    "globalTemplateParams": ["Valued customer", "FESTIVE10"],
    "data": [
      {
        "countryCode": "91",
        "toPhoneNumber": "9675360316",
        "templateParams": ["Vineet", "VIP20"]
      },
      {
        "countryCode": "91",
        "toPhoneNumber": "8077378155"
      }
    ]
  }'

In this example the first recipient gets their own values and the second falls back to globalTemplateParams.

Responses

200 — Queued (1,000 recipients or fewer)

{
  "status": true,
  "status_code": 200,
  "message": "Bulk broadcast queued successfully",
  "data": { }
}

202 — Accepted for background processing (more than 1,000 recipients)

{
  "status": true,
  "status_code": 202,
  "message": "Broadcast accepted for background processing",
  "data": {
    "jobId": "pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67",
    "status": "PROCESSING",
    "totalRecipients": 1001,
    "chunkSize": 1000,
    "totalChunks": 2
  }
}

Keep the jobId — it is the only way to check how the broadcast finished. Poll Get broadcast status with it. 400 — Recipient limit exceeded

{
  "status": false,
  "status_code": 400,
  "message": "Recipient limit exceeded",
  "data": {
    "error": {
      "message": "Template broadcast cannot exceed 10000 recipients per request."
    }
  }
}

400 — Template not approved

{
  "status": false,
  "status_code": 400,
  "message": "Template is not approved or not found",
  "data": {
    "error": {
      "message": "Template is not approved or not found for this WABA phone number."
    }
  }
}

Duplicate recipients are rejected, not merged. If the same countryCode + toPhoneNumber pair appears twice, the entire request fails with a 400 naming the index of the duplicate. Deduplicate your list before sending.

Send free-form message

Sends a single message to one recipient. All eight content types share this endpoint — the type field decides which other fields are required.

Endpoint

POST /broadcast/public/send-freeform

Common fields

Field	Type	Required	Description
`fromPhoneNumber`	string	Required	Your WABA number
`toPhoneNumber`	string	Required	Recipient with country code, digits only
`type`	string	Required	One of the eight types below

Type-specific fields

`type`	Required	Optional	Accepted file extensions
`text`	`text`	—	—
`image`	`url`	`caption`	jpg, jpeg, png
`document`	`url`	`name`, `caption`	pdf, txt, doc, docx, ppt, pptx, xls, xlsx
`audio`	`url`	—	aac, amr, mp3, m4a, mp4, ogg, opus
`video`	`url`	`caption`	mp4, 3gp
`sticker`	`url`	—	webp
`location`	`latitude`, `longitude`	`name`, `address`	—
`interactive`	`interactive`	—	—

The extension is read from the URL path, not the file. A real PNG served from a URL ending in .webp is rejected for image, and a URL with no extension at all is rejected for every media type. Query strings are ignored, so …/photo.png?v=2 is fine.

Text

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "text",
  "text": "Your order #4821 has shipped."
}

Image

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "image",
  "url": "https://cdn.example.com/offer.jpg",
  "caption": "This week only"
}

Document

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "document",
  "url": "https://cdn.example.com/invoice-4821.pdf",
  "name": "Invoice_4821.pdf",
  "caption": "Your invoice is ready"
}

Audio

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "audio",
  "url": "https://cdn.example.com/voice-note.mp3"
}

Video

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "video",
  "url": "https://cdn.example.com/demo.mp4",
  "caption": "60-second walkthrough"
}

Sticker

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "sticker",
  "url": "https://cdn.example.com/thumbs-up.webp"
}

Location

latitude and longitude must be JSON numbers, not strings. Latitude accepts −90 to 90, longitude −180 to 180.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "location",
  "latitude": 28.4595,
  "longitude": 77.0266,
  "name": "Eazybe HQ",
  "address": "Sector 44, Gurugram, Haryana 122003"
}

Interactive — buttons

Up to 3 reply buttons. More than three is rejected.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { "type": "text", "text": "Renew your plan" },
    "body": { "text": "Your subscription ends in 3 days. Renew now?" },
    "footer": { "text": "Reply STOP to opt out" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "renew_yes", "title": "Renew now" } },
        { "type": "reply", "reply": { "id": "renew_later", "title": "Remind me later" } }
      ]
    }
  }
}

Interactive — list

Up to 10 rows counted across all sections combined, not per section.

{
  "fromPhoneNumber": "14844634680",
  "toPhoneNumber": "919675360316",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Pick a plan" },
    "body": { "text": "Choose the plan that fits your team." },
    "action": {
      "button": "View plans",
      "sections": [
        {
          "title": "Monthly",
          "rows": [
            { "id": "starter_m", "title": "Starter", "description": "3 seats included" },
            { "id": "growth_m", "title": "Growth", "description": "10 seats included" }
          ]
        }
      ]
    }
  }
}

Response

200 — same shape for all eight types

{
  "status": true,
  "status_code": 200,
  "message": "Free-form message queued successfully",
  "data": { }
}

Get broadcast status

Returns the progress of a large broadcast job — the ones that returned 202 and a jobId. Broadcasts of 1,000 recipients or fewer do not create a job and have nothing to poll.

Endpoint

GET /broadcast/public/status/:jobId

Request

curl "https://cerberus.eazybe.com/prod/api/v2/broadcast/public/status/pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67" \
  -H "x-api-key: $API_KEY"

Responses

200 — job record plus a summary of chunk progress

{
  "status": true,
  "status_code": 200,
  "message": "Broadcast status fetched successfully",
  "data": {
    "jobId": "pub_4f8c2a1e9b7d43c6a5e0f2b18d3c9a67",
    "status": "QUEUED_FOR_PROCESSING",
    "totalRecipients": 1001,
    "totalChunks": 2,
    "summary": { }
  }
}

404 — Broadcast job not found 401 — Job belongs to a different organization A job created by another organization returns 401 rather than 404 — job IDs are not enumerable across organizations.

Health check

Confirms the service is up and lists the routes it currently exposes. No API key needed.

Endpoint

GET /broadcast/public/health

{
  "status": "ok",
  "timestamp": "2026-07-22T11:04:33.812Z",
  "service": "Public Broadcast API",
  "version": "2.0.0",
  "endpoints": {
    "generate-key": "POST /broadcast/public/generate-key",
    "template-broadcast": "POST /broadcast/public/send-template-broadcast",
    "freeform": "POST /broadcast/public/send-freeform",
    "templates": "GET /broadcast/public/templates",
    "phone-numbers": "GET /broadcast/public/phone-numbers",
    "status": "GET /broadcast/public/status/:jobId",
    "single": "POST /broadcast/public/send-single",
    "bulk-standard": "POST /broadcast/public/send-bulk",
    "health": "GET /broadcast/public/health"
  }
}

Validation rules

These run before anything reaches WhatsApp, so a rejection here costs no message quota. Every failure returns 400 with message: "Validation error" and a specific reason.

Rule	Applies to	On failure
Phone numbers must be digits only — no `+`, spaces, or dashes	Both send endpoints	Invalid `toPhoneNumber` / `countryCode`
At least one recipient	Template broadcast	Recipient list is required
No duplicate `countryCode` • `toPhoneNumber`	Template broadcast	Duplicate recipient found at index n
Maximum 10,000 recipients	Template broadcast	Recipient limit exceeded
Template must exist and be approved for that number	Template broadcast	Template is not approved or not found
`text` must be a non-empty string	Free-form, type `text`	text is required for text messages
`url` must be http or https	Free-form media types	url must be a valid http or https URL
URL extension must be on the allowed list	Free-form media types	Lists the accepted extensions
Latitude −90 to 90, longitude −180 to 180, both numbers	Free-form, type `location`	Names the offending coordinate
Interactive type must be `button` or `list`	Free-form, type `interactive`	interactive type must be button or list
1 to 3 buttons	Interactive buttons	Cannot exceed 3 buttons
1 to 10 rows across all sections	Interactive list	Cannot exceed 10 rows

Rate limits

Limits are counted in a fixed 60-second window. Most are scoped to your API key and the phone number in the request, so two different sending numbers do not compete for the same budget.

Endpoint	Limit	Counted per
`send-template-broadcast`	10 / min	key + fromPhoneNumber
`send-freeform`	20 / min	key + fromPhoneNumber
`templates`	20 / min	key + phone_number
`phone-numbers`	30 / min	key
`status`	30 / min	key

Exceeding a limit

{
  "status": false,
  "status_code": 429,
  "message": "Rate limit exceeded",
  "data": {
    "error": {
      "message": "Rate limit exceeded. Try again in 43 seconds."
    }
  }
}

The message tells you exactly how many seconds remain in the window. Wait that long rather than retrying immediately — an immediate retry consumes nothing but returns the same error.

Error Handling

Every error uses the same envelope:

{
  "status": false,
  "status_code": 400,
  "message": "Short summary",
  "data": {
    "error": {
      "message": "Specific detail about what to fix"
    }
  }
}

Status codes

Code	Meaning	What to do
`200`	Queued or fetched	—
`202`	Large broadcast accepted	Poll status with the `jobId`
`400`	Validation or limit failure	Read `data.error.message` and fix the payload
`401`	Key, number, or job ownership problem	See the table below
`404`	Broadcast job not found	Check the `jobId`
`409`	Same `Idempotency-Key` still processing	Wait and poll; do not resend
`429`	Rate limit exceeded	Wait the seconds named in the message
`500`	Send failed downstream	Retry with the same `Idempotency-Key`
`503`	Auth database timed out	Retry with backoff

The four 401s

All four return 401 but mean different things:

Message	Cause	Fix
API key is required	No `x-api-key` header	Add the header
Invalid API key. Organization not found.	No organization has that `auth_key`	Check the key, and that you are on the right environment
No WABA account found for this organization.	The number is not registered to your organization	Use a number from Get phone numbers
WABA account is incomplete. Missing fields: …	The WABA record is missing `waba_id`, `phone_number_id`, `phone_number`, or `access_token`	Finish WABA onboarding for that number

Retry policy. Retry 500 and 503 with exponential backoff. Never retry 400 or 401 — the same request will fail identically. On 429, wait the interval the response names. Always send an Idempotency-Key on requests you intend to retry.

Legacy endpoints

Different authentication. These three predate v2 and still use the older per-number WABA key, not your organization auth_key. They are unchanged and remain supported, but new integrations should use the v2 endpoints above.

POST /broadcast/public/generate-key      no auth · 5/min

Generates a legacy API key for a phone number. Takes phoneNumber, not an organization ID.

{ "phoneNumber": "919876543210" }

POST /broadcast/public/send-single       legacy key · 30/min

Sends one template message. Recipient fields sit at the top level rather than in a data array.

POST /broadcast/public/send-bulk         legacy key · 10/min

Bulk template send, capped at 1,000 recipients — there is no chunking and no job ID. Exceeding the cap returns 400 in the response body with an HTTP 200 status line, unlike the v2 endpoint which throws.

​Overview

​Base Configuration

​Before You Start

​Authentication Flow

​Use Auth Key in Request Headers

​What the key resolves to

​Endpoint index

​Get phone numbers

​Endpoint

​Request

​Response

​Get templates

​Endpoint

​Query parameters

​Request

​Response

​Send template broadcast

​Endpoint

​Headers

​Body

​Recipient object

​Request

​Responses

​Send free-form message

​Endpoint

​Common fields

​Type-specific fields

​Text

​Image

​Document

​Audio

​Video

​Sticker

​Location

​Interactive — buttons

​Interactive — list

​Response

​Get broadcast status

​Endpoint

​Request

​Responses

​Health check

​Endpoint

​Validation rules

​Rate limits

​Exceeding a limit

​Error Handling

​Status codes

​The four 401s

​Legacy endpoints

Overview

Base Configuration

Before You Start

Authentication Flow

Use Auth Key in Request Headers

What the key resolves to

Endpoint index

Get phone numbers

Endpoint

Request

Response

Get templates

Endpoint

Query parameters

Request

Response

Send template broadcast

Endpoint

Headers

Body

Recipient object

Request

Responses

Send free-form message

Endpoint

Common fields

Type-specific fields

Text

Image

Document

Audio

Video

Sticker

Location

Interactive — buttons

Interactive — list

Response

Get broadcast status

Endpoint

Request

Responses

Health check

Endpoint

Validation rules

Rate limits

Exceeding a limit

Error Handling

Status codes

The four 401s

Legacy endpoints