Broadcasts

Send an approved template to many contacts at once, with per-recipient variables and a throttle that protects your number’s quality rating. A broadcast is a campaign: create it, then track it to completion.

With an app key, broadcasts need the whatsapp:campaign scope. You can only broadcast an approved template — build and submit one first (see Creating & managing templates). With your org API key you get the full flow — drafts, scheduling, saved audiences, start and resume — on more kinds of numbers.

Create a broadcast

POST /campaigns queues the campaign and (by default) starts sending immediately.

curl -X POST https://api.telenow.ai/api/app-whatsapp/campaigns \
  -H "Authorization: Bearer vai_app_…" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "b1e2c3d4-…",
    "name": "Spring sale",
    "template": "spring_sale",
    "language": "en_US",
    "throttle_per_min": 120,
    "recipients": [
      { "phone": "+919876543210", "variables": ["Asha"] },
      { "phone": "+919812345678", "variables": ["Ravi"] }
    ]
  }'

{ "success": true, "data": {
  "campaignId": "c4f0a1b2-…",
  "inserted": 2,
  "suppressed": 0,
  "status": "running"
} }

Per-recipient variables. Each recipient supplies its own variables array, filling the template’s {{1}}, {{2}}… in order — so every contact gets a personalised message from one approved template:

"recipients": [
  { "phone": "+919876543210", "variables": ["Asha", "#1234"] },
  { "phone": "+919812345678", "variables": ["Ravi", "#1235"] }
]

The response reports inserted (recipients queued) and suppressed (opted-out numbers — they're added to the campaign as suppressed and never messaged). A number listed twice is queued once; the duplicate is dropped and counted in neither field. status is running when autostart is true and at least one recipient was queued; otherwise it's draft.

Track a broadcast

Poll GET /campaigns/{id} for live progress. statusCounts breaks the roster down by delivery state:

curl https://api.telenow.ai/api/app-whatsapp/campaigns/c4f0a1b2-… \
  -H "Authorization: Bearer vai_app_…"

{ "success": true, "data": {
  "id": "c4f0a1b2-…",
  "name": "Spring sale",
  "status": "running",
  "totalRecipients": 2,
  "sent": 2,
  "failed": 0,
  "statusCounts": {
    "delivered": 1,
    "read": 1
  }
} }

Each recipient advances queued → sending → sent → delivered → read (or failed) as Meta reports status back; opted-out recipients sit at suppressed. statusCounts lists only the states that currently hold recipients. status on the campaign is draft, running, paused, completed, or cancelled. sent and failed are running totals. For per-message detail, subscribe to whatsapp.message.status — each broadcast send carries the same wamid you can correlate.

An app key sees only the campaigns it created — any other id returns 404. Sending is capped at about 400 messages a minute per campaign, whatever throttle_per_min says.

Pause & cancel

# Pause — stops sending; resume with your org API key (…/start) or from the dashboard
curl -X POST https://api.telenow.ai/api/app-whatsapp/campaigns/c4f0a1b2-…/pause \
  -H "Authorization: Bearer vai_app_…"

{ "success": true }

# Cancel — stops sending permanently; queued recipients become "suppressed"
curl -X POST https://api.telenow.ai/api/app-whatsapp/campaigns/c4f0a1b2-…/cancel \
  -H "Authorization: Bearer vai_app_…"

{ "success": true }

Pause halts a running campaign; cancel ends a draft, running or paused one for good. Already-sent messages are unaffected either way. Pausing a campaign that isn't running, or cancelling one that's already completed or cancelled, returns 409.

Opt-outs

A customer who replies with exactly one of stop, stopall, unsubscribe, optout, opt out or opt-out (the whole message, any case) is opted out automatically. Opted-out numbers are suppressed from every future broadcast — counted in suppressed rather than messaged — their still-queued messages in running campaigns are suppressed too, and template sends to them are refused. A sentence that merely contains "stop" doesn't opt anyone out.

STOP replies are recorded for Meta Cloud numbers. For partner numbers (GupShup, Plivo, AiSensy), add opt-outs yourself with your org API key:

There is no route to remove an opt-out.

Opt-in is mandatory before you broadcast, and a weak, un-opted list tanks your quality rating fast. Keep lists clean and lean on the throttle_per_min to ramp gently.

Limits

On the app key, exceeding 5,000 recipients or 50 active campaigns returns a 400. To message a larger audience, split it across campaigns — or use your org API key.

Endpoint reference

Base /api/app-whatsapp, scope whatsapp:campaign.

The dashboard's CSV/XLSX upload is parsed in the browser into the same rows these endpoints take, so the API takes JSON only.

With your org API key

With your org API key (X-API-Key: vai_live_…) a broadcast is built in steps — create a draft → add recipients → start — under /api/orgs/{orgId}/whatsapp-campaigns. Bodies use snake_case, and responses return the campaign as a database row (snake_case). Changes need an owner, admin or developer key, created by someone with one of those roles.

# 1) Create a draft (no recipients yet)
curl -X POST https://api.telenow.ai/api/orgs/{orgId}/whatsapp-campaigns \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "b1e2c3d4-…",
    "name": "Spring sale",
    "template_name": "spring_sale",
    "template_language": "en_US",
    "throttle_per_min": 120
  }'

# 2) Add recipients (repeat as needed, up to 20,000 per call)
curl -X POST https://api.telenow.ai/api/orgs/{orgId}/whatsapp-campaigns/{id}/recipients \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": [ { "phone": "+919876543210", "variables": ["Asha"] } ] }'

# 3) Start
curl -X POST https://api.telenow.ai/api/orgs/{orgId}/whatsapp-campaigns/{id}/start \
  -H "X-API-Key: vai_live_…"

Create (POST /) takes channel_id, name and template_name (required), plus optional:

It returns { campaign } as a draft. On Meta Cloud numbers the template must be approved for that language (400 otherwise); WhatsApp Web numbers can't broadcast.

The org routes also start, pause and cancel campaigns created by an app key.

Related

• Creating & managing templates — build the approved template you broadcast.
• Webhooks & events — per-recipient whatsapp.message.status updates.
• Reading conversations — read replies to your broadcast.
• WhatsApp API · WhatsApp product guide.