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.

Scopes: broadcasts:read to read, broadcasts:write to change.

Run a broadcast

Endpoints

List broadcastsGET /v1/broadcastsCreate a broadcastPOST /v1/broadcastsGet a broadcastGET /v1/broadcasts/{id}List a broadcast's recipientsGET /v1/broadcasts/{id}/recipientsCancel a broadcastPOST /v1/broadcasts/{id}/cancelResume a broadcastPOST /v1/broadcasts/{id}/resume

Webhook events

broadcast.statusBroadcast status changed

The broadcast object

One template sent to many people.

Attributes

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 object · nullable

The template it sends; null if the template was deleted.

Show 3 child attributesHide child attributes

template.id string · uuid

template.name string

template.language string

number_id string · uuid · nullable

The number it sends from; null if the number was removed.

send_at string · date-time · nullable

When a scheduled broadcast sends; null for one sent at once.

started_at string · date-time · nullable

completed_at string · date-time · nullable

paused_reason string · nullable

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.

Show 7 child attributesHide child attributes

counts.total integer

counts.sent integer

counts.delivered integer

counts.read integer

counts.failed integer

counts.replied integer

counts.clicked integer

skipped object

The customers left out, and why.

Show 3 child attributesHide child attributes

skipped.opted_out integer

Contacts who opted out of marketing messages (MARKETING templates only).

skipped.duplicate integer

A number already listed.

skipped.invalid_phone integer

created_by object

Who created the broadcast: a team member, an API key or another actor.

Show 3 child attributesHide child attributes

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

created_by.id string · uuid · nullable

The person, key or broadcast. null for actors without one, such as the chatbot.

created_by.name string

created_at string · date-time

The broadcast object

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