WhatsApp API

WhatsApp Multi-Session API — Public Reference

This file is the single source of truth for the public API. public/api-docs.html is generated from it — never edit the HTML by hand (see INTERNAL.md).

Companion documents:

Table of contents

1. Quickstart — first message in five minutes
2. How to read a response
3. Two API generations: v1 and v2
4. Sending
5. Media
6. Interaction
7. Reading
8. Groups
9. Queue and limits
10. Status and health
11. Webhooks
12. Error codes
13. Limits, sizes and timeouts
14. Current release status and known gaps

1. Quickstart — first message in five minutes

Step 1 — get your API key

Your API key is issued per WhatsApp instance by your operator in the admin panel. It looks like wapi_<NAME>_<random>. Keep it secret; it is the only credential.

export WA_URL="https://wa.outrnk.io"
export WA_API_KEY="wapi_yourinstance_xxxxxxxxxxxx"     # never commit this

Step 2 — check that your instance is connected

curl -s "$WA_URL/api/status" -H "Authorization: Bearer $WA_API_KEY"

{ "success": true, "data": { "status": "connected", "connected": true, "phoneNumber": "49…" } }

If connected is false, scan the QR code first:

curl -s "$WA_URL/api/qr" -H "Authorization: Bearer $WA_API_KEY"

The response contains data.qr as a data-URL PNG. Open it, scan it with the WhatsApp app (Linked devices → Link a device). The instance stays linked across restarts.

Step 3 — check the recipient is on WhatsApp

curl -s "$WA_URL/api/check-number/4915212345678" -H "Authorization: Bearer $WA_API_KEY"

Step 4 — send your first message

curl -s -X POST "$WA_URL/api/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"4915212345678","message":"Hello from the API"}'

{ "success": true, "data": { "messageId": "true_49152…@c.us_3EB0…", "phone": "4915212345678", "status": "sent" } }

That is the whole minimum. Everything below is optional.

Step 5 (recommended) — switch to v2 and use an idempotency key

curl -s -X POST "$WA_URL/api/v2/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "X-Idempotency-Key: order-4711-confirmation" \
  -H "Content-Type: application/json" \
  -d '{"phone":"4915212345678","message":"Your order 4711 is on its way."}'

{
  "success": true,
  "data": {
    "status": "queued",
    "queueState": "scheduled",
    "jobId": "wq_9f2c1b7e4a0d4c8e",
    "scheduledAt": "2026-09-05T21:15:33.412Z",
    "etaSeconds": 42,
    "queuePosition": 7,
    "statusUrl": "/api/v2/messages/wq_9f2c1b7e4a0d4c8e"
  }
}

Read this once. Without X-Idempotency-Key there is no duplicate protection. If your request times out on the network you cannot tell "never arrived" from "arrived, answer lost" — retrying may send the message twice. With the key, retrying the exact same request is always safe: you get the original job back with idempotentReplay: true.

Poll the result:

curl -s "$WA_URL/api/v2/messages/wq_9f2c1b7e4a0d4c8e" -H "Authorization: Bearer $WA_API_KEY"

2. How to read a response

Every JSON response uses the same envelope.

Success

{ "success": true, "data": { } }

Error

{ "success": false, "error": "human readable text", "code": "MACHINE_CODE", "data": { } }

Rules that matter in practice:

3. Two API generations: v1 and v2

v1 is not deprecated and its response shape is frozen. Existing integrations keep working byte for byte. Everything new should use v2.

The only way v1 can behave differently than before: if your operator enables an hourly or daily limit and the queue cannot dispatch your message within 20 seconds, POST /api/send-message answers 504 QUEUE_WAIT_TIMEOUT. The message is not lost — it stays in the queue and goes out later. The response body then contains the jobId so you can follow it. See QUEUE.md.

4. Sending

4.1 Common request fields (all v2 send routes)

Exactly one of phone or chatId is required.

options whitelist (anything else is silently dropped):

sendAudioAsVoice, sendMediaAsDocument, sendMediaAsSticker, sendVideoAsGif, stickerName, stickerAuthor, stickerCategories are set automatically by the matching route — you do not need to pass them.

4.2 Common success response (all v2 send routes)

HTTP 202 Accepted (or 200 on idempotent replay):

{
  "success": true,
  "data": {
    "status": "queued",
    "queueState": "scheduled",
    "jobId": "wq_9f2c1b7e4a0d4c8e",
    "messageId": null,
    "idempotencyKey": "order-4711",
    "idempotentReplay": false,
    "scheduledAt": "2026-09-05T21:15:33.412Z",
    "etaSeconds": 42,
    "queuePosition": 7,
    "expiresAt": "2026-09-06T21:15:33.412Z",
    "statusUrl": "/api/v2/messages/wq_9f2c1b7e4a0d4c8e",
    "limits": {
      "maxPerHour": 40, "maxPer24h": 500,
      "usedLastHour": 12, "usedLast24h": 88,
      "remainingHour": 28, "remaining24h": 412,
      "minDelayMs": 4000, "maxDelayMs": 12000,
      "quietHours": { "start": "22:00", "end": "07:00", "tz": "Europe/Berlin" },
      "window": "sliding"
    }
  }
}

status is the field to branch on. A fresh submission is always queued.

queueState is a second, informational field carrying the queue's internal planning stage: queued (no slot assigned yet) or scheduled (slot assigned). It is deliberately kept out of status because the distinction is a planning detail, not a business outcome — in both cases the message is accepted and not yet out, and scheduledAt / etaSeconds already answer when. status never carries the value scheduled. Terminal states are not flattened: a replay of an already delivered job reports status: "sent", not queued.

A fresh submission is therefore always 202 + queued/scheduled; 200 always means replay.

Some routes add warnings: ["…"] — a non-fatal note (e.g. non-OGG audio).

4.3 POST /api/send-message — text (v1, synchronous)

curl -s -X POST "$WA_URL/api/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"4915212345678","message":"Hello"}'

Body: phone or chatId, plus message (string, required).

4.4 POST /api/v2/send-message — text

curl -s -X POST "$WA_URL/api/v2/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "X-Idempotency-Key: welcome-user-9912" \
  -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "message": "Welcome! Reply STOP to opt out.",
        "priority": 5,
        "options": { "linkPreview": false }
      }'

Errors: 400 VALIDATION_FAILED, 409 IDEMPOTENCY_PAYLOAD_MISMATCH, 422 QUEUE_FULL, 422 TTL_UNREACHABLE, 503 INSTANCE_OFFLINE, 503 QUEUE_STORE_UNAVAILABLE, 503 QUEUE_PAUSED.

4.5 POST /api/send-media — image / document (v1, synchronous)

curl -s -X POST "$WA_URL/api/send-media" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "mediaUrl": "https://example.com/invoice.pdf",
        "filename": "invoice.pdf",
        "caption": "Your invoice"
      }'

Body: phone or chatId, plus either mediaUrl or mediaBase64 (+ mimetype). Optional: filename, caption (message is accepted as an alias for caption).

Response is identical to /api/send-message plus "type":"media" in data.

mediaUrl is validated against SSRF: only public HTTP/HTTPS targets, redirects re-checked on every hop, hard size ceiling of 16 MiB.

4.6 POST /api/v2/send-media — image / document / any file

curl -s -X POST "$WA_URL/api/v2/send-media" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "chatId": "4915212345678@c.us",
        "mediaUrl": "https://example.com/photo.jpg",
        "caption": "Here you go",
        "options": { "sendMediaAsHd": true }
      }'

4.7 POST /api/v2/send-voice — voice message (PTT)

curl -s -X POST "$WA_URL/api/v2/send-voice" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "mediaUrl": "https://example.com/note.ogg",
        "mimetype": "audio/ogg; codecs=opus"
      }'

mimetype is required. Accepted: audio/ogg, audio/ogg;codecs=opus, audio/opus, audio/mpeg, audio/mp3, audio/mp4, audio/aac, audio/amr, audio/wav, audio/x-wav, audio/webm. Anything else (including video/*) → 400 VOICE_MIMETYPE_UNSUPPORTED.

We do not transcode. For a guaranteed push-to-talk bubble on every client, send OGG/Opus. Any other accepted format still goes out, but the response contains warnings: ["non-ogg audio may not render as PTT on all clients"] — on some clients it will show up as a normal audio file.

4.8 POST /api/v2/send-document — file with a filename

curl -s -X POST "$WA_URL/api/v2/send-document" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "mediaId": "md_1f2e3d4c5b6a79880011223344556677",
        "filename": "contract-2026.pdf",
        "caption": "Please sign"
      }'

filename is required here (400 VALIDATION_FAILED otherwise).

4.9 POST /api/v2/send-sticker — sticker

curl -s -X POST "$WA_URL/api/v2/send-sticker" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "mediaUrl": "https://example.com/logo.png",
        "mimetype": "image/png",
        "stickerName": "Brand",
        "stickerAuthor": "Acme"
      }'

Image → sticker conversion happens inside the browser and works.

4.10 POST /api/v2/send-video — video or GIF

curl -s -X POST "$WA_URL/api/v2/send-video" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"4915212345678","mediaUrl":"https://example.com/clip.mp4","asGif":true,"caption":"look"}'

asGif: true makes WhatsApp render it as a looping GIF.

4.11 POST /api/v2/send-location — location pin

curl -s -X POST "$WA_URL/api/v2/send-location" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "phone": "4915212345678",
        "latitude": 48.137154, "longitude": 11.576124,
        "name": "Marienplatz", "address": "80331 Munich", "url": "https://example.com"
      }'

latitude (−90…90) and longitude (−180…180) are required. name, address, url, description are optional.

4.12 POST /api/v2/send-contact — contact card(s)

curl -s -X POST "$WA_URL/api/v2/send-contact" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"4915212345678","contactIds":["4915299999999@c.us"]}'

contactIds must be a non-empty array of WhatsApp ids. One entry sends a single contact card, several entries send a contact list. The ids must be known to the linked account.

4.13 POST /api/v2/send-poll — poll

curl -s -X POST "$WA_URL/api/v2/send-poll" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "chatId": "49152123456789-1600000000@g.us",
        "name": "Lunch on Friday?",
        "options": ["Italian", "Sushi", "Döner"],
        "allowMultipleAnswers": false
      }'

options must contain 2–12 entries; outside that range WhatsApp silently drops the poll, so we reject it with 400 VALIDATION_FAILED.

Vote results arrive through the vote_update webhook event.

4.14 POST /api/v2/messages/:msgId/forward — forward a message

curl -s -X POST "$WA_URL/api/v2/messages/true_49152%40c.us_3EB0.../forward" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"toChatId":"4915299999999@c.us"}'

:msgId is a WhatsApp message id (not a wq_… job id). toChatId is required. Because WhatsApp does not return an id for forwarded messages, the resulting job ends as sent with deliveryConfidence: "assumed" and a synthetic messageId of the form fwd_<ts>.

4.15 POST /api/send-bulk — many texts in one call (v1, asynchronous)

curl -s -X POST "$WA_URL/api/send-bulk" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[
        {"phone":"4915212345678","message":"Hi A"},
        {"phone":"4915299999999","message":"Hi B"}
      ]}'

There is no fixed cap on the number of entries — this is one of the six frozen routes and a cap would have rejected batches that work today. The real bounds are the 10 MB JSON body and QUEUE_MAX_PENDING (5000 pending jobs per instance); entries beyond that come back individually as rejected instead of taking the batch down with them.

This route has always been asynchronous; it now returns jobId, scheduledAt and etaSeconds per entry in addition to the existing fields:

{
  "success": true,
  "data": {
    "queued": 2,
    "messages": [
      { "phone": "4915212345678", "status": "queued", "jobId": "wq_…", "scheduledAt": "…", "etaSeconds": 3 },
      { "phone": "4915299999999", "status": "queued", "jobId": "wq_…", "scheduledAt": "…", "etaSeconds": 9 }
    ]
  }
}

A single rejected entry does not abort the batch — it comes back as {"phone":"…","status":"rejected","error":"…"}. Note that data.queued is the length of the messages array, not the number of accepted entries: count status === "queued" yourself if you need the accepted count.

5. Media

There are three ways to hand media over. Pick exactly one per request.

Infrastructure caveat. The reverse proxy in front of this API currently has no client_max_body_size override, so nginx's default of 1 MB applies to request bodies. In practice that caps mediaBase64 at roughly 750 KB of binary and blocks large uploads with an nginx-generated 413 that never reaches our code. Until your operator sets client_max_body_size 32m;, prefer mediaUrl for anything above ~700 KB.

5.1 mediaUrl — SSRF rules

The URL is validated twice: once when the request is accepted, and again at the moment the message is actually dispatched (which may be hours later, and DNS can change in between).

Rejected with 400 VALIDATION_FAILED: private/loopback/link-local addresses, non-HTTP schemes, redirects to a non-public target, more than 3 redirect hops, Content-Length above 16 MiB.

5.2 POST /api/v2/media — upload

curl -s -X POST "$WA_URL/api/v2/media" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -F "file=@./contract.pdf" \
  -F "filename=contract-2026.pdf" \
  -F "mimetype=application/pdf"

HTTP 201:

{
  "success": true,
  "data": {
    "stored": true,
    "mediaId": "md_1f2e3d4c5b6a79880011223344556677",
    "url": "/api/v2/media/md_1f2e3d4c5b6a79880011223344556677",
    "expiresAt": "2026-09-08T18:00:00.000Z",
    "size": 184320
  }
}

Use mediaId in any send route for the next 72 hours.

5.3 GET /api/v2/media/:mediaId — metadata or bytes

# metadata
curl -s "$WA_URL/api/v2/media/md_1f2e…" -H "Authorization: Bearer $WA_API_KEY"

# bytes
curl -s "$WA_URL/api/v2/media/md_1f2e…?download=1" -H "Authorization: Bearer $WA_API_KEY" -o file.pdf

With ?download=1 the response is the raw file with Content-Type, Content-Length, Content-Disposition and Cache-Control: private, max-age=300.

404 MEDIA_NOT_FOUND if the id is unknown, deleted or expired. 410 MEDIA_GONE if the index still knows it but the file is gone from disk.

5.4 DELETE /api/v2/media/:mediaId

curl -s -X DELETE "$WA_URL/api/v2/media/md_1f2e…" -H "Authorization: Bearer $WA_API_KEY"

5.5 GET /api/v2/messages/:msgId/media — download incoming media

# metadata (+ store it if the instance has storeIncomingMedia enabled)
curl -s "$WA_URL/api/v2/messages/true_…%40c.us_3EB0…/media" -H "Authorization: Bearer $WA_API_KEY"

# raw bytes
curl -s "$WA_URL/api/v2/messages/true_…/media?download=1" -H "Authorization: Bearer $WA_API_KEY" -o incoming.jpg

Without ?download=1 you get {mimetype, filename, size, stored, mediaId?, url?, expiresAt?}. stored is false with reason: "store_disabled" unless your operator enabled incoming media storage for the instance.

404 NO_MEDIA if the message has no attachment.

6. Interaction

These endpoints do not produce a visible message, therefore they are not subject to the hourly/daily send limits. They have their own limiter: 60 calls per 60 seconds per instance, exceeding it returns 429 RATE_LIMITED.

All of them return {"success":true,"data":{…}} on success and 503 INSTANCE_OFFLINE when the WhatsApp client is not connected.

# react
curl -s -X POST "$WA_URL/api/v2/messages/true_…/reaction" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"emoji":"👍"}'

# typing indicator for 60 s (WhatsApp only holds ~25 s, we re-fire automatically)
curl -s -X POST "$WA_URL/api/v2/chats/4915212345678@c.us/typing" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"durationMs":60000}'

# delete for everyone
curl -s -X DELETE "$WA_URL/api/v2/messages/true_…" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"everyone":true}'

durationMs is capped at 300000 (5 min). Values above 25000 are kept alive by re-firing the state every 20 s until the duration is over or the client disconnects.

7. Reading

curl -s "$WA_URL/api/v2/chats?limit=20" -H "Authorization: Bearer $WA_API_KEY"
curl -s "$WA_URL/api/v2/chats/4915212345678@c.us/messages?limit=50" -H "Authorization: Bearer $WA_API_KEY"
curl -s "$WA_URL/api/v2/contacts/4915212345678/exists" -H "Authorization: Bearer $WA_API_KEY"

Chat object

{ "id":"4915212345678@c.us", "name":"Jane", "isGroup":false, "isReadOnly":false,
  "unreadCount":2, "timestamp":1757012345, "archived":false, "pinned":false,
  "isMuted":false, "muteExpiration":null }

Message object

{ "id":"true_49152…@c.us_3EB0…", "chatId":"4915212345678@c.us", "from":"…", "to":"…",
  "author":null, "body":"text", "type":"chat", "timestamp":1757012345678, "fromMe":false,
  "hasMedia":false, "hasQuotedMsg":false, "ack":3, "isForwarded":false,
  "deviceType":"android", "location":null, "vCards":[] }

Do not ask for more history than you need. limit above 200 is clamped to 200 and the whole call has a 30-second deadline. Larger fetches walk the chat backwards inside the browser and can push the instance into a memory-driven restart. capped: true in the response tells you the ceiling was hit.

8. Groups

POST /api/v2/groups creates messages for every participant and therefore goes through the queue. All other group endpoints are immediate and use the 60/min interaction limiter.

Every group endpoint verifies isGroup first and answers 400 NOT_A_GROUP otherwise.

curl -s -X POST "$WA_URL/api/v2/groups/49152…-1600000000@g.us/participants" \
  -H "Authorization: Bearer $WA_API_KEY" -H "Content-Type: application/json" \
  -d '{"participants":["4915299999999@c.us"]}'

curl -s "$WA_URL/api/v2/groups/49152…-1600000000@g.us/invite" \
  -H "Authorization: Bearer $WA_API_KEY"

POST /api/v2/groups (group creation) is not usable in the current build — see section 14.

9. Queue and limits

Full explanation in QUEUE.md. Endpoints:

Job ids always start with wq_. That prefix is how /api/v2/messages/:id decides whether you mean a queue job or a WhatsApp message.

curl -s "$WA_URL/api/v2/queue" -H "Authorization: Bearer $WA_API_KEY"

{
  "success": true,
  "data": {
    "mode": "pg",
    "limitsEnforced": true,
    "degradedSince": null,
    "counts": { "queued": 3, "scheduled": 12, "sending": 1, "sent24h": 88, "failed24h": 2, "unknown24h": 0 },
    "nextAt": "2026-09-05T21:19:02.000Z",
    "limits": { "maxPerHour": 40, "maxPer24h": 500, "usedLastHour": 12, "usedLast24h": 88,
                "remainingHour": 28, "remaining24h": 412, "minDelayMs": 4000, "maxDelayMs": 12000,
                "quietHours": null, "window": "sliding" }
  }
}

limitsEnforced is true in pg and in memory-degraded, false only in disabled. degradedSince is an ISO timestamp while the fallback is active and null otherwise. In memory-degraded the used* and remaining* fields are null — the fallback counts in process memory and cannot report the shared 24 h window.

Job status object (GET /api/v2/messages/wq_…):

{
  "success": true,
  "data": {
    "jobId": "wq_9f2c1b7e4a0d4c8e",
    "state": "sent",
    "deliveryConfidence": "assumed",
    "messageId": "true_49152…@c.us_3EB0…",
    "resultCode": "ASSUMED_SENT",
    "errorMessage": null,
    "unknownReason": null,
    "idempotencyKey": "order-4711",
    "kind": "text",
    "chatId": "4915212345678@c.us",
    "phone": null,
    "priority": 5,
    "originRoute": "/api/v2/send-message",
    "queuedAt": "…", "scheduledAt": "…", "dispatchedAt": "…", "terminalAt": "…", "expiresAt": "…",
    "attempts": 1,
    "etaSeconds": null
  }
}

There is no automatic retry, ever. POST /api/v2/messages/:jobId/requeue creates a brand new job with a new jobId (and a derived idempotency key) — the old row stays terminal. That rule is what prevents duplicate WhatsApp messages.

10. Status and health

GET /api/status

curl -s "$WA_URL/api/status" -H "Authorization: Bearer $WA_API_KEY"

{
  "success": true,
  "data": {
    "status": "connected",
    "phoneNumber": "4915212345678",
    "connected": true,
    "browser": { "alive": true, "failStreak": 0, "lastOkAt": 1757012345678 },
    "queue": {
      "sent": 120, "failed": 2, "queued": 3, "pending": 16,
      "scheduled": 12, "sending": 1, "inFlight": 1, "unknown": 0,
      "sent24h": 88, "failed24h": 2, "unknown24h": 0,
      "mode": "pg", "degraded": false, "nextAt": "2026-09-05T21:19:02.000Z",
      "limits": { "…": "…" }
    },
    "messages": { "…": "…" }
  }
}

status, phoneNumber and connected are unchanged from before; browser and the extra queue fields are additive.

status values: initializing, waiting_qr, authenticated, connected, disconnected, error.

GET /api/qr

curl -s "$WA_URL/api/qr" -H "Authorization: Bearer $WA_API_KEY"

Returns {status:'connected', phoneNumber} when already linked, otherwise {qr:'data:image/png;base64,…', status} or {status, message:'QR code not yet available'}.

GET /health (no authentication)

Service-level health of the gateway itself, counts only — no instance ids, no customer data:

{ "success": true, "service": "WhatsApp Multi-Session API", "version": "1.0.0",
  "timestamp": "…", "instances": { "total": 5, "online": 4, "offline": 0, "starting": 1,
  "degraded": 0, "quarantined": 0 }, "queue": { "degraded": 0 } }

11. Webhooks

Webhooks are opt-in per instance and configured by your operator. Existing instances receive nothing new unless they explicitly subscribe.

Envelope

{
  "v": 2,
  "eventId": "ev_7d3a1c9e5b2f4a80",
  "event": "message",
  "instanceId": "8d1b7c1f-…",
  "timestamp": 1757012345678,
  "data": { }
}

event, instanceId, timestamp and data keep their name, type and position from v1. v and eventId are additive — old receivers keep working.

Headers

Verify against the raw bytes you received, not a re-serialised object.

const crypto = require('crypto');
function verify(rawBody, headers, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headers['x-webhook-signature']));
}

Events

Default subscription for existing instances: message, ready, disconnected, instance_restarting, test. Everything else must be opted in. * subscribes to all.

WhatsApp events

Queue events

There is no message.scheduled event: acceptance always fires message.queued, whether or not a slot was assigned at that moment. The message.* events above are emitted by the persistent queue path only — while an instance is in memory-degraded none of them fire, only queue.degraded at the start of the window and queue.recovered at its end.

Incoming message media block (inside data.media):

{ "mimetype": "image/jpeg", "filename": null, "size": 184320,
  "stored": true, "mediaId": "md_…", "url": "/api/v2/media/md_…", "expiresAt": "…" }

mimetype, filename and size are unchanged. stored, mediaId, url and expiresAt are additive and only present when your operator enabled incoming media storage.

Retries

Normal events: 3 attempts. High-frequency events (message_ack, message_sent, message_reaction, unread_count, media_uploaded, message_ciphertext, message_ciphertext_failed, change_battery): 1 attempt, no retry.

12. Error codes

13. Limits, sizes and timeouts

14. Current release status and known gaps

Documented against the code as it stands, not against the plan. Nothing here is hidden.

Not implemented, and will not be

Physically impossible, stated honestly

Without X-Idempotency-Key, loss-free delivery across the network boundary cannot be guaranteed. If your connection drops before our commit, you cannot distinguish "never arrived" from "arrived, answer lost". A retry may duplicate. This is physics, not laziness. Use an idempotency key on every send that matters.

A unknown job state means the message was dispatched but the outcome is unverifiable. It is never retried automatically, because any automatic decision is wrong in one direction: retrying duplicates, dropping loses. Watch the message.unknown webhook and resolve it by hand.

Open defect in the current build

Nothing else on this page is known to be broken. The queue is nevertheless still being rolled out per instance — see the next paragraph for how to tell whether it is on for yours.

Enabled state matters

/api/v2/send-* requires the persistent queue to be enabled for your instance. If it is not, every v2 send route answers:

{ "success": false, "code": "QUEUE_STORE_UNAVAILABLE",
  "error": "queue store unavailable — loss-free delivery cannot be guaranteed",
  "data": { "queueMode": "disabled" } }

The v1 routes (/api/send-message, /api/send-media, /api/send-bulk) work in every mode and behave exactly as they always did. Ask your operator to enable the queue for your instance if you want v2.

Queue and Rate Limits — How Sending Really Works

Plain-language companion to API.md. Read this if you want to know when your message actually goes out, what queued means, and what happens when a limit is reached.

Table of contents

1. The one-paragraph version
2. The three knobs
3. What "queued" means in the response
4. When exactly does my message go out?
5. Worked examples
6. What the legacy routes do when a limit is active
7. Changing limits while the queue is full
8. Restarts, crashes and "nothing gets lost"
9. Job states, end to end
10. How to configure the limits
11. Monitoring the queue
12. Honest limitations

1. The one-paragraph version

You tell us how many messages an instance may send per hour and per 24 hours, and how much random pause to leave between two messages. Everything you hand in is written to a PostgreSQL table first and only then scheduled. If you are within the limits it goes out almost immediately (after the random pause). If you are over the limit it is not rejected — it gets a concrete future send time and the API tells you when. Nothing is dropped, nothing is sent twice, and no message is ever retried automatically.

2. The three knobs

Existing instances are not throttled by the update. All limits start at null, which means "no limit" — exactly like before. Nothing changes until someone deliberately turns limits on.

Why the windows slide

A calendar-hour window would let you send 59 messages at 10:59 and 60 more at 11:00 — twice the limit inside two minutes. That burst is exactly the pattern WhatsApp's spam detection reacts to. A sliding window counts "the last 60 minutes from right now", so the burst is impossible.

Why the random delay always applies

The pause is measured against the last actual dispatch, not against the queue length. So even a single message sent into an empty queue waits minDelayMs…maxDelayMs after the previous one. The last dispatch time is stored in the database, so a process restart does not reset your sending rhythm — otherwise a restart would produce a suspicious burst.

3. What "queued" means in the response

A fresh submission always answers 202 Accepted with status: "queued". There is no second value to handle — status never carries scheduled.

Why two fields: whether a slot is already assigned is a planning stage, not a business outcome. In both cases the message is accepted and not yet out, and scheduledAt / etaSeconds already tell you when. Branch on status; read queueState only if you are debugging the planner.

An idempotent replay — same X-Idempotency-Key, same payload — answers 200 OK with idempotentReplay: true and returns the current state of the original job. Terminal states are not flattened into queued, so status there can be sending, sent, failed, unknown, cancelled or expired. Read status, do not assume sent. (Same key with a different payload is 409 IDEMPOTENCY_PAYLOAD_MISMATCH.)

{
  "success": true,
  "data": {
    "status": "queued",
    "queueState": "scheduled",
    "jobId": "wq_9f2c1b7e4a0d4c8e",
    "messageId": null,
    "idempotencyKey": "order-4711",
    "idempotentReplay": false,
    "scheduledAt": "2026-09-05T21:15:33.412Z",
    "etaSeconds": 42,
    "queuePosition": 7,
    "expiresAt": "2026-09-06T21:15:33.412Z",
    "statusUrl": "/api/v2/messages/wq_9f2c1b7e4a0d4c8e",
    "limits": {
      "maxPerHour": 40, "usedLastHour": 12, "remainingHour": 28,
      "maxPer24h": 500, "usedLast24h": 88, "remaining24h": 412,
      "minDelayMs": 4000, "maxDelayMs": 12000, "quietHours": null, "window": "sliding"
    }
  }
}

messageId is null until the message actually goes out; on a replay of a finished job it carries the WhatsApp id. Routes that validate more than the queue does (media, stickers, voice) may add a warnings array.

Read etaSeconds if you want to tell a user "in about a minute", read scheduledAt if you want an exact time, read limits.remainingHour if you want to decide whether to hand in more work.

4. When exactly does my message go out?

The planner walks the waiting jobs in the order priority DESC, arrival time ASC and gives each one a concrete timestamp, using this rule chain:

start at:  max( now , lastDispatchAt + random(minDelayMs, maxDelayMs) )
then, until all constraints hold (max 200 attempts):
    if inside quiet hours          -> jump to the end of the quiet window
    if hourly limit reached at t   -> jump to (oldest message in the last hour) + 1h + 1ms
    if 24h limit reached at t      -> jump to (oldest message in the last 24h) + 24h + 1ms
place the message at t
next cursor = t + random(minDelayMs, maxDelayMs)

Two things follow from that:

• The random delay is a lower bound, the limits are upper bounds. Whichever is later wins.
• Order is never changed by a limit. A limit moves when things go out, never *what goes

first*. Only priority does that.

If the computed time would fall after the message's expiresAt, the request is rejected right away with 422 TTL_UNREACHABLE instead of accepting something that will silently expire later.

Messages that count against the limits: everything in state sent, sending or unknown. unknown counts too — an unverified message was very probably delivered, and not counting it would push you over the real limit.

The plan is checked again immediately before sending

scheduledAt is a plan, not enforcement. Anything that makes the plan stale — a WhatsApp disconnect (routine with this stack), an ordered restart, a limit change, a clock change, a recovery after a crash — makes many slots fall due at once. Without a second check the dispatcher would fire them back to back, which is exactly the burst pattern WhatsApp's spam detection reacts to.

So every job is re-checked the moment before it is handed to WhatsApp: hourly budget free? daily budget free? minimum spacing respected? outside quiet hours? If any of those fails, the job goes back into the queue with a new scheduledAt and is not sent. The counters come from the same rows that record the dispatch, so they cannot drift.

Practical consequence: a backlog that piled up during a two-hour outage is drained at the configured rate, not in one burst — and etaSeconds you fetched before the outage may be outdated. Re-read the job status if the exact time matters.

5. Worked examples

Example A — no limits (the default today)

Config: maxPerHour: null, maxPer24h: null, minDelayMs: 1500, maxDelayMs: 3000.

You send 5 messages back to back. They go out roughly 1.5–3 seconds apart. etaSeconds is 0–2 for the first, growing for the rest. This is byte-for-byte the behaviour that existed before the queue was introduced.

Example B — 40 per hour, 4–12 s apart

Config: maxPerHour: 40, minDelayMs: 4000, maxDelayMs: 12000.

You hand in 100 messages at 09:00.

Response for message 41:

{ "status":"scheduled", "jobId":"wq_…", "scheduledAt":"2026-09-05T10:00:00.001Z",
  "etaSeconds": 3600, "queuePosition": 41,
  "limits": { "maxPerHour":40, "usedLastHour":40, "remainingHour":0 } }

Example C — quiet hours

Config: quietHours: {"start":"22:00","end":"07:00","tz":"Europe/Berlin"}.

You hand in a message at 23:30 Berlin time. It is scheduled for 07:00:00 next morning, local time, DST-aware. etaSeconds is about 27000. Nothing is dropped.

Example D — over the daily limit

Config: maxPer24h: 500, ttlSeconds: 86400 (the default).

You hand in message number 501 for the day. The planner finds that the earliest free slot is 25 hours away, which is beyond the 24-hour TTL:

{ "success": false, "code": "TTL_UNREACHABLE",
  "error": "no slot available before expiry",
  "data": { "expiresAt": "2026-09-06T09:00:00.000Z" } }

That is deliberate: better an immediate, honest rejection than accepting a message that will quietly expire tomorrow. Raise ttlSeconds (up to 30 days) if you want it to wait.

Example E — retrying safely

# first attempt — network dies, you never see the answer
curl -X POST "$WA_URL/api/v2/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "X-Idempotency-Key: invoice-2026-0042" \
  -d '{"phone":"4915212345678","message":"Invoice 42 attached"}'

# retry the identical request — safe
curl -X POST "$WA_URL/api/v2/send-message" \
  -H "Authorization: Bearer $WA_API_KEY" \
  -H "X-Idempotency-Key: invoice-2026-0042" \
  -d '{"phone":"4915212345678","message":"Invoice 42 attached"}'

The second call returns HTTP 200 with idempotentReplay: true and the original jobId. No second message is created.

If you reuse the same key with a different body you get 409 IDEMPOTENCY_PAYLOAD_MISMATCH — that guard exists so a client bug cannot get the wrong message acknowledged as "already sent".

Idempotency keys are scoped per instance and remembered for 7 days.

6. What the legacy routes do when a limit is active

POST /api/send-message and POST /api/send-media are synchronous by contract. They now go through the same queue with priority 9 and then wait for the outcome:

The 20 s are LEGACY_SYNC_TIMEOUT_MS. The number in the error text is derived from that setting, so it changes with it. It is deliberately below the 30 s your client is assumed to wait (LEGACY_CALLER_TIMEOUT_MS) and is hard-capped at LEGACY_CALLER_TIMEOUT_MS − 5 s: a caller that gives up before we answer cannot tell "sent" from "not sent" and tends to retry — which is exactly how the historical duplicate incident happened.

The 504 is not a failure. The message is in the queue and will go out at scheduledAt. Follow it with GET /api/v2/messages/<jobId>. Do not resend — that would duplicate.

With maxPerHour: null (the default for all existing instances) the 504 path is unreachable: the planner produces exactly the same spacing the old in-memory queue produced, so nothing waits longer than it did before.

If you would rather have the old routes answer immediately, ask your operator to set legacyQueueMode: "async" for the instance. Then POST /api/send-message answers 202 with:

{ "success": true, "data": { "messageId": null, "phone": "…", "status": "queued",
  "jobId": "wq_…", "scheduledAt": "…", "etaSeconds": 42 } }

This is opt-in per instance and never happens by itself.

POST /api/send-bulk was already asynchronous and is unchanged; it just gained jobId, scheduledAt and etaSeconds per entry.

7. Changing limits while the queue is full

Changing maxPerHour, maxPer24h, minDelayMs, maxDelayMs or quietHours triggers a full re-plan:

1. Everything in state scheduled goes back to queued.
2. A message currently in state sending is never interrupted — it runs to completion.
3. The planner assigns fresh times, in the same order as before (priority, then arrival).
4. A queue.replanned webhook fires with {affected, epoch, reason}.

Lower the limit → everything shifts later. Raise the limit → everything shifts earlier, but never earlier than max(now, lastDispatch + minDelay).

Changing storeIncomingMedia or legacyQueueMode does not trigger a re-plan — those do not affect timing.

8. Restarts, crashes and "nothing gets lost"

Every message is written to PostgreSQL before anything is sent, and the state change to sending is committed before the WhatsApp call is made. That gives a clean answer for every possible crash point:

Why unknown is never retried

Retrying a message that was in fact delivered produces a duplicate on a customer's phone. Dropping a message that was in fact not delivered loses it. Both are wrong, and the system cannot tell them apart. So it does neither: it marks the job unknown, fires a webhook, logs an error, and asks a human. That is the single rule that closed the historical duplicate-message incident.

If the database goes away while we are running

The send path does not stop. The instance switches to memory-degraded, keeps serving the v1 routes through the in-memory path (with limits still enforced), fires a queue.degraded webhook and probes every 30 seconds. When PostgreSQL comes back, the in-memory backlog is drained first, then normal operation resumes and queue.recovered fires. The message that was in flight at the moment of the switch stays with the fallback — adopting it would risk a duplicate.

The v2 send routes deliberately answer 503 QUEUE_STORE_UNAVAILABLE during that window: they promise loss-free delivery, and in memory that promise does not hold.

An ordered restart leaves nothing behind

When the instance restarts itself in a controlled way, it pauses the dispatcher and waits up to 35 seconds for the in-flight message to finish before shutting down. A clean restart therefore produces no unknown rows at all.

9. Job states, end to end

        submit()
           │
           ▼
       ┌────────┐   planner    ┌───────────┐   scheduledAt reached   ┌─────────┐
       │ queued │─────────────►│ scheduled │────────────────────────►│ sending │
       └────────┘◄─────────────└───────────┘                         └─────────┘
           │        re-plan          │                              ╱     │     ╲
           │                         │              transient      ╱      │      ╲
           │ TTL                     │ TTL          (not yet sent)╱       │       ╲
           ▼                         ▼                    ┌──────╱   ┌────▼───┐   ╲────────┐
       ┌─────────┐              ┌─────────┐               │queued│   │  sent  │   │unknown │
       │ expired │              │ expired │               └──────┘   └────────┘   └────────┘
       └─────────┘              └─────────┘                              │
                                                                    ┌────▼───┐
        cancel() from queued/scheduled ─────► cancelled             │ failed │
                                                                    └────────┘

There is exactly one attempt per row. attempts in the status response is always 1. POST /api/v2/messages/:jobId/requeue does not resurrect a row — it creates a new job with a new jobId and a derived idempotency key. Only failed, expired and cancelled jobs can be requeued.

The one exception: if a message could provably not be sent yet (WhatsApp temporarily disconnected, browser page died during number validation), the row goes back to queued with a growing backoff (5 s, 10 s, … capped at 60 s), at most 10 times. After that it becomes failed with resultCode: "REQUEUE_EXHAUSTED". This only ever happens before the WhatsApp call was made, so it can never duplicate.

10. How to configure the limits

Limits live per instance and are set by your operator, either in the admin panel ("Limits" button on the instance card) or via the admin API:

curl -s -X PUT "https://wa.outrnk.io/api/instances/<INSTANCE_ID>/limits" \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": true,
        "maxPerHour": 40,
        "maxPer24h": 500,
        "minDelayMs": 4000,
        "maxDelayMs": 12000,
        "quietHours": { "start": "22:00", "end": "07:00", "tz": "Europe/Berlin" },
        "legacyQueueMode": "sync",
        "defaultTtlSeconds": 86400,
        "storeIncomingMedia": false
      }'

The configuration is written to disk first and pushed to the running instance second, so a failed live push still leaves the setting correct for the next start.

Validation rules

Unknown keys are silently ignored (forward compatibility), so sending a newer config to an older build does not fail.

Recommended starting point

40 / 500 / 4000 / 12000 / quiet 22:00–07:00 Europe/Berlin — the values behind the "Apply recommended limits" button in the panel. They approximate a human sending pattern and stay well inside what WhatsApp tolerates for a normal account.

11. Monitoring the queue

curl -s "$WA_URL/api/v2/queue" -H "Authorization: Bearer $WA_API_KEY"

{ "success": true, "data": {
  "mode": "pg",
  "limitsEnforced": true,
  "degradedSince": null,
  "counts": { "queued": 3, "scheduled": 12, "sending": 1, "sent24h": 88, "failed24h": 2, "unknown24h": 0 },
  "nextAt": "2026-09-05T21:19:02.000Z",
  "limits": { "maxPerHour": 40, "usedLastHour": 12, "remainingHour": 28, "window": "sliding" }
}}

limitsEnforced answers the only question that matters when mode is not pg: are you still being throttled? It is true in pg and in memory-degraded, false only in disabled. degradedSince is set while the fallback is active.

memory-degraded means the database was unreachable. It is entered at start-up and at runtime: if PostgreSQL disappears while the instance is running, the send path switches over instead of failing, fires a queue.degraded webhook, and probes every 30 seconds to come back. When it comes back, the in-memory backlog is drained first and a queue.recovered webhook fires.

The one thing that does change in memory-degraded: the throttle counter is process-local. It starts at zero the moment the switch happens, so the last hour of already-sent messages no longer counts against maxPerHour. In the worst case an instance can use its hourly allowance a second time right after switching. The limits are never applied more strictly than configured, only more generously — and usedLastHour / remainingHour come back as null in this mode because the shared 24 h window is not readable.

Per-message queue webhooks stop while memory-degraded is active. message.queued, message.sent, message.failed and message.unknown are emitted by the persistent path only; the fallback sends none of them. queue.degraded and queue.recovered still fire and bracket the window exactly. If you drive business logic off message.sent, treat the span between those two events as a gap and reconcile it from GET /api/v2/queue/items once mode is pg again. The messages themselves are still sent — only the notifications are missing.

/api/status carries a plain boolean for monitoring: data.queue.degraded is true for anything that is not pg — including the default mode disabled. If you want to tell the two apart, read mode and limitsEnforced from GET /api/v2/queue.

List individual jobs:

curl -s "$WA_URL/api/v2/queue/items?state=scheduled&limit=50" -H "Authorization: Bearer $WA_API_KEY"
curl -s "$WA_URL/api/v2/queue/items?state=unknown&limit=50"   -H "Authorization: Bearer $WA_API_KEY"

Cancel one that has not started sending:

curl -s -X DELETE "$WA_URL/api/v2/messages/wq_9f2c1b7e4a0d4c8e" -H "Authorization: Bearer $WA_API_KEY"

The number to watch is unknown24h. Anything above zero means at least one message was dispatched with an unverifiable outcome and needs a human to check the chat.

Housekeeping runs by itself: expired jobs are reaped every 60 seconds, terminal rows are deleted after 7 days, stored media after 72 hours.

12. Honest limitations