Trovacast

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

Schedule a broadcast to VIP customers in the north zone
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[].senderId from GET /v1/whatsapp/account; default: the default number) with senderStrategy single or rotate.
  • maxPerSecond, dailyCap (sends in any 24 hours), and timezone + sendingWindow (HH:MM start and end, optional ISO days) — 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.
  • scheduledAt more than a minute out makes it scheduled, 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

201 Created (json)
{
  "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"
}
  • status is scheduled, running, paused, completed, cancelled or failed.
  • statusReason says why it is paused, failed or ended early: OPERATOR; TEMPLATE_NOT_APPROVED, CHANNEL_UNAVAILABLE or NO_HEALTHY_SENDER when the system paused it; TEMPLATE_DELETED, AUDIENCE_TOO_LARGE or VARIABLES_INVALID when a scheduled start failed; EXPIRED when it completed early.
  • holdReason says why a running broadcast sent nothing on its last pass (THROTTLED, INTERACTIVE_BACKLOG, TIER_LIMIT, DAILY_CAP, BILLING_*), cleared once it sends again.
  • counts counts every recipient once, each dispatched one under its message’s current status (delivered does not include read). A broadcast never lists who it reached: read that message by message with GET /v1/messages, which needs messages:read.

Pause, resume and cancel

  • POST /v1/broadcasts/{broadcastId}/pause stops dispatching; messages still waiting to be sent are taken back (never charged) and sent afresh on resume.
  • POST /v1/broadcasts/{broadcastId}/resume is checked again like a launch: the template, the number and the wallet for what is left.
  • POST /v1/broadcasts/{broadcastId}/cancel is 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.

Pause a broadcast
curl -X POST 'https://api.trovacast.com/v1/broadcasts/BROADCAST_ID/pause' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Endpoints

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.

CodeStatusMeaning and what to do
BILLING_INSUFFICIENT_CREDIT402The 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_UNAVAILABLE503Your 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_CANCELED402The 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_DUE402The 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_SUSPENDED402The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us.
CONFLICT409The 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_DISABLED403Messaging 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_AVAILABLE409There 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_FOUND404No 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_SENDABLE409The 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_FAILED400The 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_CONNECTED409No 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.