…
WhatsApp Connection
0
Messages in Queue
5–9s
Anti-Ban Gap
—
Your API Key Role
WhatsApp Connection
Starting WhatsApp session…
Hold on, preparing your QR code.
Send a Test Message
Message Queue & History
auto-refreshes every 4s
Queued messages drain one-by-one with a random 5–9s gap + typing simulation (anti-ban). Top of the queued list sends next.
Fire-and-forget: the server only sends — it does not track delivered/seen receipts.
| # | Type | Recipient | Message | Status | Time |
|---|---|---|---|---|---|
| Loading… | |||||
Domain API use with SSL
VPS IP API direct access
Authentication & Response Format
Authentication — every request
| Header | Example |
|---|---|
X-API-Key | X-API-Key: wapi_xxxxxxxx_yyyyyyyy |
Authorization (alternative) | Authorization: Bearer wapi_xxxxxxxx_yyyyyyyy |
Every response has the same JSON shape
{
"success": true, // false on any error
"data": { ... }, // the result payload
"error": "", // human-readable error message
"code": "" // machine error code, e.g. RATE_LIMITED
} Recipient format
Digits with country code, no + — e.g. 5511999999999. Group JIDs ending in @g.us also work.
Anti-Ban Queue — how sending works
Messages are never blasted out together. Protection layers, all automatic:
one message at a time with a fresh random 5–9s gap · brief "typing…" simulation before each send ·
a 30–60s cool-down after every 20 messages · a daily send limit (default 500/day, configurable) ·
numbers are verified on WhatsApp before sending. Fire as many API requests as you like; they queue automatically.
Response status | Meaning |
|---|---|
sent | Message went out while your HTTP request was waiting (within ~15s). Fire-and-forget — delivery/seen receipts are not tracked. |
queued | Accepted & in the queue — it WILL send when its turn comes. No action needed. Track via GET /api/status → pendingMessages. |
failed | Send failed (e.g. WhatsApp disconnected mid-queue, or number not on WhatsApp). |
Code Examples — send a text message
Google Sheets / Apps Script? A full drop-in client (
WhatsAppApi.gs) with a Sheets bulk-send menu
ships in the repo under clients/apps-script/.
All Endpoints
Errors & Rate Limits
| HTTP | Code | When |
|---|---|---|
| 400 / 422 | VALIDATION_ERROR | Bad body — check details in the response |
| 401 | UNAUTHORIZED | Missing / invalid / revoked API key |
| 403 | ADMIN_REQUIRED | Endpoint needs an admin-role key |
| 404 | RECIPIENT_NOT_FOUND | Number is not registered on WhatsApp (checked before every send) |
| 413 | UPLOAD_ERROR | Media file too large (default limit 25 MB) |
| 429 | RATE_LIMITED | Too many requests — default 120 per key per 15 min (HTTP level; the send queue is separate) |
| 429 | DAILY_LIMIT_REACHED | Anti-ban daily cap hit (default 500/day, DAILY_SEND_LIMIT in .env) — resets midnight UTC |
| 503 | WHATSAPP_NOT_CONNECTED | Session not linked — open the dashboard and scan the QR |
On
429, respect the retry-after response header. The anti-ban queue means the HTTP rate
limit is rarely the bottleneck — queued messages drain at one per 5–9s regardless of how fast you call the API.
API Keys use these in your apps
••••••
| Name | Prefix | Role | Last used | Status |
|---|