Messaging
Broadcasts
Send one approved WhatsApp template to an audience of contacts — now or at a set time — paced, consent-checked and billed per message.
A broadcast sends one approved template — WhatsApp (marketing or utility), SMS (any DLT category but one-time codes) or email (any but authentication); the broadcast takes its template's channel — to an audience of your contacts. SMS and email recipients are checked by their channel's own rules: an SMS needs a number in a country you text and the consent its TRAI category needs (a promotional SMS waits for its 09:00–21:00 window); an email needs an address that is not suppressed and, for marketing, an opt-in, and carries the unsubscribe link. POST /v1/broadcasts (broadcasts:write) creates it and starts it in one step — there are no API drafts — and it is then paced, checked and billed exactly like one launched in the console, where it shows up too.
Create a broadcast
curl -X POST 'https://api.trovacast.com/v1/broadcasts' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: broadcast-diwali-2026' \
-H 'Content-Type: application/json' \
-d '{
"name": "Diwali offer",
"template": {
"name": "diwali_offer",
"language": "en"
},
"audience": {
"tags": [
"vip"
],
"attributes": [
{
"key": "city_zone",
"value": "north"
}
]
},
"variables": [
{
"variable": "var1",
"source": "contact_field",
"field": "firstName",
"fallback": "there"
},
{
"variable": "var2",
"source": "literal",
"value": "20%"
}
],
"timezone": "Asia/Kolkata",
"sendingWindow": {
"start": "10:00",
"end": "20:00"
},
"scheduledAt": "2026-11-01T04:30:00.000Z"
}'Template
By { id } or { name, language }: an approved WhatsApp MARKETING or UTILITY template. An AUTHENTICATION template is one person’s code, never a broadcast (400). Unknown: 404 TEMPLATE_NOT_FOUND; not approved, or deleted: 409 TEMPLATE_NOT_SENDABLE.
Audience
Filters over the project’s contacts, each narrowing the last: contactIds (at most 10,000), tags (exact, with tagMode any — the default — or all), attributes (equality on the custom attributes set with POST /v1/contacts; every clause must hold) and excludeMessagedWithinHours. Give at least one of contactIds, tags or attributes — or allContacts: true, alone — so a broadcast to everyone is never the result of a forgotten field.
Whoever the filters match, only contacts who can receive it are sent to. When the broadcast starts its audience is snapshotted: each matched contact is either pending, or skipped with a reason — blocked or archived, opted out of all contact or of WhatsApp, no full WhatsApp opt-in (a broadcast needs marketing: "opted_in" even for a UTILITY template), a missing variable, or a number whose last WhatsApp send failed as undeliverable within 90 days.
Variables
Bind every template variable exactly once: literal (the same value for everyone; a media header takes one public https link), contact_field (displayName, firstName, company, jobTitle, city, state, preferredLanguage, leadSource, externalReference — never the phone, the email or notes) or custom_field (key, a custom attribute). A contact whose value is empty, or looks like a phone number or an email address, gets fallback; without one, that contact is skipped. Omit variables for a template that has none.
Pacing and scheduling
senderIds(numbers[].senderIdfromGET /v1/whatsapp/account; default: the default number) withsenderStrategysingleorrotate.maxPerSecond,dailyCap(sends in any 24 hours), andtimezone+sendingWindow(HH:MMstart and end, optional ISOdays) — outside the window it waits. It never outruns the WhatsApp messaging-limit tier left for the rolling 24 hours either.endsAt: recipients not reached by then are skipped.scheduledAtmore than a minute out makes itscheduled, and its audience is snapshotted when it starts. Omitted, past or within the minute, it starts now (running).
Every check runs before anything is written — messaging on the project, an active project, an approved template with every variable bound, a connected account with a healthy number, an audience that is neither empty nor too large, and the estimated cost against your wallet. A refusal leaves nothing behind. Each message is then charged as WhatsApp accepts it, and a wallet that runs dry holds the broadcast (holdReason: BILLING_*) rather than failing it.
The broadcast
{
"object": "broadcast",
"id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"name": "Diwali offer",
"channel": "whatsapp",
"status": "scheduled",
"statusReason": null,
"holdReason": null,
"template": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"name": "diwali_offer",
"language": "en",
"category": "MARKETING"
},
"senderStrategy": "single",
"maxPerSecond": 20,
"timezone": "Asia/Kolkata",
"sendingWindow": {
"start": "10:00",
"end": "20:00",
"days": []
},
"counts": {
"recipients": 0,
"pending": 0,
"skipped": 0,
"cancelled": 0,
"queued": 0,
"sending": 0,
"sent": 0,
"delivered": 0,
"read": 0,
"failed": 0
},
"scheduledAt": "2026-11-01T04:30:00.000Z",
"startedAt": null,
"createdAt": "2026-10-31T12:00:00.000Z"
}statusisscheduled,running,paused,completed,cancelledorfailed.statusReasonsays why it is paused, failed or ended early:OPERATOR;TEMPLATE_NOT_APPROVED,CHANNEL_UNAVAILABLEorNO_HEALTHY_SENDERwhen the system paused it;TEMPLATE_DELETED,AUDIENCE_TOO_LARGEorVARIABLES_INVALIDwhen a scheduled start failed;EXPIREDwhen it completed early.holdReasonsays why a running broadcast sent nothing on its last pass (THROTTLED,INTERACTIVE_BACKLOG,TIER_LIMIT,DAILY_CAP,BILLING_*), cleared once it sends again.countscounts every recipient once, each dispatched one under its message’s current status (delivereddoes not includeread). A broadcast never lists who it reached: read that message by message withGET /v1/messages, which needsmessages:read.
Pause, resume and cancel
POST /v1/broadcasts/{broadcastId}/pausestops dispatching; messages still waiting to be sent are taken back (never charged) and sent afresh on resume.POST /v1/broadcasts/{broadcastId}/resumeis checked again like a launch: the template, the number and the wallet for what is left.POST /v1/broadcasts/{broadcastId}/cancelis for good: pending recipients are cancelled and queued messages fail. A scheduled, running or paused broadcast can be cancelled.
Each action answers the broadcast. One already in the state asked for is answered as it is, so a retry converges; an action its status does not allow (pausing a completed broadcast) is a 409.
curl -X POST 'https://api.trovacast.com/v1/broadcasts/BROADCAST_ID/pause' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Endpoints
- POST
/v1/broadcastsSends an approved template (WhatsApp, SMS or email) to an audience of contacts, now or at a set time - GET
/v1/broadcastsLists broadcasts, newest first, with their counts - GET
/v1/broadcasts/{broadcastId}Retrieves a broadcast and where its recipients stand - POST
/v1/broadcasts/{broadcastId}/pausePauses a running broadcast - POST
/v1/broadcasts/{broadcastId}/resumeResumes a paused broadcast - POST
/v1/broadcasts/{broadcastId}/cancelCancels a scheduled, running or paused broadcast
Events
A broadcast’s messages report like any other — message.sent, message.delivered, message.read, message.failed (see Webhooks) — and they carry no metadata.
Errors
Besides the codes below, a broadcast is refused 409 AUDIENCE_EMPTY when nobody who matches can be sent to (the body’s audience has the counts), 422 AUDIENCE_TOO_LARGE when it matches more contacts than one broadcast may reach, 409 ORGANIZATION_NOT_ACTIVE when the project is suspended or closed, and 409 BROADCAST_INVALID_STATE when its status does not allow the action.
| Code | Status | Meaning and what to do |
|---|---|---|
BILLING_INSUFFICIENT_CREDIT | 402 | The prepaid wallet, after any included plan minutes, cannot cover the messages at your plan's rate — or a call's ceiling: its maxDurationSec in started minutes, beside what your live API calls already in flight can still run to (inFlightMinutes), each at its own rate.What to do: Top up the prepaid balance (POST /v1/balance/top-ups, or Add credit in Settings → Billing), then retry. When the refusal carries maxDurationSecAvailable, a call with a maxDurationSec up to it is placed now; without it no shorter call fits — retry once a call in progress ends. See Limits and billing. |
BILLING_RATE_UNAVAILABLE | 503 | Your plan has no rate for this channel and mode (or message category) — a configuration gap on our side, not a debt.What to do: Retrying will not help until the plan prices it: contact us. GET /v1/pricing shows the rates your plan has. |
BILLING_SUBSCRIPTION_CANCELED | 402 | The subscription was cancelled at a period end.What to do: A project administrator chooses a plan in Settings → Billing, which reactivates the subscription; then retry. |
BILLING_SUBSCRIPTION_PAST_DUE | 402 | The monthly fee is unpaid: it left the wallet negative.What to do: Top up enough to bring the balance back to zero or above (POST /v1/balance/top-ups): the subscription reactivates by itself, then retry. |
BILLING_SUBSCRIPTION_SUSPENDED | 402 | The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us. |
CONFLICT | 409 | The resource's state does not allow this, there is a uniqueness clash, or it changed concurrently.What to do: Read the resource again, then decide: retry against its current state (with its new version where it has one), or choose another value for a uniqueness clash. |
ENTITLEMENT_MESSAGING_DISABLED | 403 | Messaging is not enabled for this project (it is calling-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn messaging on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then. |
NO_SENDER_AVAILABLE | 409 | There is nothing to send from: no WhatsApp number (or the conversation’s number was removed), no chosen number that can send, or no active SMS header that fits the template’s category.What to do: Connect a WhatsApp number (Settings → Channels → WhatsApp) or choose one that can send; for SMS, register a header of the kind the category needs — numeric for promotional, alphabetic otherwise — and send once the platform has activated it. |
TEMPLATE_NOT_FOUND | 404 | No template of this channel matches the id, or the name and language, the request named.What to do: Check the id, or the name and language, against GET /v1/templates for the channel you are sending on — a template belongs to one channel. |
TEMPLATE_NOT_SENDABLE | 409 | The template is not approved — pending review, paused, rejected, disabled or deleted, or an SMS template without its DLT id. Also a message.failed code when it changed after the message was queued.What to do: Send an approved template, or wait for Meta’s verdict (template.updated); give an SMS template its dltTemplateId with PATCH /v1/templates/{templateId}. A message that failed with this code was not sent: send it again once the template is approved. |
VALIDATION_FAILED | 400 | The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields. |
WHATSAPP_NOT_CONNECTED | 409 | No connected WhatsApp account — needed to submit, edit, delete or sync templates, to send a read receipt, and to create or resume a broadcast.What to do: Connect a WhatsApp account (or reconnect it in Settings → Channels → WhatsApp), then retry. |