Skip to Content
RCS Panel APIBroadcasts

Broadcasts

A broadcast pairs one approved template with one contact list. On creation we snapshot every list member into rcs_broadcast_targets (state queued), then the runner picks the broadcast up when its status is running (immediate) or scheduled + the scheduled time has passed.

POST   /api/v1/rcs/broadcasts
GET    /api/v1/rcs/broadcasts
GET    /api/v1/rcs/broadcasts/{id}
POST   /api/v1/rcs/broadcasts/{id}/start
POST   /api/v1/rcs/broadcasts/{id}/cancel
GET    /api/v1/rcs/broadcasts/{id}/targets

Status lifecycle

draft  →  scheduled  →  running  →  completed
                              ↘    ↘
                              cancelled
                              failed
  • draft — created but not yet sendable. Call /start to flip it.
  • scheduled — scheduled_at is in the future; the runner will pick it up when the time arrives.
  • running — actively sending.
  • completed — every target has settled (sent or failed).
  • cancelled — you called /cancel. Already-sent targets are not refunded.
  • failed — the runner couldn’t proceed (no credentials, no balance for the first message, missing template).

Create

POST /api/v1/rcs/broadcasts
{
  "name":         "May launch announcement",
  "template_id":  "1f7a…",
  "list_id":      "a1b2…",
  "scheduled_at": "2026-05-28T08:00:00Z"
}

scheduled_at is optional. Omit it (or send a past timestamp) and the broadcast runs as soon as you call /start.

The template must be in effective_status = approved — otherwise the endpoint returns 403.

Response:

{
  "success":       true,
  "broadcast_id":  "b1b2…",
  "total_count":   18324,
  "status":        "draft",
  "template_name": "order_shipped",
  "list_name":     "May launch — opted in"
}

Start

POST /api/v1/rcs/broadcasts/{id}/start

Returns { "success": true, "status": "running" } (or scheduled if scheduled_at is still in the future).

Cancel

POST /api/v1/rcs/broadcasts/{id}/cancel

Refuses with 409 if the broadcast is already in a terminal state.

List + get

GET /api/v1/rcs/broadcasts
GET /api/v1/rcs/broadcasts/{id}

Each row carries the live counters:

{
  "broadcast_id":    "b1b2…",
  "name":            "May launch announcement",
  "status":          "running",
  "total_count":     18324,
  "sent_count":      8124,
  "delivered_count": 0,
  "read_count":      0,
  "failed_count":    12,
  "started_at":      "2026-05-28T08:00:01Z"
}

delivered_count and read_count stay at zero in v1 — delivery webhooks are wired into a follow-up release. sent_count updates in real time as the runner walks the list.

Targets

GET /api/v1/rcs/broadcasts/{id}/targets?size=200

Returns up to size recipient rows (default 200, max 1000):

{
  "success": true,
  "targets": [
    {
      "recipient_phone": "+919876543210",
      "state":           "sent",
      "rm_message_id":   "rm_AbCd12…",
      "failure_reason":  "",
      "sent_at":         "2026-05-28T08:00:02Z",
      "delivered_at":    "0001-01-01T00:00:00Z",
      "read_at":         "0001-01-01T00:00:00Z"
    }
  ]
}

state values: queued, sent, delivered, read, failed.

Contact listsInvoices