Skip to main content
Version: v0.31.0

API conventions

The rules that hold across every OpenWA endpoint: where the API lives, how you authenticate, what a response looks like, and which status codes you will hit. Read this once, then use the API reference for per-endpoint detail.

This documentation targets OpenWA v0.31.0.

Base URL and the /api prefix​

Every REST route is mounted under a global /api prefix on port 2785.

http://localhost:2785/api

In local development that is http://localhost:2785/api. In production, OpenWA serves plain HTTP and expects you to terminate TLS at a reverse proxy; substitute your own origin and keep the /api prefix:

https://wa.example.com/api

All examples on this site use the local base URL.

Versioning​

The API is not URL-versioned — there is no /v1 segment. The version is the OpenWA release you run. Check it any time with the health endpoint. The endpoint itself is public, but since v0.19.0 the version field is disclosed only to callers presenting a valid API key — an unauthenticated probe still gets 200 with status and timestamp, and no version to fingerprint:

curl http://localhost:2785/api/health -H "X-API-Key: YOUR_API_KEY"
{ "status": "ok", "timestamp": "2026-06-25T12:34:56.789Z", "version": "0.31.0" }

Pin your deployment to a known release and read the field reference for that version. When a field or default is version-sensitive, this documentation says so.

Since v0.23.6 an admin key with no session or chat scope can ask GET /api/infra/update-check whether a newer release exists. It answers current, latest, updateAvailable and releaseUrl, reading the latest published GitHub release and caching it for six hours (fifteen minutes after a failed check). A failed check is never reported as an error: latest stays null until the gateway has reached GitHub once, and a later failure keeps the last release it found. The request goes to api.github.com directly, not through HTTP_PROXY or HTTPS_PROXY, so on a host whose only way out is such a proxy latest stays null. UPDATE_CHECK_ENABLED=false turns the outbound request off, and latest is then always null.

Since v0.16.0 the contract itself changed shape in one place, without changing any URL. The group-list and status routes used to appear twice in openapi.json under different path-parameter names, each key carrying one verb of the same URL; they are now one entry each. GET /sessions/{id}/groups (the pre-v0.16.0 spelling) became GET /sessions/{sessionId}/groups, and the status read and delete both take {id} in place of {contactId} and {statusId}. The status media route keeps {statusId}, since nothing collided there. v0.19.0 finished the respell: the twenty-two session routes that still addressed the session as {id} — the chats family, start, stop, qr, pairing-code, presence, and the rest — now spell it {sessionId} throughout the contract, and the Prometheus route labels follow. No URL and no request behaviour changed, so a hand-written HTTP caller needs no change at all. If you generate a client from openapi.json, regenerate it: parameter names move with the template, so generated method and argument names derived from the old names will change.

v0.23.4 changed a schema the same way, again without touching a URL. GET /sessions/{sessionId}/labels/{labelId}/chats used to answer with a LabelChatDto, a narrower object of its own; it now answers with the same ChatSummaryDto as the chats list, and LabelChatDto is gone from the contract. A hand-written caller reads three extra fields and nothing else changes, but a generated client loses a type by that name, so regenerate rather than patching the call site. ChatSummaryDto itself gained three required fields in the same release, which is the other half of the same change.

v0.31.0 changed the published type of eight request fields the same way, again without touching a URL or what a route accepts: the routes already refused a fraction for each of them, and openapi.json now says integer where it said number. They are maxReconnectAttempts and reconnectBaseDelay of the session config, the webhook retryCount, the limit of a webhook redrive, the automation rule cooldownSeconds, the group setting ephemeralSeconds, the label color, and database.poolSize of the infrastructure config, which GET /api/infra/config also returns as an integer and whose minimum of 0 is now published. A hand-written caller needs no change. If you generate a client from openapi.json, regenerate it: a generator that tells integer from number emits a different type for these fields. The document also declares the automation and media tags, which operations already used without a declaration, so the API explorer describes both groups.

Authentication​

Every route is protected by an API-key guard unless it is explicitly public: the health checks, GET /api/infra/health, the metrics endpoint (which uses a separate bearer token), and the Integration Fabric ingress routes, which authenticate a provider signature instead of a key. Send your key in the X-API-Key request header:

curl http://localhost:2785/api/sessions \
-H "X-API-Key: YOUR_API_KEY"

YOUR_API_KEY is the key OpenWA seeds on first run (written to data/.api-key, and printed to the startup log when generated; since v0.28.0 a key supplied via API_MASTER_KEY is never printed to the startup log). Use that admin key to mint scoped, lower-privilege keys through the auth resource. The key is bearer-equivalent — anyone holding it can act as you — so never send it over plaintext http:// outside local development, and never put it in a URL.

REST auth is header-only

A query-parameter API key (?apiKey=) is not accepted on REST routes. The header is the only way in.

For the full sign-in walkthrough and how to create scoped keys, see the authentication guide.

Roles​

Each key carries one of three roles, enforced as a minimum-rank hierarchy (viewer < operator < admin):

RoleCan do
viewerRead routes (list sessions, read message history, view contacts). Not every read is open to it: for example, search, the webhook, automation-rule and template lists, group invite codes and the session QR need operator, and the audit log, the instance-wide statistics, plugins and the infrastructure reads (apart from the public /api/infra/health probe) need admin
operatorEverything a viewer can, plus write and action routes (send messages, manage groups, manage webhooks)
adminEverything, plus key management and global settings

A key may also be scoped to specific sessions and source IPs. The scope and IP checks run before the role check, so a request outside a key's allowed sessions or IPs is rejected with 403 since v0.24.0, even when the role would otherwise pass. Earlier releases returned 401; invalid keys still return 401.

Since v0.23.6 a key can also carry an allowedChats allowlist of groups and contacts. That check runs after the role check and answers 403: a chat-restricted key is refused on every route not marked safe for chat scoping, and on a marked route whenever the request names a chat outside the list or carries a quotedMessageId anywhere but POST /sessions/{sessionId}/messages/reply. A phone entry also matches its resolved @lid form. Chat, contact, group and label-chat lists filter before pagination. Stored messages require an allowed chatId; built-in search filters before paging and totals, while plugin search providers refuse chat-restricted keys. The list is capped at 2000 entries. Since v0.25.0 WebSocket subscriptions and MCP tools also support chat scope. See the authentication guide for the routes it covers.

Request format​

Send a JSON body on POST, PUT, and PATCH requests, with a Content-Type header:

curl -X POST http://localhost:2785/api/sessions \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "my-bot" }'

Request bodies are strictly validated. A field that is not declared on the endpoint's schema is rejected, an unknown field returns 400, it is not silently ignored. Validation failures return 400. Field-level details are enabled by default outside production or with VALIDATION_ERROR_DETAIL=true; production otherwise returns only { "statusCode": 400, "message": "Bad Request" }. Accept either a string or an array in message. NUL characters in a path, query or ordinary JSON body are refused with 400; backup imports and raw ingress have separate handling.

Since v0.26.0 the checks on value types are stricter. A JSON boolean or object in a string field answers 400, where it used to be converted to text ({"text":{"a":1}} sent the customer [object Object]); a JSON number is still read as its decimal string. An array where the body expects an object (bulk options, customLinkPreview, a bulk item's content and media, the sections of PUT /infra/config, a status media source) and an object where it expects a list answer 400 too, where they were stored as defaults or as an empty list. A JSON body nested more than 100 levels deep answers 400 before authentication is checked; it used to answer 500 with a stack trace in the error log. A chatId, fromChatId or toChatId on a send or message-action body must carry its domain (628123456789@c.us): without one, or sent as a JSON number, it answers 400 where, on Baileys, it answered 500 and sent nothing. Since v0.28.0 a JSON body with more than 10,000 items in one array, more than 1,000 keys on one object, or more than 250,000 array items and object keys in total also answers 400 before route validation runs. Since v0.31.0 a string or number field that receives an object with its own toString (JSON {"toString":"x"}, or a form key such as name[toString]=x) answers 400 too, where it answered 500 and logged a stack.

Pagination​

List endpoints that can return large result sets accept limit and offset query parameters. Defaults and ceilings are per-endpoint — for example, session chats and groups default to limit=1000, while message history defaults to limit=50 and clamps to a maximum of 100. GET /search refuses an offset above 100000 with 400 (v0.23.6+) where earlier releases clamped it and returned the page at 100000 again. There is no global pagination envelope; check each endpoint in the API reference for its exact bounds.

curl "http://localhost:2785/api/sessions/SESSION_ID/messages?limit=50&offset=0" \
-H "X-API-Key: YOUR_API_KEY"

offset counts rows, so a message arriving between two pages shifts the window and a walk can repeat a row or skip one. Since v0.23.4 GET /sessions/{sessionId}/messages also takes after, a keyset cursor carrying the id of the previous page's last row:

curl "http://localhost:2785/api/sessions/SESSION_ID/messages?limit=50&after=LAST_ID_OF_PREVIOUS_PAGE" \
-H "X-API-Key: YOUR_API_KEY"

after anchors the window to a row instead of a count, so a concurrent write cannot move it. It replaces offset rather than adding to it: send both and offset is ignored rather than refused, so an SDK that always sends offset=0 keeps working. A blank after= reads as absent. A cursor naming no message in this session answers 400 Unknown cursor '<id>' for this session rather than an empty page, which would otherwise be indistinguishable from reaching the end of the history. total means the same thing either way: rows matching the filters, not rows remaining.

Since v0.23.4 every paged list also breaks ties on a second sort key, so a walk returns each row exactly once. That covers the message, session, webhook and delivery-failure lists and GET /search; before it, a non-unique sort key could repeat a row on one page and drop it from the next on PostgreSQL. On SQLite, the default database, the tiebreaker is the stored insertion sequence, so messages sharing one second come back in arrival order instead of shuffled; PostgreSQL orders such a group by id. offset is still a count and still shifts under concurrent writes, which is exactly what after exists to avoid.

Since v0.26.0, on GET /sessions/{sessionId}/chats and GET /sessions/{sessionId}/contacts, a page after the first (offset above 0) is cut from the list the engine returned within the last 5 seconds, so walking a large account costs one engine read instead of one per page; a request at offset=0 always reads the engine again. An offset of 2^63 or more on the audit, session, webhook, delivery-failure and message lists answers an empty page, where it answered 500. GET /search refuses a dateFrom or dateTo outside plus or minus 9007199254740991 with 400.

For the v0.25.0 time, direction, type and reference filters and message-time ordering, see Filter and page stored messages. Keep the same filters when continuing a cursor; a deleted or mismatched anchor returns 400, and unknown message timestamps have a separate count.

Response format​

OpenWA returns the raw handler payload — there is no { success, data, meta } wrapper. Read fields directly off the response.

A resource route returns the object as-is:

{
"id": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
"name": "my-bot",
"status": "ready"
}

Most list routes return a bare JSON array:

[
{ "id": "…", "name": "session-a" },
{ "id": "…", "name": "session-b" }
]

A few paginated list routes instead return a small wrapper such as { "messages": [...], "total": 42 }. The per-endpoint reference states the exact shape.

Timestamps​

OpenWA uses three timestamp representations — know which a field is:

Field kindRepresentationExample
Message timestampsUnix epoch seconds (a number)1719312000
Group membership requests — requestedAt on GET /sessions/{sessionId}/groups/{groupId}/membership-requestsUnix epoch seconds (a number)1754700000
muteUntil on POST /sessions/{sessionId}/chats/muteUnix epoch milliseconds (a number)1800000000000
muteExpiration on a chat summary (v0.23.4+)Unix epoch milliseconds (a number)1786003600000
startTime on POST /sessions/{sessionId}/calls/linkUnix epoch milliseconds (a number)1800000000000
Entity audit fields (createdAt, updatedAt, expiresAt, startedAt)ISO-8601 UTC string2026-06-25T09:20:00.000Z

The two millisecond request fields are the ones to get right: a seconds-scale value passes validation and answers 200, but it lands in 1970, so the mute expires immediately and the call link is scheduled in the past. Both are required — omitting them is a 400 rather than a guessed default. muteUntil additionally accepts null, which means unmute now. Since v0.26.0 a muteUntil above 9007199254740991 (Number.MAX_SAFE_INTEGER, the largest integer a JSON number carries exactly) answers 400: a larger value is not an exact integer, and from 2^63 it wrapped the Baileys int64. To mute indefinitely, send a far-future timestamp no later than that. A JSON boolean for startTime answers 400 since v0.26.0; true used to be read as 1.

muteExpiration is the one millisecond field in a response, and it shares a chat object with timestamp, which is seconds, so read the two with different scales. It carries the same unit as muteUntil, so a finite value round-trips back into a mute request unchanged. The exception is 0, which reports an indefinite mute: muteUntil demands a real future instant and rejects it, so re-apply an indefinite mute with a far-future timestamp.

On PostgreSQL, some of the ISO-8601 values stored before v0.23.6 while the gateway or the database server ran outside UTC read shifted by that offset from v0.23.6 on, until they are converted; see PostgreSQL deployments that ran outside UTC. SQLite deployments, and deployments that ran in UTC throughout, are unaffected.

Error format​

Errors use the NestJS default envelope. The HTTP status sits on the status line and is mirrored in statusCode, message says what went wrong, and error carries the reason phrase. error is not always present: a body built from a bare message omits it, for example an unexpected 500, a 413 for a body over BODY_SIZE_LIMIT that the parser refuses, the throttler's 429, a production validation 400 and the session-start 504. Some refusals also carry a stable code:

{
"statusCode": 404,
"message": "Session with id '8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a' not found",
"error": "Not Found"
}

When validation detail is enabled, message is an array of field-level strings:

{
"statusCode": 400,
"message": ["name must be longer than or equal to 3 characters"],
"error": "Bad Request"
}

Production hides the detail by default and answers { "statusCode": 400, "message": "Bad Request" }, without an error field.

The stable codes are SESSION_NAME_TEARDOWN_PENDING (409); SESSION_STOP_INCOMPLETE, SESSION_LOGOUT_INCOMPLETE and SESSION_FORCE_KILL_INCOMPLETE (502); SEND_PACING_LIMITED (429); ENGINE_PAGE_ERROR (500); ENGINE_PAGE_RELOADING (409, v0.31.0+, with retryAfterSeconds); IMPORT_ALREADY_RUNNING, EXPORT_IN_PROGRESS, IMPORT_WOULD_ORPHAN_ENGINES and IMPORT_NESTED_TRANSACTION (409); RESTART_DATABASE_NOT_STARTED and RESTART_ALREADY_RUNNING (409, v0.27.1+); IDEMPOTENCY_KEY_INVALID (400); IDEMPOTENCY_KEY_REUSED (422); IDEMPOTENCY_KEY_IN_PROGRESS and IDEMPOTENCY_OUTCOME_UNKNOWN (409); and POLL_OPTION_NOT_FOUND (400). The error code reference gives the cause and fix for each. Branch on code when present rather than parsing English messages. The send retry guide describes the twelve routes supporting Idempotency-Key.

Status codes​

These are the codes you will actually encounter:

StatusMeaningWhen
200 OKSuccessA successful GET, or a write that the controller maps to 200. The other DELETE routes, apart from the plugin ingress pass-through, answer 200 with a small JSON body: labels, a label on a chat, contacts, a contact block, channels, plugins, statuses, profile and group pictures, group participants and a chat's messages
201 CreatedCreatedA successful POST (the NestJS default for POST)
202 AcceptedAcceptedA bulk send was queued for background processing, or an integration ingress delivery was accepted for plugin processing. Since v0.23.6 a repeat ingress delivery gets the same answer as the first (the route's declared ack, or 202) instead of 200 duplicate
204 No ContentSuccess, empty bodyA successful DELETE of a session, API key, webhook, automation rule, template or integration instance
400 Bad RequestValidation or precondition failedA bad or unknown body field, an invalid value, an Idempotency-Key header that is not one value of 1 to 255 visible ASCII characters (IDEMPOTENCY_KEY_INVALID, v0.25.0+), or a business precondition such as "session not started". The platform caps also surface as 400 — a group batch over 256 participants, a template render over TEMPLATE_RENDER_MAX_CHARS, a webhook registration over WEBHOOK_MAX_PER_SESSION, or a plugin install over plain http:// without a #sha256= pin. Since v0.23.6 a media url on a send, status or picture route that is not an absolute http(s) URL, or whose download answers a non-2xx status other than a redirect, times out or fails to connect, is a 400 too, where such a failed download used to answer 500. A url whose host does not resolve, that points at or resolves to a blocked internal address, or whose server answers with a redirect (3xx) is a 400 with the message Destination address is not allowed on the send routes, and since v0.31.0 on a status post and a profile or group picture change too, where those answered 500; SSRF_ALLOWED_HOSTS does not lift the refusal of a redirect. Since v0.31.0 a url that carries a user name or password is a 400 on every route that fetches one, where it answered 500 (a send also counted it toward the send breaker and kept its Idempotency-Key); send-bulk refuses a batch whose media url carries one when the batch is created, where it accepted the batch and failed the item (a url built from variables is still checked per item). The media-conversion routes already answered 400 for a failed download. Since v0.26.0 the value-type checks under Request format answer 400 too: a chat id without its domain, a JSON boolean or object in a string field, an array for an object or an object for a list, and a body nested over 100 levels. Since v0.28.0 an over-wide JSON body (over 10,000 items in one array, over 1,000 keys on one object, or over 250,000 array items and object keys in total), a POST /sessions config over 16,384 bytes serialized, a group route whose {groupId} does not name a group, a contacts/check/{number} with a non-phone @ id or no digits, a send-sticker on whatsapp-web.js with non-image/non-video media, or a chats/pin or chats/mute on Baileys for an unpaired 1:1 chat also answers 400, while a :sessionId of 1 to 128 ASCII letters, digits, and hyphens reaches session lookup and answers 404 when no session has that id. On whatsapp-web.js, since v0.31.0, a send-sticker video that ffmpeg refuses and a chats/mute of a channel id (a channel is muted through its own route) also answer 400, where both answered 500
401 UnauthorizedAuth failedMissing, invalid, expired or revoked key
403 ForbiddenAuthorization refusedA valid key outside its session/IP scope (since v0.24.0), or whose role is below the route requirement
403 ForbiddenChat out of scopeA key restricted with allowedChats (v0.23.6+) on a route not marked safe for chat scoping, naming a chat outside its allowlist, or carrying a quotedMessageId on any route but POST /sessions/{sessionId}/messages/reply
403 ForbiddenWhatsApp refused itThe request was well formed and reached WhatsApp, which turned it down — usually a group or channel write the account has no admin rights for. On Baileys a group the account left still answers 403, but since v0.23.6 a group that no longer exists answers 404, where it answered 403 before. Since v0.28.0 Baileys POST /sessions/{sessionId}/messages/edit also answers 403 when the target message has no text or caption, matching whatsapp-web.js
403 ForbiddenNot the account's own statuswhatsapp-web.js only (v0.23.6+): DELETE /sessions/{sessionId}/status/{id} names a status the account did not post, such as a contact's status from GET /sessions/{sessionId}/status (Only the account's own statuses can be deleted). Before v0.23.6 this answered 500
404 Not FoundNo such resourceThe session, chat, message, group, channel or invite code, label, webhook, or batch does not exist. Since v0.28.0 POST /sessions/{sessionId}/channels/{channelId}/owner/transfer and .../admins/demote also answer 404 when {channelId} does not end in @newsletter. Since v0.24.0 a DELETE to an /api/... path that ends in / also answers 404 with Cannot DELETE <path>, because that path names no resource: drop the trailing slash. Paths under /api/ingress/ are exempt
409 ConflictSend retry stateAn idempotency key is in progress or its delivery outcome is unknown; see the code before retrying
422 Unprocessable EntityIdempotency key reusedThe key already names a different route or body within its 24-hour window
422 Unprocessable EntityChat labels not supportedPOST /sessions/{sessionId}/labels/chat/{chatId} or DELETE /sessions/{sessionId}/labels/chat/{chatId}/{labelId} names a channel, which carries no labels; on whatsapp-web.js it is also refused for an account that is not a WhatsApp Business account
409 ConflictConflicting stateA duplicate value, such as creating a session with a name that already exists, or an action the resource's current state does not allow, such as a data import or export that overlaps another one or would orphan a running engine. Since v0.26.0 also a plugin install from a URL, enable, disable, update or uninstall while that plugin is still being restored after startup, a storage export or file count over a local directory that holds a symbolic link, a directory the app cannot read or one nested 20 levels deep (message names the path and the cause), and, on whatsapp-web.js, a pairing code for a number that is the stored phone of another session of the gateway
409 ConflictSession not connectedAn engine exists for the session but is not ready — disconnected, reconnecting, or still initializing — so the request never reached WhatsApp. Wait for ready and retry, except on POST /sessions/{sessionId}/pairing-code, which answers this until the session reads qr_ready, and again from the moment a code is accepted until it reads ready (a session that already reads ready is linked, and answers 400 there). Since v0.26.0, on whatsapp-web.js, a request that races a session stop or teardown (a send, status post, profile, group, label, mute or pin request) answers this 409 too, where it answered 500 or 503. On whatsapp-web.js, while WhatsApp Web reloads its page, the body carries code: ENGINE_PAGE_RELOADING and retryAfterSeconds, the interval to ask again at (v0.31.0+); the request is safe to repeat (a repeat of a channel delete that the first attempt had already applied may meet a channel that is gone, which answers 403, and a repeat of an unsubscription may meet a channel that is no longer followed), and the v0.15.0 warning below says how long the window lasts. A send or status post that was already under way when the session left ready or the page reloaded is the exception: it answers a 409 with no code and an unknown outcome, so the message may or may not have gone out. A session that was never started answers 400 instead — see Session not connected and 409
413 Payload Too LargeMedia too bigBase64 media exceeds the media byte cap (default 50 MiB), or, since v0.23.6, media downloaded from a url does. Before that, an oversized download answered 500 on a send, status or picture route and 400 on a media-conversion route. POST /sessions/{sessionId}/messages/send-bulk is the exception: it checks an item's base64 before answering 202 and fetches a url item afterwards, so a download that fails or passes the cap fails only that item in the batch results (SEND_FAILED, or SEND_BLOCKED for a host that does not resolve, a blocked address or a redirect) instead of answering 400, 413 or 503. A request body over BODY_SIZE_LIMIT (25mb by default, about 18.7 MiB of base64 media) answers 413 before the media cap is checked. A request whose declared body the in-flight body budget, the caller's share of it or the unkeyed pool could never admit also answers 413, without Retry-After (v0.24.0+), because retrying cannot help
415 Unsupported Media TypeCompressed request bodyThe request carries a Content-Encoding other than identity. Middleware refuses it before routing and never reads the body, because the in-flight body budget counts wire bytes and cannot bound what a compressed body inflates to. Send the body uncompressed. This and the overload 503 below are the two statuses any operation can emit for these causes, so neither is declared per route in the contract; the ingress operation declares its own 415
415 Unsupported Media TypeUnsupported ingress body typeA request to /api/ingress/{pluginId}/{instanceId}/{route} carries a body whose Content-Type is neither application/json nor application/x-www-form-urlencoded (v0.24.0+). It is refused before the signature check; see Integration Fabric
429 Too Many RequestsRate limitedA throttler window (see Rate limiting below), a send refused by send pacing (SEND_PACING_LIMITED), send-bulk while BULK_MAX_CONCURRENT_BATCHES batches (default 50, 0 for unlimited) are already running on the node, or GET /api/metrics after 10 failed tokens within a minute (v0.23.7+)
500 Internal Server ErrorServer or engine errorThe send failed at the WhatsApp engine, or an unexpected server error. On whatsapp-web.js, a send or status post that WhatsApp Web rejects inside the page answers 500 with code: ENGINE_PAGE_ERROR (v0.24.0+), a pageError object and, when known, the WhatsApp Web build. On the operations listed as deliberately unbounded below, a 500 is also the contract's way of saying a dead page left the outcome unknown: verify before replaying rather than treating it as a bug
501 Not ImplementedThe engine cannot do itThe operation is part of the engine contract, or the request has a shape the engine cannot serve, and the engine currently running has no implementation for it. Each of these operations declares its 501 in the API reference. Baileys cannot serve the label reads (GET .../labels, .../labels/{labelId}, .../labels/chat/{chatId} and .../labels/{labelId}/chats), list subscribed channels or read channel messages, cast a vote (vote-poll), or read a chat's history, a message's reactions, or a message's per-recipient delivery receipts (GET .../messages/{chatId}/{messageId}/receipts, v0.28.0+). whatsapp-web.js cannot serve catalog reads and send-product, label edits, creating a group (v0.16.0+), a group's disappearing-messages setting (ephemeralSeconds), setting this account's member label in a group (PUT .../groups/{groupId}/member-label, v0.27.0+), subscribing to a channel by invite code, transferring channel ownership, demoting a channel admin, rejecting a call (v0.23.6+), subscribing to presence, or replying to a business-prompt button through POST /sessions/{sessionId}/messages/click-button (v0.23.6+). It also refuses some sends: media to a channel and, since v0.23.7, a reply, contact card or location to a channel or to a status or broadcast list, a poll or sticker to a status or broadcast list, and a quotedMessageId to a channel, status or broadcast list on send-text and the media sends, or to a channel on send-poll. Some options of otherwise shared routes answer 501 on whatsapp-web.js only, for example customLinkPreview on send-text. Since v0.31.0, on whatsapp-web.js, a route that runs a job in the WhatsApp Web page also answers 501 when the WhatsApp Web build the session runs has no such job, and nothing is asked of WhatsApp; a build with the job serves the route as before. The routes are the group subject, description, picture, announce, locked and memberAddMode writes, DELETE .../groups/{groupId}/picture, POST .../groups/join, GET .../groups/join-info, GET .../groups/{groupId}/invite-code and its invite-code/revoke, PUT and DELETE .../profile/picture, PUT .../profile/status, and POST .../messages/pin and .../messages/unpin
501 Not ImplementedSearch cannot runGET /api/search when no search provider is registered (what SEARCH_PROVIDER=none produces), when the built-in provider finds no full-text index in the database, or, since v0.27.0, when match=contains is requested while SEARCH_CONTAINS_ENABLED=false (the default) or while the background trigram index build is still running. Nothing to do with the engine
502 Bad GatewayLifecycle teardown incompleteA session lifecycle route's teardown could not complete on both sides. The body carries a code naming the route, and a stop or logout failure is retryable: SESSION_STOP_INCOMPLETE on stop (v0.19.0+ — fires only when the graceful disconnect and the forced teardown both failed; the session is left disconnected), SESSION_LOGOUT_INCOMPLETE on logout (v0.12.0+ — stopped locally but the unlink did not complete), SESSION_FORCE_KILL_INCOMPLETE on force-kill (v0.24.0+, the force-destroy did not complete; the session is left disconnected). After a stop or force-kill failure the engine process may still be running, so restart the node to reap it. A force-kill cannot follow a failed stop: the stop has already released the engine, so it answers 400
502 Bad GatewaySearch provider returned an unusable resultGET /api/search only, and only while a plugin search provider is active: the result shape it returned failed the host's validation, so nothing trustworthy could be forwarded. The built-in provider never answers this
503 Service UnavailableNot ready or drainingThe readiness probe failed, or teardown began. During teardown new requests get Connection: close; only /api/health, /api/health/*, dashboard HTML and CORS preflights are exempt. /api/infra/health is not exempt
503 Service UnavailableOverloadedThe aggregate in-flight request-body budget is exhausted (INFLIGHT_BODY_BUDGET_BYTES, default 4 × the per-request BODY_SIZE_LIMIT), or the caller has spent its own share of it. Since v0.24.0 a request with an active API key is charged to that key (half the budget by default, however many addresses use the key), and every other request to its client IP inside a smaller unkeyed pool (the IP resolved through TRUSTED_PROXIES; without it every unkeyed caller behind a reverse proxy shares one share); before v0.24.0 every request was charged to its client IP (v0.21.0+). The response carries Retry-After and Connection: close; the body is never read — wait for the hint and retry
503 Service UnavailableWhatsApp never answeredA route reached a WhatsApp engine call that owns a request budget, and the budget expired with no reply. See Transport failures and 503
503 Service UnavailableMedia fetch through a proxy failedSince v0.23.6 a media url is fetched through the session's egress proxy when it has one, and a failure there before any response arrives answers 503 (the same failure answers 400 without a proxy). Nothing was sent, so the call is safe to retry. SESSION_PROXY_URL_FETCH=false sends those fetches from the gateway's own address instead
503 Service UnavailableWhatsApp rate-limited or timed out a sendBaileys only, since v0.26.0: a send, reply, forward, reaction, edit, delete, pin, unpin, click-button, send-product or status post (a status delete included) that WhatsApp turned away with a rate limit (code 429: nothing was sent, and a keyed send frees its Idempotency-Key) or timed out on a query the call awaits (code 408: the outcome is not proven, and a keyed send keeps its key taken). Both answered 500 before. Since v0.27.0 an Idempotency-Key is also freed when a send fails before anything is handed to WhatsApp: the session is not ready or its WhatsApp Web page is reloading before the send (409), a Baileys connection is closed (503), replaced or stopped (409) before the write, a media, sticker or link-preview thumbnail fetch or decode fails (400, 413 or 503), the recipient is not registered on WhatsApp on Baileys (400), or the quoted or forwarded message is not stored or belongs to another chat on Baileys (404). Since v0.31.0 a keyed send also frees its Idempotency-Key when, on Baileys, WhatsApp's media host refuses a media upload, and when, on whatsapp-web.js, the conversion of a video sticker fails (400 or 503)
503 Service UnavailableWhatsApp rate-limited, timed out or failed a whatsapp-web.js writeSince v0.31.0, on whatsapp-web.js, a rate limit, a timeout or a server error from WhatsApp is a 503 on the group subject, description, picture and settings writes, the removal of a group or account picture, the account picture write, a group join and an invite preview, reading and resetting an invite code, the channel delete, unsubscribe and mute writes, and the group read in front of messages/pin and messages/unpin. These answered 403, 400, 404 or 500 before, and a refused announce or locked write answered 200. A refusal by WhatsApp answers 403, except that a refused invite answers 400 on a group join and 404 on an invite preview. The 503 description of each route in the API reference says whether the change may have been applied; a channel write may or may not have been, so check before repeating it
503 Service UnavailableAnother database transaction stayed open or ownership check failedOn SQLite, since v0.26.0: POST /sessions, DELETE /sessions/{sessionId} and DELETE /integration/plugins/{pluginId}/instances/{instanceId} wait for another open database transaction to end and answer 503 when it stays open for 10 s. A create stores nothing and an instance delete deletes nothing, so retry; a session delete may already have committed earlier batches. Since v0.28.0 POST /sessions/{sessionId}/start, stop, and DELETE /sessions/{sessionId} also answer 503 when the database cannot check or claim session ownership (nothing was started, stopped, or deleted; retry)
503 Service UnavailableDatabase did not answer a session lifecycle requestSince v0.31.0, POST /sessions/{sessionId}/stop, logout and force-kill also answer 503 when the database does not answer the read of the session, stop and DELETE /sessions/{sessionId} when it does not answer the write that records the stop or delete, and DELETE when it does not answer the read of the session it makes once it holds its claim; these answered 500 before. Nothing was stopped, logged out, killed or deleted. A record the database did not confirm may have been written, so repeating the request is safe
503 Service UnavailableS3 media download limit reachedOn S3 storage, since v0.27.0: GET /sessions/{sessionId}/messages/{messageId}/media caps concurrent S3 downloads at 50 and answers 503 with Retry-After: 1 when 50 are already open
503 Service UnavailableVideo sticker conversion unavailablePOST /sessions/{sessionId}/messages/send-sticker on whatsapp-web.js, since v0.31.0: the ffmpeg of the host is missing or cannot run the conversion of a video. Nothing was sent, and the reason is in the gateway log. A video that ffmpeg itself refuses (corrupt, or a codec or type it cannot read) is a 400
503 Service UnavailableSearch provider did not answerGET /api/search only, and only while a plugin search provider is active: its worker is not running, the query passed the 10-second search timeout, or the handler reported a failure. Retryable. The built-in provider never answers this
504 Gateway TimeoutStart or forward timed outPOST /sessions/{sessionId}/start: the engine did not finish starting within its timeout, because WhatsApp Web or the network is unreachable, a browser stalled or hit a resource limit, or, on whatsapp-web.js, the session proxyUrl is unreachable or WhatsApp Web's authentication wait ran out. The engine is torn down and the start can be retried; this body carries message but no error field. For a slow first boot, raise WWEBJS_AUTH_TIMEOUT_MS. On a deployment that routes requests between nodes (NODE_URL), any session-scoped request forwarded to the owning node also answers 504, with error: "Gateway Timeout", when the owner does not answer within SESSION_PROXY_TIMEOUT_MS; the owner may already have carried the request out. A forward that fails after it was sent answers 502, and one that never reached the owner 503. See Horizontal scaling
Rate limiting

A global rate limiter applies per client IP and per route across three named throttlers — short (10 requests / 1 s), medium (100 / 60 s), and long (1000 / 1 h). Exceeding any one of them returns 429 Too Many Requests. Since v0.23.6 an IPv6 client is keyed on its /64, so every client in one /64 shares each bucket, and so do the pre-auth limits on MCP, Bull Board and the WebSocket and the per-IP share of the unkeyed upload body budget (a request with an active API key is charged to the key instead).

Rate-limit state rides in headers suffixed with the throttler name. The unsuffixed X-RateLimit-* variants are never sent; the one unsuffixed header is Retry-After on a 429 (v0.23.6+):

HeaderMeaning
X-RateLimit-Limit-<name>Budget for that window, e.g. X-RateLimit-Limit-short: 10
X-RateLimit-Remaining-<name>Requests left in the current window
X-RateLimit-Reset-<name>Seconds until the window resets
Retry-After-<name>On 429, seconds to wait before retrying; the suffix names the window that shed the request
Retry-AfterOn 429 (v0.23.6+), the same value under the standard name, which is the one HTTP clients read. Before v0.23.6 only the suffixed header was sent, which no HTTP client reads. A client that honours Retry-After now waits for it, up to an hour when the long window shed the request

The integration ingress routes carry two throttlers of their own, instance and ingress-ip, with the same header pattern, plain Retry-After included. All these headers are exposed through CORS, so browser clients can read them. The limits are configurable through environment variables, and the health and metrics routes are exempt. See the configuration reference for the env overrides.

The exempt set is exactly four routes: GET /api/health, GET /api/health/live, GET /api/health/ready, and GET /api/metrics. Exempt means no throttler runs on them and no rate-limit headers are sent (v0.16.0+). All four are also public — no X-API-Key — so if the port is reachable from the internet, rate-limit them at your reverse proxy; nothing in the gateway limits them, apart from the failed-token limit on GET /api/metrics below. GET /api/metrics is separately gated by METRICS_TOKEN: it answers 404 while that variable is unset and 401 when it is set and the bearer token is missing or wrong. Since v0.26.0 a production boot refuses a METRICS_TOKEN that is the .env.example placeholder or a known weak value such as test or change-me, since the endpoint is public; set a long random token, or leave it unset to keep the endpoint disabled. Since v0.23.7 it also answers 429 once a client has sent 10 failed tokens within a minute. The check runs before the token is compared, so while that window is spent even the correct token gets 429 until the window slides; a successful scrape does not spend it. See deployment for the proxy setup.

Session not connected and 409​

Every engine method checks that a live, connected engine is there before it touches the socket or the page, and answers 409 Conflict when it is not. GET /sessions/{sessionId}/qr is not one of them: it reads the QR the engine has already cached rather than querying WhatsApp, so a session that is not at qr_ready answers 400 there, and since v0.23.3 the route declares no 409 at all.

409 is narrower than it first looks, because a session that is not connected can fail in two different places:

What is trueWhere it is caughtStatus
The session has never been started, so no engine exists for itThe service, before the engine is fetched400, "Session is not started"
An engine exists but is not ready — still initializing, reconnecting, or disconnectedThe engine itself, on entry to the method409

The two are sequential rather than alternative, so an operation that can answer one can usually answer the other, and most engine routes declare both: 400 means nothing has been started, 409 means something is running but cannot talk to WhatsApp yet. Neither sent anything, and neither changed anything (apart from the unknown-outcome 409 described below) — the difference is only whether you need to start the session or wait for it.

Other operations answer 409 for an unrelated reason, creating a session whose name is taken, installing a plugin that is already installed or changing one that is still being restored after startup (v0.26.0+), importing data that would orphan a running engine, revoking the last usable admin key or updating it so it no longer counts as one (a demotion, an expiry, an allowedSessions list, or, since v0.23.6, an allowedChats list), or starting a session while a name-keyed credential teardown is still in flight. Those are conflicts of state rather than of connectivity, and idempotent sends also use 409 for retry state. Read the response code and route description before deciding whether another request is safe.

Note that starting an already-running session is a 400, not a 409 — the guard runs before any conflict fence is reached.

Note

A connectivity 409 means the engine was not ready, so the call did not reach WhatsApp. The exception is a send that was already under way: on whatsapp-web.js a page reload that cuts a send, reply, forward or status post once the message was handed to the page (a reload that cuts the chat read in front of a reply or forward gets the coded 409 instead, and nothing was sent), and on Baileys a connection replaced or stopped while a send, status post or status delete, reaction, edit, message delete for everyone or pin is being written, answer a 409 with no code whose message says the outcome is unknown: the message or status may or may not have gone out, or the change been applied (v0.31.0+). Check the chat before sending it again; a retry of a keyed send answers IDEMPOTENCY_OUTCOME_UNKNOWN. Other conflicts, especially IDEMPOTENCY_OUTCOME_UNKNOWN, leave the send outcome unresolved. A 503 can mean a refused request during shutdown or overload, a failed media fetch or recipient lookup before sending, or a WhatsApp operation whose confirmation never arrived. Read the route and error code; status alone does not establish whether a write happened. For the twelve supported send routes, retain and reuse the same Idempotency-Key when retrying.

Transport failures and 503​

A route that talks to WhatsApp can get no answer at all: the socket is up, the query goes out, and nothing comes back. Since v0.14.5 that outcome has a status of its own. For a timed-out engine query, 503 Service Unavailable means the gateway stopped waiting for a confirmation that never came, it is a statement about the query, not about the resource.

Every engine call whose outcome cannot be read from its own return value now runs against a 30-second request budget, and the affected operations declare 503 in the contract. Other routes answer 503 when the whatsapp-web.js page connection dies mid-request: there is no deadline to expire, only a connection that stopped answering. Listing a session's chats and listing the chats that carry a label have declared it since v0.15.0, and the label-chats behaviour predates the declaration. v0.23.4 declared it on thirteen more routes: seven message operations, two contact reads, three label reads and the status delete. All but two of them used to report a dead page as a bare 500; the single-contact read and the status delete already answered 503, and v0.23.4 only declared it. Four declare 503 on their own terms: the readiness probe, the two media-conversion routes, and GET /api/search when its active plugin search provider does not answer. v0.23.6 declared sixteen more: POST /sessions/{sessionId}/pairing-code when its retry budget runs out while WhatsApp Web keeps reloading its QR page, the five media sends and three status media posts when a url fetched through the session's egress proxy fails before any response, and the seven methods of the integration ingress route when a route's session-alive preflight finds no live engine (that one carries Retry-After; since v0.26.0 a route that declares a response contract answers it while its plugin is still being restored after startup too, and a route without one is accepted meanwhile). Later releases declared further route-specific 503s, each with its own reason: an S3 bucket that is unreachable on the three storage routes, a Baileys group or channel create that WhatsApp rate-limited, and a whatsapp-web.js page death or protocol timeout on PUT /sessions/{sessionId}/presence (v0.24.0); a gateway that is shutting down on GET /api/infra/health, POST /api/plugins/{id}/update, send-bulk and start, an engine launch that died during start, and the Baileys recipient lookup on nine send and presence routes (v0.25.0). v0.26.0 declared the Baileys rate-limit and timeout 503 on the send, message-action and status routes, the open-transaction 503 on POST /sessions and the plugin instance delete (SQLite), and the shutdown 503 on the two media-conversion routes; the status table above gives the first two reasons. Read an operation's 503 description in the API reference rather than counting them. Also since v0.23.6, on whatsapp-web.js a browser command that outruns the Puppeteer protocol timeout answers 503 on the group read, the invite preview and join, the chats-by-label read, the single-contact read and the chat actions, where it used to fall through to a false 404, 400 or success: false; each of those routes already declared 503. Since v0.24.0 the same timeout answers 503 on the chat, group and contact list reads, on the mute, unmute, pin and unpin writes themselves, and on PUT /sessions/{sessionId}/presence. Since v0.31.0 the same timeout answers 503, where it answered 500, on more whatsapp-web.js routes: the contact, profile, channel, group-setting and chat label writes, the message reaction, edit, delete, star, pin and vote actions, a status delete, and the reads of channels, labels, a chat's labels, reactions, receipts and history, and of a group's invite code and join requests. Sends, status posts and the other writes keep their answer, apart from the group lookup and the invitation check made before a group write, which answer 503 because nothing was applied. Before v0.14.5, an unanswered query was folded into whatever the engine happened to return, which was usually indistinguishable from a real answer:

RouteWhat an unanswered query used to returnWhat it returns now
GET /sessions/{sessionId}/groups200 with [] — the same body an account in no groups gets503
GET /sessions/{sessionId}/contacts/check/{number}200 with exists: false503
GET /sessions/{sessionId}/contacts/{contactId}/profile-picture200 with url: null — the same body a contact with no picture gets503
Group and profile writes, chat actions, label writes, call rejection on Baileys (on whatsapp-web.js a rejection answered 200 through v0.23.5 and answers 501 since v0.23.6)200, reporting success for a change nothing acknowledged503
Group participant writes — add, remove, promote, demote200 carrying a results array, indistinguishable from a batch nothing acknowledged503
Group metadata reads, channel operations, marking a chat readA bare 500 with the underlying message discarded503

On the four participant writes, 503 is the one status that separates WhatsApp never answered from the per-participant refusals a 200 reports inside results. A batch where some participants were refused is a successful call with a mixed outcome; read results for it. A 503 says the batch has no outcome to read.

Reads and writes that converge on the same state can be retried after a 503. A response from a send does not establish that nothing was delivered: preserve the send key or inspect the chat before deciding to send again. Honor Retry-After when present, including overload and ingress preflight refusals. A request rejected during teardown can be retried against a ready instance.

Group creation, channel creation, media sends, status posts and call-link creation do not impose an engine response timeout that would invite duplicate writes. Media URL fetches and Baileys recipient lookups can fail before sending, while routing, hooks or shutdown can also produce a failure outside the engine call itself. Treat any non-2xx response from a non-idempotent write as an outcome to verify. An HTTP status alone is not a receipt; use the send retry contract where it is supported.

Breaking in v0.14.5: a dead connection is no longer reported as a client error

On the Baileys engine, the helper that decided whether a failure was a refusal by WhatsApp or a death of the transport matched every failure, so a closed socket was reported as a permissions or input problem:

  • the group and channel writes answered 403 admin rights or permissions may be missing,
  • POST /sessions/{sessionId}/groups/join answered 400 — the same "invite code may be invalid" as a genuinely bad code,
  • GET /sessions/{sessionId}/groups/join-info answered 404.

A transport failure now propagates as a 5xx instead. This changes the status code you receive for those cases. Keep your existing 4xx handling for genuine refusals and treat 5xx as a retryable transport failure. A caller that retried on 403 to work around this should stop doing so, and one that surfaced "invalid invite code" to an end user will now correctly report an outage. The three profile writes were never affected — they do not go through that helper.

Breaking in v0.15.0: engine operations during a WhatsApp Web page reload answer 409 instead of 500

WhatsApp Web periodically reloads its own page (~5 minutes after a fresh pairing, among other triggers). During the bounded window while whatsapp-web.js re-injects, every engine route now answers a retryable 409 naming the reload. Before v0.15.0, most routes surfaced raw TypeError 500s, and the five chat write endpoints — read, unread, archive (unarchive is the same endpoint with archive: false), typing and clear — answered 200 {success:false}. Retry on a timer rather than waiting for a ready event: the session never leaves ready across the reload, so no session.status event is emitted. The window ends 60 s after the last navigation (NAVIGATION_REINJECT_GRACE_MS, a build-time constant of 60000 ms, not configurable) and 180 s after the first navigation of a reload at the latest; a page that a liveness probe has found still without whatsapp-web.js keeps answering the 409 until a later probe finds it recovered or the liveness watchdog reconnects the session. The window can last a few minutes. Since v0.31.0 the body carries code: ENGINE_PAGE_RELOADING and retryAfterSeconds, the interval in seconds to ask again at, so retry on that interval — see troubleshooting for the retry shape. Match on the code, not on the message: the text changed in v0.31.0 from Retry in a few seconds. to Retry every few seconds: this can last a few minutes. The send breaker counts only failures that reached WhatsApp, so a typed 4xx such as this 409 does not add to it; that exemption dates from v0.14.0, when the breaker shipped, and what changed in v0.15.0 is the status the reload produces. A read already running when the page reloaded could still die with Puppeteer's navigation error before the window began and answer a bare 500, or a false 404 or 400 for a group, contact, label or invite that exists; since v0.26.0 it answers the same 409. Accepting a group invite is the exception: it answers 503, because the join may have landed.

Breaking in v0.16.0: creating a group answers 501 on whatsapp-web.js

POST /sessions/{sessionId}/groups now refuses up front on the whatsapp-web.js engine — which is the default, the one you get with ENGINE_TYPE unset — with 501 and the message Operation not supported by the active engine: createGroup. Before v0.16.0 the creation was attempted and failed as an opaque 500: whatsapp-web.js still declares createGroup, but its page code reaches a WhatsApp Web internal that no longer exists, so every call already failed. The practical impact is therefore smaller than it reads — nothing that used to work stopped working, the failure just became a stated refusal instead of an unexplained server error. Action required: create groups through the Baileys engine (ENGINE_TYPE=baileys), which is unaffected. The route, its body, and its Baileys behaviour are unchanged. The readiness check still runs first, so a whatsapp-web.js session that is not yet ready answers 409 rather than 501.

A worked request​

Send a text message and read the response:

curl -X POST http://localhost:2785/api/sessions/SESSION_ID/messages/send-text \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "chatId": "628123456789@c.us", "text": "Hello from OpenWA!" }'
{ "messageId": "true_628123456789@c.us_3EB0ABCD", "timestamp": 1719312000 }

The response is the raw payload: messageId is the engine's WhatsApp message id, and timestamp is epoch seconds.

Request lifecycle​

Every authenticated request passes the same guards before reaching a handler:

Next steps​

  • Browse every endpoint, field, and schema in the API reference.
  • Get a key and connect a session in the quick start.
  • Drive the API from JavaScript with the SDK.