Broadcasts

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.

Broadcasts need the whatsapp:campaign scope on your app key. You can only broadcast an approved template — build and submit one first (see Creating & managing templates).

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"
} }
FieldTypeNotes
channelIdstringRequired. The native channel to send from
namestringRequired. A label for your own reference
templatestringRequired. Name of an approved template on this channel
languagestringOptional. Template language (defaults to en_US)
throttle_per_minnumberOptional. Max sends per minute — defaults to 60. Protects your quality rating
recipientsarrayRequired. { phone, variables? } per contact — see below. ≤ 5,000 per campaign
autostartboolOptional. Defaults to true — set false to create it paused and start it later

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 (recipients dropped before sending — already opted out via a prior STOP, or duplicates). status is running when autostart is true.

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": {
    "queued": 0,
    "sent": 0,
    "delivered": 1,
    "read": 1,
    "failed": 0
  }
} }

Each recipient advances queued → sent → delivered → read (or failed) as Meta reports status back. status on the campaign is running, paused, completed, or cancelled. sent and failed are running totals; statusCounts is the per-state histogram. For per-message detail, subscribe to whatsapp.message.status — each broadcast send carries the same wamid you can correlate.

Pause & cancel

# Pause — stops sending; resume later by re-creating or from the dashboard
curl -X POST https://api.telenow.ai/api/app-whatsapp/campaigns/c4f0a1b2-…/pause \
  -H "Authorization: Bearer vai_app_…"

{ "success": true, "data": { "success": true } }

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

{ "success": true, "data": { "success": true } }

Pause halts an in-flight campaign; cancel ends it for good. Already-sent messages are unaffected either way.

STOP opt-out is automatic

A STOP reply from a customer (also unsubscribe / optout) automatically opts that contact out. Opted-out contacts are suppressed from every future broadcast — you’ll see them counted in the suppressed field of the create response rather than messaged. You don’t implement anything; honouring STOP is handled for you.

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

LimitValue
Recipients per campaign5,000
Active campaigns per app50
Default throttle60 sends/minute
TemplateMust be approved on the channel
ChannelNative channels only

Exceeding 5,000 recipients or 50 active campaigns returns a 400. To message a larger audience, split it across multiple campaigns.

Endpoint reference

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

MethodPathPurpose
POST/campaignsCreate + (auto)start → { campaignId, inserted, suppressed, status }
GET/campaigns/{id}Status → { id, name, status, totalRecipients, sent, failed, statusCounts }
POST/campaigns/{id}/pausePause → { success: true }
POST/campaigns/{id}/cancelCancel → { success: true }

The dashboard equivalent lives under /api/orgs/{orgId}/whatsapp-campaigns (with an opt-out list and CSV recipient upload); mutations require owner/admin/developer.