Sign up

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

POST /v1/broadcasts

Request syntax

{
  "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>"
}
PlaceholderDescriptionSample 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

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 carries its counts.

Next steps

Last updated