WasaasPlatform
Sign inGet your API key

Bulk messaging

WhatsApp Bulk Messaging API

One POST sends the same message to up to 500 recipients. The server walks the list sequentially with a randomised pause between each send, then returns a sent/failed result for every recipient — so you get a per-contact outcome rather than a single opaque success.

Endpoint

http
POST https://wasaas.org/api/v1/messages/bulk
Authorization: Bearer wsa_your_api_key
Content-Type: application/json

Authentication is the same API key used everywhere else in the API. An unknown or malformed key returns 401.

Request fields

FieldTypeRequiredNotes
session_idstringYesA connected WhatsApp session belonging to your account. Unknown session → 404.
recipientsstring[]Yes1–500 numbers in international format, no leading +. Empty strings are rejected.
messagestringYesThe text body. Bulk sends are text only — no images or documents.
min_delayintegerNoSeconds, 1–300. Defaults to 3.
max_delayintegerNoSeconds, 1–300. Defaults to 8. Must be ≥ min_delay, or the call returns 400.
bash
curl -X POST https://wasaas.org/api/v1/messages/bulk \
  -H "Authorization: Bearer wsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "customer-5-1",
    "recipients": ["966501234567", "966502345678", "201012345678"],
    "message": "Our new collection is live.",
    "min_delay": 3,
    "max_delay": 8
  }'

Pacing

Messages go out one after another, and between each pair the server sleeps a random number of seconds drawn from your min_delay–max_delay window. There is no pause after the final message. Randomised spacing is there because identical, evenly-spaced bursts are the pattern WhatsApp's automated enforcement looks for.

Batch size is bounded by time, not just by the 500 limit

The request is synchronous and the route has a 300-second execution budget. With the default 3–8s pacing, a batch averages about 5.5s per recipient, so roughly 55 recipients fit inside that window — well under the schema's 500.

To reach the full 500 in one call you would need min_delay and max_delay near 1s, which increases ban risk. The safer pattern is to chunk your list and issue several calls from a queue or scheduler.

Response

You get counts plus the full per-recipient breakdown, in the order the recipients were sent.

json
{
  "sent": 2,
  "failed": 1,
  "results": [
    { "to": "966501234567", "status": "sent" },
    { "to": "966502345678", "status": "sent" },
    { "to": "201012345678", "status": "failed", "error": "Message quota exceeded" }
  ]
}

Delivery is not guaranteed: status: "sent" means the message was accepted for sending by the connected WhatsApp session, not that it was received or read. Every send — successful or not — is written to your message log with its status and error.

Quota behaviour

A bulk request counts as one API call against your plan's API-call allowance, and each recipient counts as one message against your monthly message allowance.

The message quota is re-checked before every individual send. If it runs out part-way through, the run stops there and the current plus all remaining recipients come back as failed with "Message quota exceeded" — so you can see exactly where it stopped and resume from that point. WhatsApp API pricing lists each plan's monthly message allowance.

Errors

FieldTypeRequiredNotes
401Invalid API keyNoKey missing, malformed, or not linked to an active subscription.
400Invalid inputNoSchema violation — includes a details object. Also returned when min_delay > max_delay.
404Session not foundNoThe session_id does not belong to your account.

What it suits

Bulk sending fits announcements to a list that asked to hear from you: a restock notice, an event invitation, a seasonal offer, a service-status update. It is a poor fit for cold outreach — recipient reports are what drive number bans, and no amount of pacing offsets messaging people who never opted in.

The practical guidance on warm-up, opt-in and list hygiene is in WhatsApp bulk messaging without bans.

Where to go next

WhatsApp Bulk Messaging API | Wasaas