Docs / API Reference / Broadcasts

Broadcasts

Send template campaigns to cohorts of contacts at scale, and track delivery, read, and failure metrics for every send.

POST /v1/broadcasts

Create broadcast

Create a broadcast that sends an approved template to every contact in a cohort.

Parameters

name string required

Broadcast name. Max 255 characters.

inbox_id string

Inbox (WhatsApp number) to send from.

cohort_id string required

Cohort of contacts to send to.

template_id string required

Approved message template to send.

variable_mapping object

Maps template variables to contact attributes for per-recipient substitution.

scheduled_at string

ISO 8601 timestamp to schedule the send. Max 30 days in the future. Omit to create a draft.

Request

cURL

curl -X POST https://api.boltly.online/v1/broadcasts \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring sale announcement",
    "inbox_id": "inb_01H...",
    "cohort_id": "coh_01H...",
    "template_id": "tpl_01H...",
    "scheduled_at": "2026-04-10T09:00:00Z"
  }'

Response

JSON

{
  "data": {
    "id": "bc_01H...",
    "organization_id": "org_01H...",
    "inbox_id": "inb_01H...",
    "name": "Spring sale announcement",
    "cohort_id": "coh_01H...",
    "template_id": "tpl_01H...",
    "scheduled_at": "2026-04-10T09:00:00Z",
    "execution_status": "scheduled",
    "recipient_count": 0,
    "stats": { "total": 0, "sent": 0, "delivered": 0, "read": 0, "failed": 0 },
    "created_at": "2026-04-03T12:00:00Z",
    "updated_at": "2026-04-03T12:00:00Z"
  }
}

POST /v1/broadcasts/{id}/execute

Execute broadcast

Start sending a draft or scheduled broadcast immediately.

Parameters

id string required

Broadcast ID.

Request

cURL

curl -X POST https://api.boltly.online/v1/broadcasts/bc_01H.../execute \
  -H "X-API-Key: $API_KEY"

Response

JSON

{
  "data": {
    "id": "bc_01H...",
    "name": "Spring sale announcement",
    "cohort_id": "coh_01H...",
    "template_id": "tpl_01H...",
    "execution_status": "processing",
    "recipient_count": 1250,
    "stats": { "total": 1250, "sent": 0, "delivered": 0, "read": 0, "failed": 0 },
    "created_at": "2026-04-03T12:00:00Z",
    "updated_at": "2026-04-03T12:10:00Z"
  }
}

GET /v1/broadcasts/{id}/metrics

Get metrics

Retrieve delivery metrics for a broadcast, updated as WhatsApp delivery receipts arrive.

Parameters

id string required

Broadcast ID.

Request

cURL

curl https://api.boltly.online/v1/broadcasts/bc_01H.../metrics \
  -H "X-API-Key: $API_KEY"

Response

JSON

{
  "data": {
    "total": 1250,
    "sent": 1180,
    "delivered": 1100,
    "read": 640,
    "failed": 20,
    "pending": 50
  }
}

Conversations Templates