---
title: "Broadcasts"
description: "Send one message to a segment, a list of numbers, or every customer."
url: "https://docs.goomzo.africa/docs/developers/messages/broadcasts"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Messages"
related:
  - /docs/developers/messages
  - /docs/developers/messages/send
  - /docs/developers/messages/templates
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Broadcasts

> Send one message to a segment, a list of numbers, or every customer.

A broadcast is one message sent to many people, filled in for each of them. Goomzo works out who it reaches when it
goes out, sends a message to each person, and counts how they did.

## Requirements

- An API key with the `broadcasts.send` permission.
- Enough SMS for everyone it reaches. For WhatsApp, your number connected and an approved template.

## Requests

```text
POST /v1/broadcasts
```

### Request syntax

```json
{
  "name": "<NAME>",
  "channel": "<CHANNEL>",
  "from": "<SENDER>",
  "content": { "text": "<TEXT>" },
  "template": { "id": "<WHATSAPP_TEMPLATE_ID>", "values": { "<KEY>": "<VALUE>" } },
  "audience": {
    "segments": [{ "name": "<SEGMENT>" }],
    "to": ["<PHONE_NUMBER>"],
    "everyone": <EVERYONE>
  },
  "sendAt": "<TIME>"
}
```

| Placeholder              | Description                                                                                    | Sample value                         |
| ------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------ |
| `<NAME>`                 | _String._ What you call it. Up to 100 characters.                                              | `Black Friday`                       |
| `<CHANNEL>`              | _String._ `sms` or `whatsapp`.                                                                 | `sms`                                |
| `<SENDER>`               | _String. Optional._ An SMS sender ID from `GET /v1/messaging/senders`.                         | `DUKA AMINA`                         |
| `<TEXT>`                 | _String._ SMS only. Can use `{{name}}` and `{{attributes.x}}`, with a fallback after `\|`.     | `Hi {{name\|there}}, 20% off today.` |
| `<WHATSAPP_TEMPLATE_ID>` | _String._ WhatsApp only. An approved template from `GET /v1/whatsapp/templates`.               | `wat_4hq2v9n1c8x0t6pk`               |
| `<KEY>`, `<VALUE>`       | _Object of strings._ A value for each of the template's parameters, filled in for each person. | `{ "body.1": "{{name\|there}}" }`    |
| `<SEGMENT>`              | _String._ A segment by `name`, or by `id`. Up to 20.                                           | `VIP`                                |
| `<PHONE_NUMBER>`         | _String._ A number with its country code. Up to 10,000.                                        | `+255712345678`                      |
| `<EVERYONE>`             | _Boolean._ `true` sends to every customer, in place of `segments` and `to`.                    | `true`                               |
| `<TIME>`                 | _String. Optional._ When to send it. Left out, now.                                            | `2026-11-28T06:00:00Z`               |

### Example request

```bash
curl https://api.goomzo.africa/v1/broadcasts \
  -H "Authorization: Bearer $GOOMZO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: black-friday-2026" \
  -d '{
    "name": "Black Friday",
    "channel": "sms",
    "content": { "text": "Hi {{name|there}}, 20% off everything today." },
    "audience": { "segments": [{ "name": "VIP" }], "to": ["+255787654321"] }
  }'
```

## Responses

The answer is `201` with the broadcast, scheduled. Its `audience` says who it goes to, in words such as
`"VIP and 1 number"`.

**Important:** `audience` is required. Leaving it out is an error, never a send to everyone.

## Notes

- **Once each:** each person gets it once, however often they're named.
- **Checked first:** every number and segment is checked before anything is saved, and a bad one is named, such as
  `audience.to[1]` or `audience.segments[0]`.
- **Measured as filled in:** each text is priced as it reads for that person, so a long name can't push one past
  6 SMS.
- **Worked out again when it goes:** people added to a segment meanwhile get it. If a segment it names was deleted,
  it doesn't go, and `error` says why.
- **Placeholders:** `{{data.x}}` and `{{secret.x}}` can't be used, since a broadcast has no request to fill them.
- **Cancel:** `POST /v1/broadcasts/{id}/cancel` stops one that hasn't gone out.
- **Finished:** the `broadcast.finished` [webhook](https://docs.goomzo.africa/docs/developers/webhooks/events?utm_source=llms&utm_medium=ai) carries its counts.

## Next steps

- [Segments](https://docs.goomzo.africa/docs/help/segments?utm_source=llms&utm_medium=ai)
- [WhatsApp templates](https://docs.goomzo.africa/docs/developers/templates?utm_source=llms&utm_medium=ai)
- [Webhook events](https://docs.goomzo.africa/docs/developers/webhooks/events?utm_source=llms&utm_medium=ai)

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)