# Batch sends

> Docs index: https://wahasend.com/llms.txt · Everything in one file: https://wahasend.com/docs.md · API base URL: https://app.wahasend.com/api/v1

The same text to up to 500 people in one call. Comes with **Notify**, **Developer** and **Connect** (feature `batch`). For personalised texts and scheduling, use [campaigns](https://wahasend.com/docs/api/campaigns.md).

<a id="alert-batch"></a>

### Send one text to many

`POST /api/v1/alert/batch`

Checks every number on WhatsApp, skips the ones that aren't, and queues one message per remaining recipient.

- Unlocked by: Notify, Developer, Connect (`batch`)
- Per-number key: yes

> Sending the same text to many people who didn't ask for it is the fastest way to get a number banned. See [Good practice](https://wahasend.com/docs/good-practice.md).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `recipients` | string[] | yes | 1–500 phone numbers or `@lid` ids. |
| `message` | string | yes | 1–4096 characters. |
| `priority` | "high" \| "normal" \| "low" | no | Default `normal`. |
| `skipInvalidNumbers` | boolean | no | Default `true`: numbers not on WhatsApp are skipped and listed in `invalidNumbers`. `false`: if any number is not on WhatsApp, nothing is sent (`NUMBER_NOT_ON_WHATSAPP` with `details.invalidNumbers`). |
| `containerId` | uuid | no | Which of your WhatsApp numbers to use; it always wins. Default: your default number (else any connected one), or a number of the group when [several numbers](https://wahasend.com/docs/phone-numbers.md#several-numbers) is on. Ignored with a per-number key, which always uses its own number. |

**Example**

curl:

```bash
curl -X POST https://app.wahasend.com/api/v1/alert/batch \
  -H "X-API-Key: $WAHASEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    "+22212345678",
    "+22287654321"
  ],
  "message": "We are closed on Friday for the holiday."
}'
```

JavaScript:

```js
const res = await fetch('https://app.wahasend.com/api/v1/alert/batch', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.WAHASEND_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "recipients": [
      "+22212345678",
      "+22287654321"
    ],
    "message": "We are closed on Friday for the holiday."
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

r = requests.post(
    "https://app.wahasend.com/api/v1/alert/batch",
    headers={"X-API-Key": os.environ["WAHASEND_API_KEY"]},
    json={
        "recipients": [
            "+22212345678",
            "+22287654321",
        ],
        "message": "We are closed on Friday for the holiday.",
    },
)
print(r.json())
```

**Response 201**

```json
{
  "success": true,
  "count": 1,
  "messages": [
    {
      "phone": "22212345678",
      "messageId": "4f0c6a1e-2b7d-4c1a-9e35-7d8f2a6b1c90",
      "containerId": "6d2b9c1e-8f4a-4e37-a5c2-1b9e7d3f0a64"
    }
  ],
  "invalidNumbers": [
    "22287654321"
  ],
  "skipped": 1
}
```

**Errors to expect**

- [`VALIDATION_ERROR`](https://wahasend.com/docs/errors.md#validation_error) (400): Validation failed. Check the details for specific field errors.
- [`NO_VALID_NUMBERS`](https://wahasend.com/docs/errors.md#no_valid_numbers) (400): None of these numbers are on WhatsApp.
- [`NUMBER_NOT_ON_WHATSAPP`](https://wahasend.com/docs/errors.md#number_not_on_whatsapp) (400): This number is not on WhatsApp.
- [`NUMBER_VALIDATION_UNAVAILABLE`](https://wahasend.com/docs/errors.md#number_validation_unavailable) (503): Numbers cannot be checked right now. Try again shortly.
- [`NO_SESSION_CONFIGURED`](https://wahasend.com/docs/errors.md#no_session_configured) (400): This account has no connected WhatsApp number.