> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`      |
| `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

## Add recipients

Two ways, and they produce the same result:

<CardGroup cols={2}>
  <Card title="CSV upload" icon="file-csv" href="/docs/platform/broadcasts/csv-upload">
    Upload a spreadsheet in the dashboard. No code.
  </Card>

  <Card title="Broadcasts API" icon="code" href="/docs/platform/broadcasts/api">
    Create and send programmatically.
  </Card>
</CardGroup>

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

## 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                         |
| `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](/docs/platform/broadcasts/api#list-individual-recipients).

## 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.