# Send a broadcast

`POST /api/bulk-send`  (operationId: `bulkSend`, group: Messaging)

Sends one message or template to many numbers as a campaign. Numbers that are blacklisted, opted out, or over the workspace’s frequency cap are skipped and counted in the response. The call answers 202 at once and the sending runs in the background, one recipient at a time with a delay between them; a broadcast can also be scheduled, or held for approval when the workspace requires it. Not held to the default per-key request limit; volume is governed by your credits and WhatsApp’s own limits.

Part of the core API, included in the Growth and Scale plans. Any one of these scopes is enough: `whatsapp_api`. The workspace must also have the WhatsApp Cloud API enabled.

**Request body** (JSON, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numbers` | array of string | yes | Recipient phone numbers. |
| `type` | string | no | Default text. One of: `text`, `template`, `image`, `video`, `document`. |
| `message` | string | no | The text or caption. |
| `template` | object | no | Template name, language and header, as for a single send. |
| `variableMapping` | object | no | Maps a template variable position to a contact field, for example {"1": "contact.name"}. |
| `mediaUrl` | string | no | Public URL of the media. Required for image, video and document. |
| `campaignName` | string | no | A name to find the campaign by. |
| `scheduledAt` | string (date-time) | no | Send later, at this time. |
| `senderId` | string | no | WhatsApp phone number id to send from. |
| `trackLinks` | boolean | no | Track clicks on links in the message. |
| `delayMs` | integer | no | Pause between recipients. Default 1000. Range 250..5000. |
| `enableRetry` | boolean | no | Retry a failed recipient. Default true. |
| `maxRetries` | integer | no | Retries per recipient. Default 2. Range 0..5. |

Example:

```json
{
  "numbers": [
    "919876543210",
    "919812345678"
  ],
  "type": "template",
  "template": {
    "name": "diwali_offer",
    "language": "en_US"
  },
  "campaignName": "Diwali offer",
  "variableMapping": {
    "1": "contact.name"
  }
}
```

**Response 200**: Accepted (202). status is processing, scheduled (with scheduledAt), or pending_approval.

Example:

```json
{
  "success": true,
  "status": "processing",
  "campaignId": 3812,
  "message": "Broadcast accepted and is executing in the background.",
  "totalRecipients": 2,
  "skippedOptOut": 0,
  "skippedBlacklist": 0
}
```

**Errors specific to this call.** The common ones (401, 403, 429 and the rest) are in the [Errors guide](https://inboxwa.online/docs/api/guide/errors.md).

| Status | error | When |
| --- | --- | --- |
| 400 | `Phone numbers array is required` | numbers is missing or empty. |
| 400 | `mediaUrl is required for media broadcasts` | An image, video or document broadcast without mediaUrl. |
| 400 | `All recipients are blacklisted, opted out, or over the frequency cap` | Nothing left to send. skippedOptOut, skippedBlacklist and skippedFrequencyCap say why. |
| 403 | `feature_disabled_for_org` | The WhatsApp Cloud API is switched off for the workspace. |

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json