Skip to content

REST API v1 · Resource

Broadcasts

Send a template to many contacts, preview who it reaches, follow each recipient and cancel.

API reference · Broadcasts

Endpoints

Paths are relative to https://fliok.com/api/v1. Each endpoint names the scope and the lowest key role it needs; a key without them gets 403 (see Authentication).

Broadcasts

6
  • GET/broadcastsList campaigns with live sent/delivered/failed countsScope broadcasts:read · viewer role or higher
  • POST/broadcastsCreate a campaign by tags, contact ids or a number list. Returns how many will actually send after opt-out and the marketing capScope broadcasts:write · admin role or higher
  • GET/broadcasts/{id}One campaign with its delivery progressScope broadcasts:read · viewer role or higher
  • DELETE/broadcasts/{id}Cancel a campaign. Messages already handed to WhatsApp cannot be recalledScope broadcasts:write · admin role or higher
  • GET/broadcasts/{id}/recipientsWho a campaign went to and what happened to each (status, reason, sent/delivered/read times), cursor-paginated. Numbers and names need contacts:read tooScope broadcasts:read · viewer role or higher
  • POST/broadcasts/previewWhat POST /broadcasts would do with this body — matched, will send, suppressed and why, new recipients, plan and reach warnings, Meta’s estimated cost. Writes nothingScope broadcasts:write · admin role or higher

Request bodies

What these endpoints take, field by field. A body that doesn’t match answers 400 naming the field.

POST /broadcasts

JSON body, admin keys. Refused before anything is written when this month’s allowance is used up or a template variable is blank. Recipients who have never messaged you (and have no opt-in recorded) have their own rules, the same as in the dashboard: 422 "notice_to_new_recipients" for a utility or authentication template, 409 "new_recipients_unconfirmed" without confirmNewRecipients, 409 "new_recipient_cool_off" after Meta restricted the account, and 409 "follow_up_too_soon" when they were sent a broadcast in the last few days and have not replied. Each answer carries a "message", "newRecipients" and "knownRecipients"; knownOnly is always accepted. A 409 "number_banned" or "sending_blocked" means Meta is refusing messages from the number.

FieldTypeWhat it is
namerequiredstringUp to 200 characters.
templateIdrequireduuidAn approved template’s id (GET /templates).
phoneNumberIdrequireduuidThe number that sends (GET /phone-numbers).
segmentrequiredobjectWho receives it: { "tags": [ … ] } and/or "excludeTags", "optInStatus", "lastSeenWithinDays" — or { "contactIds": [ … ] } for hand-picked contacts (an empty list means nobody).
variablesobjectThe template’s parameters as { "components": [ … ] }, the same shape a template send uses.
sendNowbooleanStart sending at once.
scheduledAtISO timeSend later instead. With neither, it is saved as a draft.
confirmNewRecipientsbooleanYour confirmation that the recipients who have never messaged you agreed to get WhatsApp messages from your business. Recorded in the activity log.
knownOnlybooleanSend only to recipients who have messaged you or have an opt-in recorded; the others are listed as skipped.
followUpOfuuidThe broadcast this one follows up. A follow-up to a marketing broadcast must use a marketing template.

Returns 201 { "id", "status": "running" | "scheduled" | "draft", "audience": { "matched", "willSend", "suppressed" }, "newRecipients" } — willSend is how many will actually be messaged after opt-outs and Meta’s marketing cap. newRecipients is how many of them have never messaged you; they are sent gradually, a daily allowance per number, so the broadcast can stay "running" for several days.

Rate limits

The buckets these endpoints use. Burst is how many requests you can make back-to-back from a full bucket; sustained is how fast it refills.

BucketEndpointsBurstSustained
Broadcast cancelDELETE /broadcasts/{id}301 / 2 sec
Broadcast createPOST /broadcasts1010 / hour

Every limit, the RateLimit-* headers and what to do on a 429: Rate limits.