# Broadcasts

A broadcast is one template sent to many people, now or at a time you choose. The app calls a broadcast a campaign. Create one, then follow it to the end.

## Endpoints

- [List broadcasts](https://docs.soosh.io/reference/api/broadcasts/list-broadcasts/): `GET /v1/broadcasts`
- [Create a broadcast](https://docs.soosh.io/reference/api/broadcasts/create-broadcast/): `POST /v1/broadcasts`
- [Get a broadcast](https://docs.soosh.io/reference/api/broadcasts/get-broadcast/): `GET /v1/broadcasts/{id}`
- [List a broadcast's recipients](https://docs.soosh.io/reference/api/broadcasts/list-broadcast-recipients/): `GET /v1/broadcasts/{id}/recipients`
- [Cancel a broadcast](https://docs.soosh.io/reference/api/broadcasts/cancel-broadcast/): `POST /v1/broadcasts/{id}/cancel`
- [Resume a broadcast](https://docs.soosh.io/reference/api/broadcasts/resume-broadcast/): `POST /v1/broadcasts/{id}/resume`

## Webhook events

- [`broadcast.status`](https://docs.soosh.io/reference/api/webhook-events/broadcast-status/): A broadcast's status changes, starting when it is created.

## The Broadcast object

- `id` (string, uuid)
- `name` (string)
- `status` (string): `preparing`: its audience is being collected. `scheduled`: waiting for `send_at`. `queued`: about to send. `processing`: sending. `paused`: stopped, by a person or for `paused_reason`. `missed`: it couldn't start at its time. More values may be added. One of `preparing`, `scheduled`, `queued`, `processing`, `paused`, `completed`, `cancelled`, `failed`, `missed`.
- `template` (nullable object): The template it sends; `null` if the template was deleted.
  - `id` (string, uuid)
  - `name` (string)
  - `language` (string)
- `number_id` (nullable string, uuid): The number it sends from; `null` if the number was removed.
- `send_at` (nullable string, date-time): When a scheduled broadcast sends; `null` for one sent at once.
- `started_at` (nullable string, date-time)
- `completed_at` (nullable string, date-time)
- `paused_reason` (nullable string): Why it stopped, in plain words for people, such as the monthly limit.
- `counts` (object): What happened to its messages so far. `replied` and `clicked` count recipients who replied, or tapped a quick-reply button, after its message.
  - `total` (integer)
  - `sent` (integer)
  - `delivered` (integer)
  - `read` (integer)
  - `failed` (integer)
  - `replied` (integer)
  - `clicked` (integer)
- `skipped` (object): The customers left out, and why.
  - `opted_out` (integer): Contacts who opted out of marketing messages (MARKETING templates only).
  - `duplicate` (integer): A number already listed.
  - `invalid_phone` (integer)
- `created_by` (object): Who created the broadcast: a team member, an API key or another actor.
  - `type` (string): Who or what it was: a team member, an API key, the chatbot, the AI, an automation, a broadcast, the WhatsApp Business app or Soosh itself. More values may be added. One of `user`, `api_key`, `bot`, `ai`, `automation`, `broadcast`, `whatsapp_app`, `system`.
  - `id` (nullable string, uuid): The person, key or broadcast. `null` for actors without one, such as the chatbot.
  - `name` (string)
- `created_at` (string, date-time)

```json
{
  "id": "2e4a6c8e-0b1d-4f3a-a5c7-9e1b3d5f7a2c",
  "name": "Diwali offer",
  "status": "completed",
  "template": {
    "id": "8d2f4c1e-7a3b-4e59-b0c6-1f2e3d4c5b6a",
    "name": "diwali_offer",
    "language": "en"
  },
  "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
  "send_at": null,
  "started_at": "2026-10-14T09:31:40.912Z",
  "completed_at": "2026-10-14T09:33:08.774Z",
  "paused_reason": null,
  "counts": {
    "total": 250,
    "sent": 247,
    "delivered": 244,
    "read": 171,
    "failed": 3,
    "replied": 21,
    "clicked": 14
  },
  "skipped": {
    "opted_out": 6,
    "duplicate": 2,
    "invalid_phone": 1
  },
  "created_by": {
    "type": "api_key",
    "id": "5e1d2c3b-4a59-4f68-8e7d-6c5b4a392817",
    "name": "Order system"
  },
  "created_at": "2026-10-14T09:31:40.552Z"
}
```