Ricky logorickyDocs

Create a broadcast

POST
/broadcasts

Sends an approved WhatsApp template to an audience, now or at scheduled_at. Ricky fixes the recipient list now and sends through each number’s conversation, as a template sent from the inbox; variables the template maps to contact fields in Ricky are filled per contact. Answers 201 with the broadcast queued or scheduled; follow it with GET /broadcasts/{broadcast_id}. An audience without any WhatsApp number answers 422 rule_violation.

Scope: broadcasts:write.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An organization API key, rky_live_…, created in Settings → API. Send it only from a server.

Header Parameters

Idempotency-Key?string

Optional. A value you choose, unique per logical write, 8–200 characters: a UUID or an ID from your system such as order-10482-ready. Retrying with the same key and body replays the first response instead of repeating the write.

Length8 <= length <= 200

Request Body

application/json
  1. body

Sends an approved template to many numbers, now or at a set time.

channel_id*string

WhatsApp channel to send from. See GET /channels.

Formatuuid
template*

An approved WhatsApp template and the values of its variables.

audience*||

Who receives it. filter takes every contact matching all the filters you send (no filter: every contact); contacts and phones take the ones you list. Ricky uses each contact’s phone, or its WhatsApp number, skips contacts without one and sends once per number, up to 5,000.

mappings?array<>

Fills template variables per recipient from their contact, as the broadcast composer does. Ricky saves them on the template, replacing the ones it had, so later broadcasts of the template use them too; omit it to keep the saved ones, send [] to clear them. A recipient without a contact, or without a value in the field, receives the text you sent in template.components.

Itemsitems <= 100
scheduled_at?string

When to start sending, up to 7 days ahead. Omit it to send now.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
Formatdate-time

Response Body

Success.

application/json
  1. response
data*

One approved WhatsApp template sent to many numbers.

curl -X POST 'https://getricky.ai/api/v1/broadcasts' \  -H 'Idempotency-Key: order-10482-ready' \  -H 'Content-Type: application/json' \  -d '{  "channel_id": "8f3c2a5e-6b1d-4c7a-9e2f-1a2b3c4d5e6f",  "template": {    "id": "1234567890123456",    "components": [      {        "type": "body",        "parameters": [          {            "type": "text",            "text": "20%"          }        ]      }    ]  },  "audience": {    "type": "filter",    "tag_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"  },  "scheduled_at": "2026-10-20T14:00:00Z"}'
{  "data": {    "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",    "channel_id": "8f3c2a5e-6b1d-4c7a-9e2f-1a2b3c4d5e6f",    "template": {      "id": "1234567890123456",      "name": "promo_octubre",      "language": "es"    },    "audience": {      "type": "filter",      "tag_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",      "lifecycle_stage": null,      "query": null    },    "status": "completed",    "counts": {      "recipients": 120,      "pending": 0,      "sent": 14,      "delivered": 61,      "read": 41,      "failed": 4    },    "scheduled_at": "2026-10-14T14:00:00.000Z",    "canceled_at": null,    "completed_at": "2026-10-14T14:03:12.000Z",    "created_by_user_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",    "created_at": "2026-10-14T15:30:00.000Z"  }}