Overview

Send an approved template to many recipients with per-recipient tracking

A broadcast sends one approved WhatsApp template to a list of recipients, and tracks delivery, reads, and replies for each one.

Broadcasts are template-only. Meta requires an approved template to open a conversation, so free-form text cannot be broadcast.

Lifecycle

Status	Meaning
draft	Being built. Recipients can be added or cleared
scheduled	Will start automatically at scheduled_at
copying	Duplicated from another broadcast, recipients still being copied. Shown as Preparing in the dashboard
sending	Currently delivering
completed	All recipients processed
stopped	Manually stopped mid-send
failed	Could not complete

Two paths through it:

• draft → sending → completed, failed, or stopped
• draft → scheduled → sending → …

The transitions are enforced:

• Scheduling requires a scheduled_at timestamp
• Recipients can only be added or cleared while draft or scheduled
• Cancelling only works while scheduled, and returns the broadcast to draft
• Stopping only works while sending. Pending recipients stay pending and are not sent
• A draft or scheduled broadcast with a CSV upload or contact import still running rejects those changes with 422 until the import finishes
• A copying broadcast rejects them for the same reason, until its recipients have been copied

Add recipients

Two ways, and they produce the same result:

CSV upload

Upload a spreadsheet in the dashboard. No code.

Broadcasts API

Create and send programmatically.

The API accepts up to 1000 recipients per request. Send more by repeating the call.

Duplicate a broadcast

Duplicate an existing broadcast from the broadcast list or its details page. The copy keeps the template, template parameters, agent, and every recipient with their personalized values, and starts as a new draft with delivery state reset — no counts, timestamps, or per-recipient results are carried over.

Large recipient lists are copied in the background. The copy stays in copying until every recipient has been written, and cannot be edited, sent, or scheduled until then. If the copy cannot be completed it becomes failed rather than draft.

While a copy is being prepared, the source broadcast is also locked: it cannot be edited, sent, scheduled, or deleted until the copy finishes.

Metrics

Every broadcast exposes running counts:

Field	Meaning
total_recipients	Recipients on the list
pending_count	Not yet sent
sent_count	Accepted by WhatsApp
delivered_count	Reached the device
read_count	Opened by the recipient
failed_count	Rejected or undeliverable
suppressed_count	Skipped because the contact stopped marketing on this number
responded_count	Recipients who replied
response_rate	responded_count as a percentage of sent_count

Per-recipient status, timestamps, and error messages are available through List individual recipients.

Marketing opt-outs

A contact can tell WhatsApp to stop receiving marketing messages from one of your numbers. Kapso records that per number and enforces it on marketing template sends.

Recipients of a marketing broadcast who have stopped get the suppressed status. Nothing is sent to them, and they are not charged. They stay out of the sent_count and failed_count denominators, so delivery and failure rates describe only the messages you actually attempted.

The opt-out applies to marketing templates only. Utility and authentication templates, and free-form replies inside an open session, are unaffected. It is also scoped to the number the contact stopped: a broadcast from a different number reaches them normally.

Subscribe to whatsapp.contact.marketing_preference_changed to mirror these opt-outs into your own system, or check a contact before sending with the marketing preferences API. See Marketing opt-outs for the full behavior.

Delivery pacing

Kapso batches sends automatically and paces them to stay within WhatsApp’s throughput limits. Batch size scales with the size of the list, so you do not need to throttle your own requests or split large lists.