n8n Node Reference
Exact field-level reference for the two nodes in the @rmyndharis/n8n-nodes-openwa package (v1.8.1): OpenWA (an action node) and OpenWA Trigger (a webhook trigger node). Use it to look up every resource, operation, field, and event, plus the HMAC signature the trigger verifies.
Nineteen operations answer a bare JSON array. On node version 2, the version a newly added node gets, each row becomes its own item, so {{ $json.id }} reads a row directly and an empty list emits zero items, which stops the next node unless Always Output Data is on. A node saved on any release up to and including 1.0.0 stays on node version 1 across the package upgrade and keeps the whole array on a single item, so an existing {{ $json[0].id }} expression still works there. A node added while on 1.0.0 carries version 1 too, so it returns to the whole array on upgrade; delete and re-add it to move it to version 2.
See Output and error handling for the affected operations, the ones that keep their shape on both versions, and what each workflow pattern becomes on version 2.
For installation and a first workflow, see the n8n integration guide. For the underlying HTTP API each operation calls, see the API Reference.
Package overview
| Node | n8n type | Direction | Purpose |
|---|---|---|---|
| OpenWA | openWa | Action | Send messages and manage sessions, chats, contacts, groups, labels, templates, status, channels, keys, and webhooks |
| OpenWA Trigger | openWaTrigger | Trigger | Start a workflow when a subscribed event arrives |
Both nodes use the openWaApi credential and call your OpenWA server's /api endpoints.
Credential: OpenWA API
Both nodes require an OpenWA API credential with two fields.
| Field | Required | Description |
|---|---|---|
| Server URL | Yes | Base URL with no /api suffix, for example http://localhost:2785 or https://wa.example.com. The node appends /api/... itself. The nodes drop surrounding whitespace and trailing slashes (before 1.2.1, one trailing slash and no whitespace), and n8n's credential test drops a trailing slash too, so a trailing slash does not fail the test. |
| API Key | Yes | Sent as the X-API-Key header on every request. Get it from your OpenWA dashboard. |
The credential test issues an authenticated GET /api/sessions, so an invalid key fails at save time. To create the key, see Authentication.
A key restricted to selected chats (allowedChats, server v0.23.6+) fails the credential test even when it is valid. GET /api/sessions (the test and the Session Name or ID dropdown), the Label and Template dropdowns, and Trigger webhook registration remain closed. n8n still saves a credential whose test fails, so supply the session UUID from an expression for the open operations below. Gateway v0.23.6 filters the Chat dropdown to allowed chats, and v0.24.0 the Contact and Group dropdowns; loading them still requires that session UUID.
- Session: Get Status.
- Message: every send, Reply, React, Forward, Edit, Delete, Pin, Unpin, Star, Vote Poll, Click Button, Get History, Get Reactions, Get Receipts, Get Media and Send Bulk. Since server v0.24.0, List is also open when Options > Chat Name or ID names an allowed chat; omitting it answers
403. Get Batch Status and Cancel Batch stay closed. - Every Chat operation. List returns only allowed chats, filtered before pagination.
- Contact: Get Info, Get Phone, Get Profile Picture, Save, Delete, Block and Unblock; since v0.24.0, List returns only allowed contacts.
- Group: Update Subject, Update Description, Leave, Get Picture, Set Picture and Delete Picture; since v0.24.0, List returns only allowed groups. Server v0.25.0 also opens Get, Get Settings and Update Settings for allowed groups, and server v0.27.0 opens Set Member Label.
- Label: Get for Chat, Add to Chat and Remove From Chat; since v0.24.0, Get Chats returns only allowed chats. The label dropdown remains closed, so supply its id from an expression.
- Presence: Subscribe and Get.
- System: Search on the built-in provider since server v0.25.0, with results scoped before totals and pagination. Plugin search remains forbidden.
Operations that name a chat answer 403 for one outside the key's list (Forward checks both chats, Send Bulk every recipient). A send carrying Quoted Message ID is still refused on every operation except Reply, which resolves the quote inside the authorized chat. Contact Check Exists and Get LID, and group participant, membership-request and invite-code operations remain closed. The Observability checks need no key and are unaffected.
OpenWA (action node)
Package 1.8.1 covers the nineteen resources below. Select a
Resource, then an Operation; the visible fields change with each operation.
Most operations take a Session Name or ID. It is a dropdown: the node calls GET /api/sessions
with your credential and lists each session as name (id), storing the session's UUID. The stored
value is a plain string, so an expression can supply an id instead of picking one. The same pattern
backs the Chat, Contact, Group, Label, Template, Channel, and Webhook ID
fields, each loading from its own listing endpoint once a session is chosen, and the API Key
field, which is not session-scoped. The session, chat, contact, and group loaders fetch one page of
up to 1000 entries — beyond that, set the field from an expression. Since package 1.8.0 the Chat Name or ID
dropdown lists a chat whose name is blank as phone (id) when the gateway reports a phone for it (a
Baileys chat under a privacy id, server v0.31.0+); without a phone it is listed by its id alone, as before.
The Observability and API Key resources have no Session ID at all; on System it appears only for Get Session Stats, and on Webhook it is hidden for List All, Get Delivery Failures and Redrive Delivery Failures.
| Resource | Operation | Method + path |
|---|---|---|
| Session | Create | POST /api/sessions |
| Session | Start | POST /api/sessions/{sessionId}/start |
| Session | Stop | POST /api/sessions/{sessionId}/stop |
| Session | Force Kill | POST /api/sessions/{sessionId}/force-kill |
| Session | Delete | DELETE /api/sessions/{sessionId} |
| Session | Get QR | GET /api/sessions/{sessionId}/qr |
| Session | Request Pairing Code | POST /api/sessions/{sessionId}/pairing-code |
| Session | Get Status | GET /api/sessions/{sessionId} |
| Session | List All | GET /api/sessions |
| Session | Get Stats Overview | GET /api/sessions/stats/overview |
| Session | Log Out | POST /api/sessions/{sessionId}/logout |
| Session | Get Config | GET /api/sessions/{sessionId}/config |
| Session | Update Config | PATCH /api/sessions/{sessionId}/config |
| Session | Get Proxy | GET /api/sessions/{sessionId}/proxy |
| Session | Update Proxy | PATCH /api/sessions/{sessionId}/proxy |
| Message | Send Text | POST /api/sessions/{sessionId}/messages/send-text |
| Message | Send Image | POST /api/sessions/{sessionId}/messages/send-image |
| Message | Send Video | POST /api/sessions/{sessionId}/messages/send-video |
| Message | Send Audio | POST /api/sessions/{sessionId}/messages/send-audio |
| Message | Send Document | POST /api/sessions/{sessionId}/messages/send-document |
| Message | Send Sticker | POST /api/sessions/{sessionId}/messages/send-sticker |
| Message | Send Location | POST /api/sessions/{sessionId}/messages/send-location |
| Message | Send Contact | POST /api/sessions/{sessionId}/messages/send-contact |
| Message | Send Poll | POST /api/sessions/{sessionId}/messages/send-poll |
| Message | Send Template | POST /api/sessions/{sessionId}/messages/send-template |
| Message | Send Bulk | POST /api/sessions/{sessionId}/messages/send-bulk |
| Message | Get Batch Status | GET /api/sessions/{sessionId}/messages/batch/{batchId} |
| Message | Cancel Batch | POST /api/sessions/{sessionId}/messages/batch/{batchId}/cancel |
| Message | Reply | POST /api/sessions/{sessionId}/messages/reply |
| Message | React | POST /api/sessions/{sessionId}/messages/react |
| Message | Edit | POST /api/sessions/{sessionId}/messages/edit |
| Message | Delete | POST /api/sessions/{sessionId}/messages/delete |
| Message | Forward | POST /api/sessions/{sessionId}/messages/forward |
| Message | List | GET /api/sessions/{sessionId}/messages |
| Message | Get History | GET /api/sessions/{sessionId}/messages/{chatId}/history |
| Message | Get Reactions | GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/reactions |
| Message | Get Receipts | GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/receipts |
| Message | Get Media | GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/media |
| Message | Pin | POST /api/sessions/{sessionId}/messages/pin |
| Message | Unpin | POST /api/sessions/{sessionId}/messages/unpin |
| Message | Star | POST /api/sessions/{sessionId}/messages/star |
| Message | Vote Poll | POST /api/sessions/{sessionId}/messages/vote-poll |
| Message | Click Button | POST /api/sessions/{sessionId}/messages/click-button |
| Message | Send Product | POST /api/sessions/{sessionId}/messages/send-product |
| Contact | Check Exists | GET /api/sessions/{sessionId}/contacts/check/{phoneNumber} |
| Contact | Get Info | GET /api/sessions/{sessionId}/contacts/{contactId} |
| Contact | Get LID | GET /api/sessions/{sessionId}/contacts/{phoneNumber}/lid |
| Contact | Get Phone | GET /api/sessions/{sessionId}/contacts/{contactId}/phone |
| Contact | Get Profile Picture | GET /api/sessions/{sessionId}/contacts/{contactId}/profile-picture |
| Contact | Get Profile Pictures | GET /api/sessions/{sessionId}/contacts/profile-pictures?ids= |
| Contact | List | GET /api/sessions/{sessionId}/contacts |
| Contact | List Blocked | GET /api/sessions/{sessionId}/contacts/blocked |
| Contact | Save | PUT /api/sessions/{sessionId}/contacts/{contactId} |
| Contact | Delete | DELETE /api/sessions/{sessionId}/contacts/{contactId} |
| Contact | Block | POST /api/sessions/{sessionId}/contacts/{contactId}/block |
| Contact | Unblock | DELETE /api/sessions/{sessionId}/contacts/{contactId}/block |
| Chat | List | GET /api/sessions/{sessionId}/chats |
| Chat | Mark Read | POST /api/sessions/{sessionId}/chats/read |
| Chat | Mark Unread | POST /api/sessions/{sessionId}/chats/unread |
| Chat | Delete | POST /api/sessions/{sessionId}/chats/delete |
| Chat | Clear Messages | DELETE /api/sessions/{sessionId}/chats/{chatId}/messages |
| Chat | Archive | POST /api/sessions/{sessionId}/chats/archive |
| Chat | Pin | POST /api/sessions/{sessionId}/chats/pin |
| Chat | Mute | POST /api/sessions/{sessionId}/chats/mute |
| Chat | Set State | POST /api/sessions/{sessionId}/chats/typing |
| Group | List | GET /api/sessions/{sessionId}/groups |
| Group | Create | POST /api/sessions/{sessionId}/groups |
| Group | Join | POST /api/sessions/{sessionId}/groups/join |
| Group | Get Join Info | GET /api/sessions/{sessionId}/groups/join-info?code= |
| Group | Get | GET /api/sessions/{sessionId}/groups/{groupId} |
| Group | Leave | POST /api/sessions/{sessionId}/groups/{groupId}/leave |
| Group | Add Participants | POST /api/sessions/{sessionId}/groups/{groupId}/participants |
| Group | Remove Participants | DELETE /api/sessions/{sessionId}/groups/{groupId}/participants |
| Group | Promote Participants | POST /api/sessions/{sessionId}/groups/{groupId}/participants/promote |
| Group | Demote Participants | POST /api/sessions/{sessionId}/groups/{groupId}/participants/demote |
| Group | Update Subject | PUT /api/sessions/{sessionId}/groups/{groupId}/subject |
| Group | Update Description | PUT /api/sessions/{sessionId}/groups/{groupId}/description |
| Group | Set Member Label | PUT /api/sessions/{sessionId}/groups/{groupId}/member-label |
| Group | Get Settings | GET /api/sessions/{sessionId}/groups/{groupId}/settings |
| Group | Update Settings | PUT /api/sessions/{sessionId}/groups/{groupId}/settings |
| Group | Get Invite Code | GET /api/sessions/{sessionId}/groups/{groupId}/invite-code |
| Group | Revoke Invite Code | POST /api/sessions/{sessionId}/groups/{groupId}/invite-code/revoke |
| Group | Get Membership Requests | GET /api/sessions/{sessionId}/groups/{groupId}/membership-requests |
| Group | Approve Membership Requests | POST /api/sessions/{sessionId}/groups/{groupId}/membership-requests/approve |
| Group | Reject Membership Requests | POST /api/sessions/{sessionId}/groups/{groupId}/membership-requests/reject |
| Group | Get Picture | GET /api/sessions/{sessionId}/groups/{groupId}/picture |
| Group | Set Picture | PUT /api/sessions/{sessionId}/groups/{groupId}/picture |
| Group | Delete Picture | DELETE /api/sessions/{sessionId}/groups/{groupId}/picture |
| Profile | Set Name | PUT /api/sessions/{sessionId}/profile/name |
| Profile | Set Status | PUT /api/sessions/{sessionId}/profile/status |
| Profile | Set Picture | PUT /api/sessions/{sessionId}/profile/picture |
| Profile | Delete Picture | DELETE /api/sessions/{sessionId}/profile/picture |
| Label | List | GET /api/sessions/{sessionId}/labels |
| Label | Get | GET /api/sessions/{sessionId}/labels/{labelId} |
| Label | Create or Update | PUT /api/sessions/{sessionId}/labels/{labelId} |
| Label | Delete | DELETE /api/sessions/{sessionId}/labels/{labelId} |
| Label | Get Chats | GET /api/sessions/{sessionId}/labels/{labelId}/chats |
| Label | Get for Chat | GET /api/sessions/{sessionId}/labels/chat/{chatId} |
| Label | Add to Chat | POST /api/sessions/{sessionId}/labels/chat/{chatId} |
| Label | Remove From Chat | DELETE /api/sessions/{sessionId}/labels/chat/{chatId}/{labelId} |
| Status | List | GET /api/sessions/{sessionId}/status |
| Status | Get by Contact | GET /api/sessions/{sessionId}/status/{contactId} |
| Status | Get Media | GET /api/sessions/{sessionId}/status/{statusId}/media |
| Status | Delete | DELETE /api/sessions/{sessionId}/status/{statusId} |
| Status | Send Text | POST /api/sessions/{sessionId}/status/send-text |
| Status | Send Image | POST /api/sessions/{sessionId}/status/send-image |
| Status | Send Video | POST /api/sessions/{sessionId}/status/send-video |
| Status | Send Voice | POST /api/sessions/{sessionId}/status/send-voice |
| Template | List | GET /api/sessions/{sessionId}/templates |
| Template | Create | POST /api/sessions/{sessionId}/templates |
| Template | Get | GET /api/sessions/{sessionId}/templates/{templateId} |
| Template | Update | PUT /api/sessions/{sessionId}/templates/{templateId} |
| Template | Delete | DELETE /api/sessions/{sessionId}/templates/{templateId} |
| Channel | List | GET /api/sessions/{sessionId}/channels |
| Channel | Get | GET /api/sessions/{sessionId}/channels/{channelId} |
| Channel | Get Messages | GET /api/sessions/{sessionId}/channels/{channelId}/messages |
| Channel | Create | POST /api/sessions/{sessionId}/channels |
| Channel | Subscribe | POST /api/sessions/{sessionId}/channels/subscribe |
| Channel | Unsubscribe | DELETE /api/sessions/{sessionId}/channels/{channelId} |
| Channel | Delete | POST /api/sessions/{sessionId}/channels/{channelId}/delete |
| Channel | Mute | POST /api/sessions/{sessionId}/channels/{channelId}/mute |
| Channel | Demote Admin | POST /api/sessions/{sessionId}/channels/{channelId}/admins/demote |
| Channel | Transfer Ownership | POST /api/sessions/{sessionId}/channels/{channelId}/owner/transfer |
| Call | Reject | POST /api/sessions/{sessionId}/calls/{callId}/reject |
| Call | Create Link | POST /api/sessions/{sessionId}/calls/link |
| Observability | Check | GET /api/health |
| Observability | Check Liveness | GET /api/health/live |
| Observability | Check Readiness | GET /api/health/ready |
| System | Get Settings | GET /api/settings |
| System | Get Stats Overview | GET /api/stats/overview |
| System | Get Message Stats | GET /api/stats/messages |
| System | Get Session Stats | GET /api/stats/sessions/{sessionId} |
| System | Get Audit Log | GET /api/audit |
| System | Search | GET /api/search |
| API Key | List | GET /api/auth/api-keys |
| API Key | Create | POST /api/auth/api-keys |
| API Key | Get | GET /api/auth/api-keys/{keyId} |
| API Key | Update | PUT /api/auth/api-keys/{keyId} |
| API Key | Revoke | POST /api/auth/api-keys/{keyId}/revoke |
| API Key | Delete | DELETE /api/auth/api-keys/{keyId} |
| API Key | Validate | POST /api/auth/validate |
| Webhook | Create | POST /api/sessions/{sessionId}/webhooks |
| Webhook | Get | GET /api/sessions/{sessionId}/webhooks/{webhookId} |
| Webhook | List | GET /api/sessions/{sessionId}/webhooks |
| Webhook | Update | PUT /api/sessions/{sessionId}/webhooks/{webhookId} |
| Webhook | Delete | DELETE /api/sessions/{sessionId}/webhooks/{webhookId} |
| Webhook | Test | POST /api/sessions/{sessionId}/webhooks/{webhookId}/test |
| Webhook | List All | GET /api/webhooks |
| Webhook | Get Delivery Failures | GET /api/webhooks/delivery-failures |
| Webhook | Redrive Delivery Failures | POST /api/webhooks/delivery-failures/redrive |
| Automation Rule | List | GET /api/sessions/{sessionId}/automation-rules |
| Automation Rule | Create | POST /api/sessions/{sessionId}/automation-rules |
| Automation Rule | Get | GET /api/sessions/{sessionId}/automation-rules/{ruleId} |
| Automation Rule | Update | PUT /api/sessions/{sessionId}/automation-rules/{ruleId} |
| Automation Rule | Delete | DELETE /api/sessions/{sessionId}/automation-rules/{ruleId} |
| Catalog | Get | GET /api/sessions/{sessionId}/catalog |
| Catalog | List Products | GET /api/sessions/{sessionId}/catalog/products |
| Catalog | Get Product | GET /api/sessions/{sessionId}/catalog/products/{productId} |
| Media | Check Availability | GET /api/sessions/{sessionId}/media/convert |
| Media | Convert to Voice Note | POST /api/sessions/{sessionId}/media/convert/voice |
| Media | Convert to Video | POST /api/sessions/{sessionId}/media/convert/video |
| Presence | Subscribe | POST /api/sessions/{sessionId}/presence/subscribe |
| Presence | Get | GET /api/sessions/{sessionId}/presence/{chatId} |
| Presence | Set Own Presence | PUT /api/sessions/{sessionId}/presence |
Values that land in a URL path — Session ID, Webhook ID, Label ID, Rule ID, Status ID,
Template ID, Call ID, API key ID — are sanitized before use: they cannot be empty and cannot contain
.., /, or \. A value that violates this fails the item with a clear error rather than building
a malformed URL. Values that legitimately carry such characters are checked for emptiness and
URL-encoded instead: the WhatsApp JIDs (chat, contact, group, channel), the Message ID a reaction, receipt or
media read addresses, the Batch ID (Send Bulk accepts one with such characters in it), and the
Product ID from a catalog listing. Whatever the ID, a path segment that is . or .. (including one split by %2F or %5C since package 1.5.0) is
refused before the request is sent.
Send Catalog and PUT /api/settings were removed from the server in v0.19.0 — both had answered 501 since they shipped. Settings are environment-derived and read-only at runtime, so System exposes only a read, and /api/metrics authenticates with its own bearer token rather than the X-API-Key this credential carries. The Catalog resource reads a Baileys session's catalog; on a whatsapp-web.js session every catalog operation answers 501. Sending a product from that catalog is Message → Send Product, not a Catalog operation.
Separately, the node is not a full mirror of the API. Five server areas have no resource: plugin
management (/api/plugins/*), the infrastructure routes (/api/infra/*), Integration
Fabric instance management (/api/integration/*), the Prometheus metrics scrape, and the
plugin ingress receiver (/api/ingress/*). Within the resources it does cover, the operation
tables above are the authoritative list: an operation absent from them is absent from the node.
Reach plugin management, the infrastructure routes (apart from the public GET /api/infra/health)
and Integration Fabric with n8n's HTTP Request node using the same credential and an ADMIN
key. The metrics scrape takes its own METRICS_TOKEN bearer instead, and the ingress receiver is
public and verifies the provider's signature, so the credential applies to neither.
The action node can be attached to an AI agent as a tool; the Trigger cannot. You choose the resource
and operation when you build the workflow, and the model fills only the fields you map to
$fromAI().
- Give the tool a key with the lowest role it needs, restricted with
allowedSessionsandallowedChats. Set Session Name or ID yourself rather than leaving it to the model, and do not map the target of a destructive operation (Session → Delete, Group → Remove Participants, Webhook → Create or Update) to$fromAI(). - Everything an operation returns reaches the model and is stored in the execution data. API Key → Create returns the new key in plaintext, and a key created without a Role is an OPERATOR key. Session → Get QR, Request Pairing Code and Group → Get Invite Code return codes that grant access.
- A webhook secret, webhook headers and a Proxy URL that carries credentials are saved as ordinary node parameters, so they appear in the workflow JSON, in exports and in execution snapshots.
Media source model
Every operation that carries media — Message → Send Image, Send Video, Send Audio, Send Document and Send Sticker; Profile → Set Picture; Group → Set Picture; and Status → Send Image, Send Video and Send Voice — shares one source model. A Source field offers three ways to supply the bytes, and the remaining fields follow from it:
| Source | Extra fields | Request fields sent |
|---|---|---|
| Binary Data | Binary Property (default data) | base64 (the buffer encoded) and mimetype, read from the binary metadata |
| URL | (the media URL field) | url |
| Base64 | Base64 Data, MIME Type | base64 and mimetype (the MIME Type field) |
Two of them differ in their labels. Group → Set Picture and Status → Send Voice name the
first option Binary rather than Binary Data, default to it rather than to URL, and call the
field that follows Input Binary Field rather than Binary Property. Everywhere else the option
reads Binary Data, the default is URL, and the field is Binary Property. Media → Convert
follows the same shorter naming; see Media resource.
When a binary item carries no MIME type of its own, the node falls back to a per-kind default:
application/octet-stream for images, video, and documents, audio/ogg; codecs=opus for audio and
status voice notes, image/webp for stickers, image/jpeg for profile pictures, group pictures and
status images, and video/mp4 for status video.
The URL source is fetched by the gateway, not by n8n, and a redirect is never followed. Since
server v0.23.6 a URL that is not an absolute http:// or https:// URL is refused with 400, and
one the gateway cannot fetch (a 4xx or 5xx answer, a timeout, a failed connection) answers 400, or
413 when the download exceeds the media cap, where a failed fetch used to answer 500. A URL that
carries a user name or password is refused with 400 before any connection is made, on every
operation that fetches one (since server v0.31.0; it answered 500). A URL that redirects, whose host
does not resolve, or that points at a private or internal address, which includes the documentation
address ranges such as 203.0.113.0/24 since v0.31.0, answers 400 with
Destination address is not allowed on the Message sends, and since v0.31.0 on Status posts and the
two picture operations, Profile → Set Picture and Group → Set Picture, which answered 500.
Before v0.23.6 those two picture operations refused a single-label host name, such as localhost,
with 400 before any fetch. Also since v0.23.6, a session with an egress proxy has the URL fetched
through that proxy on both engines, where it used to be fetched from the
gateway's own address; an operator whose proxy reaches only WhatsApp can restore the direct fetch with
SESSION_PROXY_URL_FETCH=false (see Configuration). A fetch through
the proxy that fails before any response answers 503 rather than 400, and is worth retrying.
OpenWA rejects base64 media without a mimetype. The Binary Data source fills it in from the
binary metadata and the URL source needs nothing extra, but the Base64 source requires you to
set the MIME Type field.
List fields
Several fields take a list: Mentions, Participants, Recipients, Contact IDs, poll
Options, Allowed IPs, and Allowed Sessions. Each is a plain string field rather than a
fixed set of rows, so it accepts three shapes: a comma- or newline-separated list typed by hand, a
pasted JSON array, or an expression resolving to an array. Blank entries are dropped. A list in one
pair of brackets, with a comma or a line break inside, that is not valid JSON, such as ['a', 'b'],
fails the item in each of these fields (and in Selected Options, Failure IDs and Message IDs) instead
of posting the brackets and quotes as part of the entries.
Session resource
Session operations address a session by its UUID. Create, List All, and Get Stats Overview take no Session ID.
| Operation | Fields | Notes |
|---|---|---|
| Create | Session Name, Session Config (JSON), Proxy URL | Session Name is required: 3–50 characters, letters, numbers, and hyphens only. Session Config is an optional JSON object, for example {"autoRejectCalls":true} (at most 16,384 bytes when serialized as JSON, checked locally since package 1.5.0 and on the gateway since server v0.27.1); a non-object value fails the item. Proxy URL is optional and validated the same way Update Proxy validates it, but a blank value is omitted rather than sent, since the server's DTO reads a blank as a malformed URL. Setting a Proxy URL needs an ADMIN key since server v0.24.0; without one, an OPERATOR key is enough. Returns the new session's UUID. |
| Start | Session Name or ID | Starts the session and connects to WhatsApp. |
| Stop | Session Name or ID | Stops the session and disconnects. |
| Force Kill | Session Name or ID | Force-kills a stuck session's engine. |
| Delete | Session Name or ID | Deletes the session. |
| Get QR | Session Name or ID | Returns the QR code for scanning authentication. |
| Request Pairing Code | Session Name or ID, Phone Number | Phone Number is 6–15 digits in international format (for example 628123456789); the node strips +, spaces, -, and () before validating. Returns an 8-character phone-linking code. Start the session and poll Get Status until status reads qr_ready before requesting a code: an unstarted session answers 400, a started one that has not reached qr_ready answers 409, and one that already reads ready is linked and answers 400. On whatsapp-web.js a 503 (server v0.23.6+; 500 before) means the gateway used up its attempts, usually because WhatsApp Web kept reloading its page, and is retryable. On that engine, request a code only for a number you are prepared to re-link. Since server v0.26.0 a number that is the stored phone of another session on this gateway is refused with 409 and WhatsApp is not asked; before it, such a request has been observed to end with WhatsApp unlinking that device. The gateway cannot see a link made on another gateway or only on the phone, so a request for such a number can still unlink that device. A retry after a 503 carries the same risk, since the timed-out attempt may still have reached WhatsApp. Baileys was not affected in the same tests and accepts the request, since its sessions are companion devices and may share a number. Link by QR when a session of that number must stay up. See Sessions. |
| Get Status | Session Name or ID | Returns the status of one session. |
| List All | Options: Limit (1 to 1000), Offset, Name | Returns every session, paginated. Name returns only the session with exactly that name, case-sensitive, so no match is an empty list (zero items on node version 2). It needs server v0.23.5 or newer: an older server ignores it and returns every session. A blank Name fails the item, because dropping it would list every session. |
| Get Stats Overview | (none) | Overview statistics across all sessions. |
| Log Out | Session Name or ID | Asks WhatsApp to remove this companion device, then tears the engine down. Unlike Stop it needs a live engine, and the session must be paired again afterwards. On Baileys, once WhatsApp acknowledges the unlink, and equally when the phone unlinks the device, the gateway also deletes its stored copies of the session's messages and its chat states (mute, archive, pin): earlier messages still list and search, but Reply, Forward, React, Edit, Delete, Star, Pin, Unpin and Click Button on a message from before the unlink answer 404, and linking the same number again does not bring the copies back. |
| Get Config | Session Name or ID | The session's effective configuration: the four recognised keys, as the engine will apply them (linkPreview, server v0.30.3+, reads null while unset). |
| Update Config | Session Name or ID, Config Fields | A PATCH: only the fields you add are sent, and anything left out keeps its stored value. At least one is required. A field that an expression resolves to nothing fails the item (package 1.2.1) instead of being dropped or sent as a reset. |
| Get Proxy | Session Name or ID | Server v0.23.4 and newer. Reports the scheme, the host and port, and whether credentials are embedded. It never returns the credentials themselves. |
| Update Proxy | Session Name or ID, Proxy URL, Clear Proxy | Server v0.23.4 and newer. Writes the proxy without restarting anything, so a change takes effect on the next Start. Needs an ADMIN key since server v0.24.0 (an OPERATOR key before) and refuses a session-scoped key. |
Session Config on Create takes the same four keys the collection below offers, spelled as JSON:
autoRejectCalls, maxReconnectAttempts, reconnectBaseDelay and linkPreview (a boolean; server
v0.30.3+, an older server stores it and ignores it). Those are the only keys the
server reads. Anything else is stored and ignored, so a misspelled key is accepted silently and
never takes effect. Since server v0.24.0 a maxReconnectAttempts outside 0 to 20, a
reconnectBaseDelay outside 1000 to 300000 or an autoRejectCalls that is not a boolean is refused
at creation with 400, and since v0.30.3 so is a linkPreview that is neither a boolean nor null.
The Config Fields collection on Update Config:
| Field | Type | Notes |
|---|---|---|
| Auto Reject Calls | boolean | Default false. Decline every incoming call automatically. Re-read on each call, so it applies immediately. Baileys only: whatsapp-web.js cannot reject a call, and since server v0.23.6 it logs each auto-reject as failed rather than done. |
| Link Preview | options | Default Engine Default. The default for a Send Text or Send Template that sets neither Link Preview nor a Custom Link Preview; a value on the send wins. Generate a Preview sends true and No Preview sends false (no preview on either engine). Engine Default sends null, which clears the setting, so whatsapp-web.js builds a preview and Baileys sends none (on Send Text the same option sends nothing). On Baileys a preview makes the gateway fetch the first https:// link with a domain-name host in the text before the message is sent, which stalls the send on a slow or dead link. An expression can supply true or false; any other value must be one of the three options, or the item fails. Applies from the next send, with no restart. Server v0.30.3 and newer: an older server refuses the field with 400. |
| Max Reconnect Attempts | number | How many consecutive reconnects to attempt, -1 to 20. -1 means unlimited and is both the default and the only way back to it once a cap is set; the node sends it as the null the server spells unlimited with, and a number below -1 or above 20 fails the item. 0 is a real value meaning the gateway never reconnects, leaving the session down until it is started by hand; on Baileys that covers only a logged-out close (see below). Applies from the next Start, not to a reconnect already under way. |
| Reconnect Base Delay (Ms) | number | Base backoff between the gateway's reconnect attempts, 1000 to 300000, default 5000. On Baileys it applies only to the reconnect after a logged-out close. Applies from the next Start. |
Both reconnect fields bound the gateway's own reconnect: every reconnect on whatsapp-web.js, but on
Baileys only the one after a logged-out close. Baileys retries a transient drop itself, with a fixed
1 s to 60 s backoff and no attempt cap, so on that engine 0 does not keep a session down after a
network drop. A close WhatsApp reports as a replaced connection (another instance took over the
account) or as a rejected account is terminal on Baileys: the session goes to failed, and neither
the engine nor the gateway reconnects it.
Proxy URL is a full URL with its scheme (http, https, socks4 or socks5), at most 255
characters; a value without a scheme or without a host fails the item. Credentials embedded in the
URL work on Baileys over http, https and socks5, but whatsapp-web.js cannot authenticate a SOCKS
proxy. socks4 has no authentication step at all: on Baileys the user name goes out as the connect
request's user id and the password is dropped, which Baileys logs as a warning at Start since server
v0.23.6. Write a literal % in the credentials as %25. Since server v0.23.6 a % that does not
start a valid escape is refused with 400, where it used to be stored and then fail every later Start
with URI malformed. An unreachable proxy does not fail fast: no QR is ever delivered. On
whatsapp-web.js Start times out after about 30 seconds; on Baileys Start succeeds and the session
keeps retrying the connection.
Clear Proxy removes the stored proxy instead of setting one, because the server spells removal as
an explicit null that a text field cannot express. While it is on, Proxy URL is ignored. The node
tests it against true rather than for truthiness, so an expression resolving to the string
"false" does not wipe a working proxy. With the toggle off, a blank Proxy URL fails the item rather
than being sent, which would otherwise turn the PATCH into a no-op read reporting the old proxy as
though it had been written.
Message resource
The twenty-nine message operations share a required Session Name or ID. All of them except
Send Bulk, Get Batch Status, Cancel Batch, Forward, and List also require a
Chat Name or ID — the batch routes are not addressed to one chat, Forward names a source and a
target chat of its own, and List takes an optional chat filter in its options collection. On server v0.24.0 and newer, a chat-restricted key must set Options > Chat Name or ID to an allowed chat; without it, List answers 403.
| Field | Type | Required | Description |
|---|---|---|---|
| Session Name or ID | options | Yes | The session to act through. |
| Chat Name or ID | options | Yes (all except Send Bulk, Get Batch Status, Cancel Batch, Forward, List) | Recipient, for example 628123456789@c.us for a person or ...@g.us for a group. Empty values fail the item. Since package 1.3.0 a chat id without its @ domain, such as a bare number, fails the item in the node itself and names the field on every message operation that sends the id in the request body (every send, Reply, Edit, React, Delete, Pin, Unpin, Star, Vote Poll, Click Button, and both From Chat Name or ID and To Chat Name or ID on Forward); Get History, Get Reactions, Get Receipts, and Get Media put the id in the URL path and leave that check to the gateway. Since server v0.26.0 a chat id without its domain is also refused with 400 by the gateway on every operation that sends it in the body (Forward's two chat ids and each Send Bulk item included); before, a single send answered 500 on Baileys, and Send Bulk accepted the batch with 202 without checking the id. |
The operation-specific fields follow.
Send Text — request body { chatId, text }.
| Field | Type | Required | Maps to |
|---|---|---|---|
| Message | string | Yes | text. Blank, or longer than 4096 characters, fails the item; surrounding whitespace is kept. A number that is not finite (NaN, Infinity) fails too, rather than being sent as a word. |
| Link Preview | options | No | linkPreview. Engine Default (the default) sends nothing, Generate a Preview sends true and No Preview sends false. With Engine Default, the session's Link Preview setting applies when it has one and the send has no Custom Link Preview (server v0.30.3+); otherwise the engine decides. Baileys builds a preview only when asked to; whatsapp-web.js builds one by default and No Preview suppresses it. On Baileys the gateway fetches the linked page itself: since server v0.23.6 it does so through the session's egress proxy when one is set, where it used to fetch from the gateway's own address, and a fetch the proxy cannot complete sends the message without a preview rather than failing it. Since server v0.31.0 the fetched page's title is cut to 256 characters and its description to 1024, the limits a Custom Link Preview is held to. SESSION_PROXY_URL_FETCH=false restores the direct fetch. |
| Custom Link Preview | collection | No | customLinkPreview. Supplies the card yourself, so nothing is fetched. Offers URL, Title, Description, Thumbnail Base64 (server v0.27.0+) and Thumbnail URL (server v0.27.0+); URL and Title are both required or nothing is sent, and the URL must also appear literally in the message text or WhatsApp renders no card at all. Since package 1.4.0 the node checks lengths locally before sending (URL at most 2048 characters, Title at most 256, Description at most 1024), refuses a multi-element list on URL, Thumbnail Base64 or Thumbnail URL, strips an optional data:*;base64, prefix from Thumbnail Base64 (which takes precedence when both thumbnail fields are set), and requires Thumbnail URL to be an http:// or https:// URL with a host. Either thumbnail is capped at 5 MiB on the gateway, and an older server refuses them with 400. Baileys only: whatsapp-web.js answers 501 rather than dropping it silently. |
Send Image — the media source model, plus an optional caption. Request
body { chatId } plus the source fields, and caption when set.
| Field | Type | Required | Notes |
|---|---|---|---|
| Image Source | options: Binary Data, URL, Base64 | Yes | Default URL. |
| Binary Property | string | Yes (binary) | Default data. |
| Image URL | string | Yes (url) | Public URL of the image. |
| Base64 Data | string | Yes (base64) | Base64-encoded image bytes. |
| MIME Type | string | Yes (base64) | For example image/png. Default image/jpeg. |
| Caption | string | No | Sent as caption. At most 1024 characters, here and on Send Video and Send Document. |
Send Video — same shape as Send Image, with the Video Source field, a Video URL field
(public URL of the video) in place of Image URL, and a video/mp4 default MIME type.
Send Audio — same source model, plus a voice-note toggle. Request body { chatId } plus the
source fields, and ptt: true when the toggle is on.
| Field | Type | Required | Notes |
|---|---|---|---|
| Audio Source | options: Binary Data, URL, Base64 | Yes | Default URL. |
| Binary Property | string | Yes (binary) | Default data. |
| Audio URL | string | Yes (url) | Public URL of the audio. |
| Base64 Data | string | Yes (base64) | Base64-encoded audio bytes. |
| MIME Type | string | Yes (base64) | Default audio/ogg; codecs=opus. For a plain audio file set its real type (for example audio/mpeg). |
| Send as Voice Note | boolean | No | Default off. When on, the clip is delivered as a true WhatsApp voice note (PTT — the microphone bubble with a waveform) instead of a plain audio file. Requires OGG/Opus audio (audio/ogg; codecs=opus). |
Send Document — same source model, with a filename. Request body { chatId, filename } plus the
source fields, and caption when set.
| Field | Type | Required | Notes |
|---|---|---|---|
| Document Source | options: Binary Data, URL, Base64 | Yes | Default URL. |
| Binary Property | string | Yes (binary) | Default data. |
| Document URL | string | Yes (url) | Public URL of the document. |
| Base64 Data | string | Yes (base64) | Base64-encoded document bytes. |
| MIME Type | string | Yes (base64) | For example application/pdf. Default application/pdf. |
| Filename | string | No | Sent as filename (at most 255 characters, checked locally since package 1.7.0 and on the gateway). Default document.pdf. Clearing the field takes the binary file's own name, or the file name at the end of the URL, when it looks like a real file name (a short extension that is not a server-script one such as .php); otherwise the document is named document.pdf. |
| Caption | string | No | Sent as caption when set. |
Send Sticker — same source model. WhatsApp expects a WebP sticker, ideally 512×512.
| Field | Type | Required | Notes |
|---|---|---|---|
| Sticker Source | options: Binary Data, URL, Base64 | Yes | Default URL. |
| Binary Property | string | Yes (binary) | Default data. |
| Sticker URL | string | Yes (url) | Public URL of the sticker (WhatsApp expects a WebP image). |
| Base64 Data | string | Yes (base64) | Base64-encoded sticker bytes. |
| MIME Type | string | Yes (base64) | Default image/webp. Set the type the bytes really have, such as image/png: the gateway converts an image to WebP itself, but on whatsapp-web.js data declared as image/webp skips that conversion, so non-WebP bytes labelled image/webp arrive as a broken sticker. Since server v0.28.0 whatsapp-web.js also refuses non-image and non-video media (such as application/pdf or audio/*) with 400 before calling the browser. Since server v0.31.0 whatsapp-web.js answers 400 with its reason for a video that ffmpeg refuses, and 503 when the host's ffmpeg is missing or cannot run the conversion; both sent nothing, and both answered 500 before. |
Send Text, Send Image, Send Video, Send Audio, Send Document, Send Sticker, Send Template, Reply and Edit all accept an optional Mentions field — a list
of WhatsApp ids to @mention (for example 628123456789@c.us), in any of the shapes described under
List fields. The message text or caption must also contain the matching
@628123456789 token for the mention to render. Each id needs its domain: a bare number fails the
item. The field is guarded by operation, so a mentions value can never ride along on an operation
whose DTO would reject it.
Send Text, Send Template, Send Image, Send Video, Send Audio, Send Document, Send Sticker, Send Location, Send Contact, Send Poll, Reply and Forward accept an optional Idempotency Key, sent as the Idempotency-Key header. It takes 1 to 255 visible ASCII characters with no spaces; anything else fails the item. On server v0.25.0 and newer, retrying the same request with the same key within 24 hours returns the first response instead of sending again. Keys are unique per session, so build one per intended message from an expression and reuse it only to retry that message. The same key with a different route or body answers 422, and a retry answers 409 while the first request is still running or after a failure that may have sent the message; inspect the outcome before sending again. On Baileys, since server v0.26.0, a send that WhatsApp rate-limits answers 503 and frees its key, so the same key can be retried; a 503 for a WhatsApp query that timed out keeps the key taken, and a retry answers 409. Since server v0.27.0 the key is also freed on any failure that proves nothing was handed to WhatsApp (the session is not ready or its WhatsApp Web page is reloading before the send, the active engine does not support the call, a Baileys connection is closed, replaced or stopped before the write, a media, sticker or link-preview thumbnail download or decode fails with 400, 413 or 503, on Baileys the media host refuses the upload (since v0.31.0), a pre-send recipient lookup fails or times out, or on Baileys the quoted or forwarded message is not stored in that chat). A server older than v0.25.0 ignores the header, so it gives no retry protection. The node never generates a key.
Send Text, Send Image, Send Video, Send Audio, Send Document, Send Sticker, Send Location, Send
Contact and Send Poll each accept an optional Quoted Message ID, sent as quotedMessageId. It is
how a reply carries media, a location, a contact or a poll: Reply itself sends text only, and its
own Quoted Message ID is required rather than optional. The two sets are not the same, and neither
follows from the other. Send Template and Edit can mention but cannot quote.
An id the engine cannot resolve fails the send outright rather than delivering it unquoted, and
Baileys can only quote a message it has already stored. On whatsapp-web.js, a send with a Quoted
Message ID to a channel or to a status or broadcast list answers 501 (server v0.23.7+).
Send Location — request body { chatId, latitude, longitude }.
| Field | Type | Required | Maps to |
|---|---|---|---|
| Latitude | number | Yes | latitude |
| Longitude | number | Yes | longitude |
| Location Name | string | No | Sent as description (OpenWA's field for the location label) when set. |
| Address | string | No | Sent as address, the street line WhatsApp shows under the label. |
Send Contact — request body { chatId, contactName, contactNumber }.
| Field | Type | Required | Maps to |
|---|---|---|---|
| Contact Name | string | Yes | contactName — display name for the shared contact card. |
| Contact Number | string | Yes | contactNumber — phone number including the country code (it is not auto-prefixed), for example +628123456789. |
Send Poll — request body { chatId, name, options }, plus allowMultipleAnswers when on.
| Field | Type | Required | Notes |
|---|---|---|---|
| Question | string | Yes | Sent as name. Maximum 255 characters. |
| Options | string list | Yes | The answers to vote on. Between 2 and 12 — anything outside that range fails the item. Each option is also capped at 100 characters, which the node checks too. A list in one pair of brackets that is not valid JSON, such as ['Pizza', 'Sushi'], fails the item (see List fields). |
| Allow Multiple Answers | boolean | No | Default off. When on, voters may pick several options instead of exactly one. |
Send Template — renders a stored template and sends the result. Request
body { chatId } plus either templateId or templateName, and vars when set.
| Field | Type | Required | Notes |
|---|---|---|---|
| Template Name or ID | options | Yes (or Template Name) | Id of the template to render. When both this and Template Name are set, the id wins. |
| Template Name | string | Yes (or Template Name or ID) | Used only when the id is empty. Providing neither fails the item. |
| Variables (JSON) | json | No | Values substituted into the template's {{placeholder}} tokens, as a JSON object such as {"name":"Alice"}. A non-object value fails the item. |
| Link Preview | options | No | The same field as under Send Text: Engine Default, Generate a Preview or No Preview. The node sends linkPreview only for the last two, and a server older than v0.23.0 refuses a Send Template request that carries it. With Engine Default, the session's Link Preview setting applies (server v0.30.3+), as under Send Text. |
Send Bulk — sends up to 100 messages as a tracked batch. Request body { messages }, plus
batchId and options when set. No Chat ID — each item carries its own chatId.
| Field | Type | Required | Notes |
|---|---|---|---|
| Messages (JSON) | json | Yes | Array of 1–100 items — an empty array or more than 100 items fails the item, and since package 1.5.0 (and server v0.29.0) each element must be a plain JSON object (null, primitives, and nested arrays fail the item locally). A text item is { "chatId": "628123456789@c.us", "type": "text", "content": { "text": "Hello" } }. A media item nests the media object under the type key (image/video/audio/document) and puts caption alongside it on content: { "chatId": "628123456789@c.us", "type": "image", "content": { "image": { "url": "https://example.com/a.jpg" }, "caption": "Hi" } }. Media uses url or base64 (add mimetype for base64) — there is no binary source in bulk. A url must be an absolute http:// or https:// URL; since server v0.23.6 anything else is refused with 400, or fails only its own item when variables fill it in, and since v0.31.0 the same holds for a url that carries a user name or password. An item can also carry variables, an object of string values substituted into the {{name}} placeholders of its content, and, inside content, mentions (a list of WhatsApp ids; server v0.23.0 and newer, an older server refuses it with 400; since v0.26.0 an entry may be a {{name}} placeholder that variables fill in, and the rendered ids are checked as the item runs). Since v0.26.0 each item's chatId needs its domain, and a list where the gateway expects an object (an item's content or media object, or the batch options) is refused with 400. The media object takes filename on a document and "ptt": true on an audio item for a voice note, for example "content": { "audio": { "url": "https://example.com/a.ogg", "ptt": true } }. A value that is blank or not valid JSON fails the item, naming the field. |
| Batch ID | string | No | Custom batch id; must be unique per session. Leave empty to let the server generate one. Since server v0.23.6, . and .. are refused with 400. |
| Options | collection | No | Left empty, the server applies its own defaults (delay 3000 ms, randomize on, stop-on-error off). |
The Options collection offers:
| Option | Type | Default | Notes |
|---|---|---|---|
| Delay Between Messages (Ms) | number | 3000 | Milliseconds to wait between sends, 1000–60000. |
| Randomize Delay | boolean | on | Adds a random 0–2000 ms on top of the delay. |
| Stop on Error | boolean | off | Aborts the batch on the first failed send. |
Send Bulk returns a batchId immediately and sends in the background. Poll Get Batch Status
until the status is completed, cancelled, or failed, or stop the batch early with Cancel
Batch. A 429 means the server already runs BULK_MAX_CONCURRENT_BATCHES batches (default 50,
0 is unlimited; servers before v0.24.0 answered 400), and a 503 means it is shutting down
(since v0.25.0). Retry either shortly.
Get Batch Status / Cancel Batch — read a batch's progress or cancel it. Each takes one field:
| Field | Type | Required | Notes |
|---|---|---|---|
| Batch ID | string | Yes | The batch id returned by Send Bulk. |
Reply — request body { chatId, quotedMessageId, text }.
| Field | Type | Required | Notes |
|---|---|---|---|
| Quoted Message ID | string | Yes | Full serialized id of the message to quote (for example true_628123456789@c.us_3EB0…), as returned by send operations or delivered by the Trigger. |
| Message | string | Yes | The reply text, sent as text. The same rules as Send Text: blank, or longer than 4096 characters, fails the item. |
React — request body { chatId, messageId, emoji }.
| Field | Type | Required | Notes |
|---|---|---|---|
| Message ID | string | Yes | Full serialized id of the target message. |
| Emoji | string | No | The emoji to react with. Leave empty to remove your existing reaction — the empty value is sent deliberately. An object fails the item. |
Edit — request body { chatId, messageId, body }.
| Field | Type | Required | Notes |
|---|---|---|---|
| Message ID | string | Yes | Full serialized id of the message to edit. |
| Message | string | Yes | The replacement body, maximum 4096 characters. |
The response carries the messageId and timestamp of the edited message itself: the id you sent
and its original send time. On Baileys that holds from server v0.23.6. Earlier releases returned the
id and send time of the envelope that carried the edit, an id no other operation can address, so
against an older server take the id for a follow-up Delete, React, Pin or Edit from the input rather
than from the Edit response. Since server v0.28.0 Baileys also refuses to edit a message that has no text or caption (such as an uncaptioned image, sticker, audio, location, contact, or poll) with 403, matching whatsapp-web.js.
Delete — request body { chatId, messageId, forEveryone }.
| Field | Type | Required | Notes |
|---|---|---|---|
| Message ID | string | Yes | Full serialized id of the message to delete. |
| Delete for Everyone | boolean | No | Default on: revokes the message for everyone when the account sent it or administers the group. On Baileys, since server v0.23.7, another sender's message in a one-to-one chat, or in a group the account does not administer, is deleted for the account only and the route still answers success. Turn off to remove only your own local copy; on Baileys that works from server v0.23.6, and earlier releases answered 500 without reaching WhatsApp. An expression that resolves to nothing fails the item, since the server would read it as on and retract the message for everyone. |
Forward — request body { fromChatId, toChatId, messageId }. Takes no shared Chat ID. Since server v0.27.1, when the source message is in the gateway's history for fromChatId, the stored row for the forwarded copy keeps the original message's type, text, and media instead of type: "text" with an empty body.
| Field | Type | Required | Notes |
|---|---|---|---|
| From Chat Name or ID | options | Yes | The chat the message currently lives in. |
| To Chat Name or ID | options | Yes | The chat to forward it to. |
| Message ID | string | Yes | Full serialized id of the message to forward. |
List — reads stored messages. Takes no shared Chat ID; every filter lives in its Options collection and is sent as a query parameter.
| Option | Type | Default | Notes |
|---|---|---|---|
| After Row ID | string | unset | Keyset cursor: the id of the previous page's last message. Anchors the page to a row rather than a count, so a message arriving mid-walk cannot repeat or skip one. Takes precedence over Offset. |
| Chat Name or ID | options | — | Only return messages from this chat. |
| Direction | options | Incoming | Incoming or Outgoing. Left out, both directions are returned. Server v0.25.0 and newer. |
| From | string | — | Only return messages from this sender. |
| Inline Media | boolean | true | Turn off to omit inline media payloads, keeping each row's { omitted, sizeBytes } marker. The media budget is per response, so a paged walk pays it again on every page. |
| Limit | number | 50 | Max results, 1 to 100. |
| Message ID | string | unset | Exact WhatsApp message reference, at most 200 characters with no whitespace. It is not the stored row ID that After Row ID takes. Server v0.25.0 and newer. |
| Offset | number | 0 | Records to skip before collecting the result set. |
| Order By | options | Created At | Newest first either way. Created At orders by when the gateway stored the message; Message Timestamp orders by WhatsApp's message time and leaves out messages with no known time. Server v0.25.0 and newer. |
| Since | dateTime | unset | Inclusive lower bound on message time. Server v0.25.0 and newer. |
| Type | string | unset | Exact stored message type, for example text, image, voice or poll. Server v0.25.0 and newer. |
| Until | dateTime | unset | Exclusive upper bound on message time; it must be later than Since, or the item fails. Server v0.25.0 and newer. |
Since and Until reach the gateway as epoch milliseconds: a date with no timezone is read in the workflow timezone. A number, or text of digits, other than 0 and below 100000000000 is refused as epoch seconds (package 1.2.0 read it as milliseconds), and a date that does not exist, such as 2026-02-30, is refused in every date field. A server older than v0.25.0 ignores these six options and returns the broader selection. With After Row ID, the cursor must come from the same selection, so keep the filters and the ordering unchanged between pages.
Unlike Get History and Get Reactions beside it, List answers an envelope ({ messages, total })
and so still produces a single item; see Output and error handling.
Get History reads a chat's history from the device. whatsapp-web.js only; Baileys answers
501, so on a Baileys session reach for List, which serves the gateway's own stored copy on
both engines. Since server v0.29.1, forwarded messages in the returned history include isForwarded: true and (when positive) forwardingScore (absent on non-forwarded messages and on List). Requires a Chat ID; the Options collection offers:
| Option | Type | Default | Notes |
|---|---|---|---|
| Deep | boolean | off | Allows a deeper read. History is always read live from the device; Deep raises the Limit ceiling from 100 to 2000 and forces metadata only. A large deep read is slow and raises the risk of WhatsApp rate-limiting the account. |
| Include Media | boolean | off | Include media payloads in the returned messages. Ignored while Deep is on. |
| Limit | number | 50 | Max number of results to return, 1 to 2000. Without Deep the gateway caps it at 100. |
Get Reactions reads the reactions on one message. whatsapp-web.js only; Baileys answers
501. The Trigger's message.reaction event fires on both engines, so a Baileys workflow tracks
reactions as they arrive rather than reading them back.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the message lives in. |
| Message ID | string | Yes | Full serialized id of the message. |
Get Receipts reads who received, read, and played a message this account sent (delivered, read, and played lists with Unix-second timestamp values). whatsapp-web.js only, and requires server v0.28.0 or newer; Baileys answers 501 (on Baileys, subscribe to the Trigger's message.receipt event instead). Answers 403 when the message was received rather than sent by this session, and 404 when messageId is not a full serialized id (true_<chatId>_<id>...) or is not found in chatId. Because the response is an { delivered, read, played } object rather than a bare array, it produces a single item on both node versions.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the message was sent to. |
| Message ID | string | Yes | Full serialized id of the outbound message. |
Get Media downloads the media attached to one message.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the message lives in. |
| Message ID | string | Yes | Full serialized id of the message. |
| Put Output in Field | string | Yes | Name of the output binary property, default data. |
The bytes are attached as a binary property rather than put on json, so the item's json is empty.
This one reads from the gateway's own archive rather than the engine, so it works while the session
is stopped, and a 404 is its only failure.
Pin and Unpin take request body { chatId, messageId }, plus durationSeconds on Pin alone.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the message lives in. |
| Message ID | string | Yes | Full serialized id of the message. |
| Pin Duration | options | Pin only | 24 Hours (the default), 7 Days, or 30 Days. WhatsApp accepts only these three windows, and there is no way to read a pin back, so a workflow cannot check or refresh one. |
On whatsapp-web.js, since server v0.31.0, Pin and Unpin call the page's pin sender the way the
running WhatsApp Web build takes it (they answered a bare 500 on every build from 2.3000.1052565782).
A build with no sender the gateway can call answers 501, a chat with a contact the account blocked
answers 403, and when WhatsApp fails the read of the group in front of the send the answer follows
its status: 503 for 408, 423, 429 or 5xx, 403 for any other. A page reload that lands on the call
answers the retryable 409.
Star takes request body { chatId, messageId, star }.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the message lives in. |
| Message ID | string | Yes | Full serialized id of the message. |
| Star | boolean | Yes | On by default; turn it off to remove the star. Always sent, since the server has no default and omitting it is a 400. A star is private to this account and never visible to the other party. |
Vote Poll casts a vote on a poll someone else sent, with request body
{ chatId, pollMessageId, options }. whatsapp-web.js only; Baileys answers 501.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the poll lives in. |
| Message ID | string | Yes | The poll message's id. Sent as pollMessageId, not messageId. |
| Selected Options | string list | Yes | The option texts to select, at most 12. Matched by text against the poll's own options, so they must match exactly: a different case, or a space inside the text, does not match (the node trims spaces at either end of each entry). On server v0.25.0 and newer a list in which nothing matches is refused with 400 POLL_OPTION_NOT_FOUND, whose body lists the poll's valid options, and the earlier vote stays; older servers clear the vote and still report success. When only some options match, the others are dropped without notice. An option whose own text contains a comma must be supplied as a JSON array, since a comma-separated list would split it. The vote replaces any previous selection, and an empty list clears it, so the key is always sent. |
Click Button answers a button, template quick-reply or list prompt that someone sent, with request
body { chatId, messageId, buttonId } plus text when set. It needs server v0.23.6 or newer and an
OPERATOR key, and it is Baileys only: whatsapp-web.js answers 501. It sends a structured
reply quoted to the prompt rather than a native tap, so WhatsApp may reject it or treat it
differently, and a URL or call button cannot be clicked this way.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | The chat the prompt arrived in. |
| Message ID | string | Yes | The prompt's own id, data.id on its message.received event. |
| Button ID | string | Yes | One of the prompt's buttons[].id, at most 256 characters. An id that is not among its choices answers 400. |
| Button Text | string | No | The visible label of the choice, sent as text. Left empty, the gateway reads it from the stored prompt. |
The prompt must still be in the engine's message store: one that has been evicted answers 404, even
when a reloaded chat still shows its choices.
Send Product sends a product card from this account's catalog, with request body
{ chatId, productId } plus body when a message is set. Baileys only; whatsapp-web.js answers
501, which is the same engine restriction the Catalog resource carries, so the operation that finds
a product id and the one that sends it agree on the engine.
| Field | Type | Required | Notes |
|---|---|---|---|
| Chat Name or ID | options | Yes | Recipient. |
| Product ID | string | Yes | The product's id in this account's catalog; find it with Catalog → List Products. An id that is not in the catalog answers 404. A product with no image cannot be sent as a card, which the server reports as a 400. |
| Message | string | No | Optional text alongside the card. Sent as body. |
Send Image, Send Video, Send Audio, Send Document and Send Sticker all answer 501 on
whatsapp-web.js when the Chat Name or ID is a channel (<id>@newsletter). Since server v0.23.7,
whatsapp-web.js also answers 501 for Reply, Send Location, Send Contact and any send carrying a
Quoted Message ID to a channel or to a status or broadcast list (@broadcast), and for Send Poll
and Send Sticker to a status or broadcast list; nothing is sent. The same operations work on either
engine for a person or a group. Send Text to a channel works on both when it carries no Quoted
Message ID.
Contact resource
Check Exists and Get LID take a Phone Number, Get Profile Pictures takes a list of ids, List and List
Blocked take only pagination or nothing at all, and every other contact operation takes a Contact
Name or ID (a WhatsApp JID such as 628123456789@c.us).
| Operation | Field | Type | Required | Notes |
|---|---|---|---|---|
| Check Exists | Phone Number | string | Yes | Digits in international format (for example 628123456789) or, since package 1.5.0, a phone-based user JID (@c.us, @s.whatsapp.net, or @hosted, with an optional :device suffix). The node strips +, spaces, -, (), and a phone-JID suffix; @lid, groups, channels, and any non-digit left over fail the item. Needs an OPERATOR key since server v0.24.0; a VIEWER key answers 403. |
| Get Info | Contact Name or ID | options | Yes | For example 628123456789@c.us. Empty values fail the item. |
| Get LID | Phone Number | string | Yes | Looks up the @lid privacy id ({ lid, phoneNumber }) for a phone number or phone-based user JID, with the same input stripping and validation as Check Exists. Needs server v0.27.1 or newer and an OPERATOR key (403 to a VIEWER or chat-restricted key; 404 when no @lid is known for the number). |
| Get Phone | Contact Name or ID | options | Yes | Resolves the contact's phone number. On whatsapp-web.js since server v0.27.1 a phone JID (@c.us or @s.whatsapp.net) is answered directly from its user part without a browser lookup. |
| Get Profile Picture | Contact Name or ID | options | Yes | Returns the contact's profile-photo URL. |
| Get Profile Pictures | Contact IDs | string list | Yes | Pictures for many contacts at once, sent as ?ids=. At most 50 — a longer list fails the item rather than being silently truncated by the server. An id with no picture, a hidden one or a failed lookup comes back null. Since server v0.26.0, once one lookup times out the ids not yet looked up are left out of the answer instead of being null, so ask for them again and do not index the answer by every id you sent. |
| List | Options: Limit (1 to 1000), Offset | collection | No | Returns the session's contacts, paginated. On Baileys (server v0.23.6+) that is the saved address book only; see below. |
| List Blocked | (none) | n/a | n/a | The ids this account has blocked. Bare id strings, not contact objects; see the wrapping note under Output and error handling. |
| Save | Contact Name or ID, First Name, Last Name | string | First Name yes | Writes the addressbook entry. Both names are capped at 100 characters. |
| Delete | Contact Name or ID | options | Yes | Removes the entry from the addressbook. The chat and its history are untouched. |
| Block | Contact Name or ID | options | Yes | Blocks the contact. On whatsapp-web.js, since server v0.31.0, the gateway asks WhatsApp for the number's privacy id when the page holds none, so a number the session never talked to can be blocked, and a number WhatsApp holds no privacy id for answers 400. |
| Unblock | Contact Name or ID | options | Yes | Unblocks the contact (DELETE on the block endpoint). On whatsapp-web.js a number WhatsApp holds no privacy id for answers 400 (server v0.31.0+), and an unblock removes only the entry under the number's privacy id: server v0.26.0 to v0.30.3 also removed an entry the same person held under a second id, such as a block by phone number from before WhatsApp moved the contact to privacy ids, which now has to be unblocked on the phone. |
Check Exists returns whatsappId, the chat id WhatsApp holds for the number, as <phone>@c.us on
both engines since server v0.26.0; whatsapp-web.js answered an @lid id for a contact migrated to
privacy-id addressing before. It can differ from the number you sent, so read the recipient id from the
response rather than reconstructing it.
List on a Baileys session returns, since server v0.23.6, only contacts with a name saved on the
phone. A peer known by its pushname alone is no longer listed, and so no longer offered by the
Contact Name or ID dropdown, which reads the same route; supply its id from an expression, and
Get Info still resolves it with isMyContact: false. whatsapp-web.js still lists unsaved chat
partners. The saved names arrive after the session connects, not with it: on a fresh link about 20
seconds after WhatsApp's initial sync ends, and after every Start or gateway restart once the gateway
has pulled the address book again. A List run straight after linking or starting can come back short
or empty (zero items on node version 2), so wait or retry before relying on it.
Save overwrites the whole entry rather than patching it, so a blank Last Name clears any last
name already stored. The node omits the key when it is blank rather than sending null, which the
engine would write as a literal null.
List Blocked returns ids alone on both engines. whatsapp-web.js can resolve full contact models and Baileys cannot, so the server publishes the honest common subset instead of letting the two engines describe the same account differently.
Chat resource
Chat operations act on a conversation rather than the session. Most post the target chat in the
request body; List takes none, and Clear Messages is the one that names the chat in the path
and is a real DELETE.
| Operation | Fields | Notes |
|---|---|---|
| List | Options: Limit (1 to 1000), Offset | The session's chats, one item per chat. The fields show 50 and 0 once added; with no option set, the server returns up to 1000 chats. Each row carries archived, pinned and muted, plus muteExpiration when muted, so the state the write operations below set can be read back. On Baileys, since server v0.31.0, a chat held under a privacy id (@lid) that has no saved, verified or push name lists name as "", where it listed the id's own digits, and carries a phone when the session can map the id: title such a chat by phone, else by id. phone is Baileys only (whatsapp-web.js lists none, and lists an unnamed privacy-id chat under its id). Also since v0.31.0 a Baileys name is trimmed, and a blank name of a Baileys chat not held under a privacy id lists the contact's name or the id's digits, where it was listed as it came. |
| Mark Read | Chat Name or ID, Message IDs | Body { chatId }, plus messageIds when supplied. Leave the ids empty to mark the whole chat read; supply them to ack specific messages, at most 100. An expression that resolves to an empty list fails the item rather than marking the whole chat. On Baileys, since server v0.31.0, a read whose receipt names the chat's newest received message (the default when no ids are supplied) also sets the chat's unreadCount back to 0 and undoes an unread mark set by Mark Unread or on the phone; before, the count and the mark stayed, so the chat listed as unread again. A read whose ids leave out a newer message leaves the chat unread. |
| Mark Unread | Chat Name or ID | Body { chatId }. |
| Delete | Chat Name or ID | Body { chatId }. A POST, not a DELETE — the server takes the chat id in the body here. |
| Clear Messages | Chat Name or ID | DELETE /api/sessions/{sessionId}/chats/{chatId}/messages. Empties the chat but keeps it in the list. |
| Archive | Chat Name or ID, Archive | Body { chatId, archive }. Set Archive off to unarchive. |
| Pin | Chat Name or ID, Pin | Body { chatId, pin }. WhatsApp allows at most three pinned chats. On Baileys since server v0.28.0 pinning or unpinning a 1:1 chat requires both its phone number and its @lid privacy ID to be paired in lid_mappings (answering 400 when unpaired). |
| Mute | Chat Name or ID, Mute Until | Body { chatId, muteUntil }, epoch milliseconds. A date with no timezone is read in the workflow timezone, and a date with no time is midnight there. A number below 100000000000 other than 0 is refused as epoch seconds, which the gateway would accept as a mute that expired in 1970; 0 reaches the gateway, which refuses it. To mute indefinitely, use a far-future timestamp: since server v0.26.0 one above 9007199254740991 (the largest integer a JSON number carries exactly) is refused with 400. Left empty, the node sends null, which unmutes the chat; an expression that resolves to nothing fails the item instead. On Baileys since server v0.28.0 muting or unmuting a 1:1 chat also requires its phone and @lid to be paired in lid_mappings (answering 400 when unpaired). On whatsapp-web.js a channel id answers 400, for the mute and the unmute alike (mute a channel with Channel → Mute); before server v0.31.0 it answered a bare 500. |
| Set State | Chat Name or ID, State | Body { chatId, state }. State is Typing, Recording, or Paused (default Typing); Typing and Recording show the indicator in the chat, Paused clears it. |
Mark Read, Mark Unread, Delete, Archive, Pin and Mute refuse a bare number as the Chat Name or ID
and fail the item: give a full WhatsApp ID including its domain, such as 628123456789@c.us. Set State passes a bare number through in the node, and since server v0.26.0 the gateway refuses it with 400.
Group resource
List, Create, Join, and Get Join Info are session-level; every other operation takes a Group Name
or ID (a JID such as 120363021234567890@g.us). Since package 1.4.0 the node checks locally that Group Name or ID ends in @g.us with no internal whitespace or extra @ (normalizing an uppercase @G.US suffix to lowercase @g.us) before calling the gateway.
| Operation | Fields | Notes |
|---|---|---|
| List | Options: Limit (1–1000), Offset | Left empty, the server applies its own defaults (limit 1000, offset 0). |
| Create | Group Name, Participants | Name is required and capped at 100 characters; Participants is required and capped at 256. Baileys engine only since server v0.16.0 — whatsapp-web.js, the server default, answers 501 Operation not supported by the active engine: createGroup. See Groups. |
| Join | Invite Code | The part after https://chat.whatsapp.com/. A full invite link is accepted and reduced to the code. Maximum 128 characters. On whatsapp-web.js, since server v0.31.0, a group that has an admin approve new members answers 400 with a message that a request to join was sent (the account has not joined; the message called the invite invalid before), a rate limit, a timeout or a server error from WhatsApp (408, 423, 429 or 5xx) answers a retryable 503 (a good code answered 400), and a WhatsApp Web build with no group join job answers 501 (every code answered 400). |
| Get Join Info | Invite Code | Previews the group behind a code without joining, so it is safe to run on a code from an untrusted source. Same link tolerance and 128-character cap as Join. There is no participant list, only a count, and only when WhatsApp discloses one; fields the engine does not report are omitted rather than defaulted. On whatsapp-web.js, since server v0.31.0, a rate limit, a timeout or a server error from WhatsApp (408, 423, 429 or 5xx) answers a retryable 503 (a good code answered 404), and a WhatsApp Web build with no invite preview job answers 501 (every code answered 404); a preview that gets neither a group nor an error back still answers 404. |
| Get | Group Name or ID | Group info including participants. |
| Leave | Group Name or ID | Leaves the group. |
| Add / Remove / Promote / Demote Participants | Group Name or ID, Participants | Body { participants }, capped at 256. Remove Participants is a DELETE that carries a JSON body — the API takes the list there rather than in the query string. |
| Update Subject | Group Name or ID, Subject | Required, maximum 100 characters. |
| Update Description | Group Name or ID, Description | Maximum 1024 characters. An empty value is sent as-is and clears the description. |
| Set Member Label | Group Name or ID, Member Label | Body { label }. Sets or clears this account's own member label in the group (at most 30 UTF-16 code units, so an emoji outside the Basic Multilingual Plane takes two; leave empty to clear). Refuses null, a list, or a template expression ({{ ... }}) that resolves to nothing or whitespace so an unresolved expression never clears an existing label. Baileys only (whatsapp-web.js answers 501), and requires server v0.27.0 or newer. |
| Get Settings | Group Name or ID | Reads announce, locked, the member-add mode, and the disappearing-message timer. |
| Update Settings | Group Name or ID, Settings | Partial — settings you leave out stay untouched, and at least one is required. |
| Get Invite Code | Group Name or ID | The invite code and link. Needs an OPERATOR key since server v0.23.5, because the code lets anyone join the group, so a VIEWER key answers 403 on this read. On whatsapp-web.js, since server v0.31.0, a WhatsApp Web build with no job to read the code answers 501, and WhatsApp giving no code answers 403; both answered a bare 500. |
| Revoke Invite Code | Group Name or ID | Revokes the code and generates a new one. On whatsapp-web.js, since server v0.31.0, a WhatsApp Web build with no job to reset the code answers 501; it answered 500 and the link was not rotated. |
| Get Membership Requests | Group Name or ID | The join-approval queue, one item per pending request. Only populated when the group has admin approval enabled, and admin-only on both engines. |
| Approve / Reject Membership Requests | Group Name or ID, Requesters | Body { participants }, capped at 256. Leave Requesters empty to act on the whole queue rather than failing, which is why it is the one participant list the node accepts empty. An expression that resolves to an empty list is refused instead, so that acting on everyone is always deliberate. An empty queue is a no-op returning an empty results list. |
| Get Picture | Group Name or ID | The group picture's URL. |
| Set Picture | Group Name or ID, Picture Source (+ source fields) | The media source model, defaulting to Binary; base64 falls back to image/jpeg. The resolved media fields form the whole request body. Any member may change it unless the group restricts editing its info to admins (Locked), which takes an admin; anyone else is refused with 403. A base64 or binary payload over the server's media cap answers 413. The media must be an image: a binary item or a Base64 MIME Type that is not image/* fails the item with the reason, where a production server's 400 carries no field detail unless VALIDATION_ERROR_DETAIL is true; a URL source is not checked here. |
| Delete Picture | Group Name or ID | Removes the picture. Needs an admin only when the group restricts editing its info to admins (Locked). On whatsapp-web.js the request goes to WhatsApp itself, so a group with no picture answers 200 and a repeat converges (since server v0.31.0; it answered 403). |
The Settings collection offers:
| Option | Type | Default | Notes |
|---|---|---|---|
| Announce | boolean | off | Only admins can send messages to the group. |
| Locked | boolean | off | Only admins can edit the group info. |
| Member Add Mode | options | All Members | Who may add participants: All Members (all) or Admins Only (admins). |
| Disappearing Messages (Seconds) | number | 604800 | Disappearing-message timer; 0 disables it. Baileys engine only — whatsapp-web.js returns 501. |
On whatsapp-web.js, since server v0.31.0, Update Subject, Update Description, Update Settings, Set
Picture and Delete Picture answer with the status WhatsApp gave: a rate limit, a timeout or a server
error (408, 423, 429 or 5xx) answers a retryable 503 (for a Member Add Mode change it may mean the
change was applied in part, and the message names any setting of the same request that was), and any
other refusal answers 403. Before, every status answered 403 naming missing admin rights, except
that a refused Announce or Locked write answered 200. A WhatsApp Web build with no job to send the
change answers 501, for Update Settings only when it sets Announce, Locked or Member Add Mode.
Add, Remove, Promote, and Demote report a per-participant outcome in results[], and a partial
refusal does not fail the batch — check results[].success rather than the top-level success.
Approve and Reject Membership Requests report the same way. On whatsapp-web.js the engine pauses
250 to 500 ms between requesters as upstream anti-abuse pacing, so clearing a long queue is a
proportionally long request: raise the node's timeout before running it on a busy group. On whatsapp-web.js, on a WhatsApp Web build where the library's invitation sender is not found, Add Participants adds without sending an invitation: a participant WhatsApp only lets the account invite is reported in results with status 403, and the others keep their outcome (since server v0.31.0; the whole call answered 500).
Profile resource
Changes the session's own WhatsApp profile.
| Operation | Fields | Notes |
|---|---|---|
| Set Name | Name | Required, maximum 25 characters. |
| Set Status | Status | Maximum 139 characters. An empty value is sent as-is and clears the about text. On whatsapp-web.js a WhatsApp Web build that no longer has the call the library uses to set the About text answers 501 (server v0.31.0+; 500 before). |
| Set Picture | Picture Source, and the matching Binary Property / Picture URL / Base64 Data + MIME Type | The media source model; base64 defaults to image/jpeg. The resolved media fields form the whole request body. The same image-only check as Group Set Picture applies. On whatsapp-web.js, since server v0.31.0, a rate limit, a timeout or a server error from WhatsApp (408, 423, 429 or 5xx) answers a retryable 503, where every status answered 403, and a WhatsApp Web build with no job to send the picture answers 501; any other refusal still answers 403. |
| Delete Picture | (none) | Removes the account's own picture. On whatsapp-web.js the request goes to WhatsApp itself, so a repeat answers what WhatsApp answers, not a local 200; a rate limit, a timeout or a server error (408, 423, 429 or 5xx) answers a retryable 503, which used to answer 403; and a WhatsApp Web build with no job to remove the picture answers 501 (server v0.31.0+). |
Label resource
WhatsApp Business labels — the catalogue on the account, and the labels attached to one chat.
| Operation | Fields | Notes |
|---|---|---|
| List | (none) | whatsapp-web.js only; Baileys answers 501. Every label on the account. |
| Get | Label Name or ID | whatsapp-web.js only; Baileys answers 501. One label. An unknown id answers 404 (server v0.23.6+; 500 before), which on a personal account is every id. |
| Create or Update | Label ID, Fields: Name, Color | Baileys only; whatsapp-web.js answers 501. A PUT, because the id is caller-chosen: an unused id creates, an existing one rewrites that label rather than failing. At least one field is required, and the write replaces the whole label: a field left out is not preserved, so send every field the label should keep. |
| Delete | Label ID | Baileys only; whatsapp-web.js answers 501. The label disappears from every chat it was on. |
| Get Chats | Label Name or ID | whatsapp-web.js only; Baileys answers 501. Since server v0.24.0 a chat-restricted key sees only allowed chats; supply the label id from an expression because its dropdown stays closed. |
| Get for Chat | Chat Name or ID | whatsapp-web.js only; Baileys answers 501. The labels attached to a chat. |
| Add to Chat | Chat Name or ID, Label Name or ID | Body { labelId }. On whatsapp-web.js a chat the session cannot resolve answers 404 (server v0.23.6+; 500 before). Answers 422 for a channel chat (on whatsapp-web.js always, on Baileys since server v0.22.0) and, on whatsapp-web.js, for an account that is not a WhatsApp Business account. |
| Remove From Chat | Chat Name or ID, Label Name or ID | Both ids go in the path. On whatsapp-web.js a chat the session cannot resolve answers 404 (server v0.23.6+; 500 before). Answers 422 in the same cases as Add to Chat. |
The whole resource is split down the middle, and no session gets both halves. Baileys carries the label writes and cannot query labels at all; whatsapp-web.js carries every read and cannot edit a label. Only Add to Chat and Remove From Chat work on both, since those write the chat rather than the label.
That split is also why Create or Update and Delete take a plain-text Label ID rather than the dropdown the other operations use: the picker is fed by a read the engine serving those two writes cannot perform, so a picker would always be empty there.
The Fields collection on Create or Update:
| Field | Type | Notes |
|---|---|---|
| Name | string | Label text, up to 100 characters. A blank value fails the item rather than being dropped: the server marks the field non-empty, so a blank cannot mean "clear the name". Leaving the field out is not a safe no-op either: the write replaces the whole label, so a name that is not sent is lost. |
| Color | number | An index into WhatsApp's twenty predefined colours, 0 to 19, not a hex value. 0 is a real colour, so the field lives in a collection to keep "not set" distinguishable. A read returns a hex string that cannot be converted back, so read-then-write does not round-trip the colour. |
Status resource
Reads the Status (Stories) feed and posts new updates.
| Operation | Fields | Notes |
|---|---|---|
| List | (none) | The status feed. |
| Get by Contact | Contact Name or ID | One contact's status updates. |
| Get Media | Status ID, Put Output in Field | Streams the stored image or video bytes. The response is attached as a binary property named by Put Output in Field (default data), not as JSON. |
| Delete | Status ID | Deletes one of your own status updates. |
| Send Text | Text, Background Color, Font, Recipients | Body { text } plus backgroundColor, font, and recipients when set. Text is required, maximum 4096 characters. |
| Send Image | Image Source (+ source fields), Caption, Recipients | The media object nests under image rather than sitting flat on the body. |
| Send Video | Video Source (+ source fields: Binary Property, Video URL, Base64 Data, MIME Type), Caption, Recipients | The media object nests under video. |
| Send Voice | Audio Source (+ source fields), Background Color, Recipients | Posts an audio status as a voice note. The media object nests under audio, and there is no caption. The source dropdown defaults to Binary; base64 falls back to audio/ogg; codecs=opus. |
| Field | Type | Notes |
|---|---|---|
| Background Color | color | Sent as backgroundColor. Leave empty for the server default. |
| Font | options | Font index from the WhatsApp status font set: Default (0), Font 1, Font 2, Bold (6), Font 7, Font 8, Font 9, Font 10, and Server Default (the node's default), which omits the field entirely. |
| Caption | string | Maximum 1024 characters. |
| Recipients | string list | Who may see this status: at most 256 @c.us or @lid ids, never a group. Required on the Baileys engine, which honours it. whatsapp-web.js ignores it entirely and posts to the whole contact list whether a list is supplied or not, logging a warning server-side when one is, so treat it as an audience restriction on Baileys alone. |
Template resource
Reusable message bodies with {{variable}} placeholders, stored per session and rendered by
Message → Send Template.
| Operation | Fields | Notes |
|---|---|---|
| List | (none) | Every template in the session. |
| Create | Name, Body, Header, Footer | Name (max 100) and Body (max 4096) are required; Header and Footer are optional, max 1024 each. |
| Get | Template Name or ID | One template. |
| Update | Template Name or ID, Update Fields | Partial: the collection offers Body, Footer, Header, and Name, with the same limits. At least one is required. |
| Delete | Template Name or ID | Deletes the template. |
A blank value in Update Fields means different things per field, because the server validates them differently. Name and Body are non-empty on the server, so a blank one fails the item with a message naming the field rather than being silently dropped, which would report success while leaving the template untouched. Header and Footer carry no such rule, so a blank there is a deliberate clear and is sent as one. Add a field only to change it; remove it from the collection to leave it alone.
Channel resource
WhatsApp Channels (newsletters) the session follows.
| Operation | Fields | Notes |
|---|---|---|
| List | (none) | whatsapp-web.js only; Baileys answers 501. Followed channels. |
| Get | Channel Name or ID | One channel. Works on both engines. |
| Get Messages | Channel Name or ID, Options: Limit (1 to 100, default 50) | whatsapp-web.js only; Baileys answers 501. A channel's messages. |
| Create | Channel Name, Description | Name is required, maximum 100 characters; Description is optional, maximum 2048. The account becomes the owner, which is what makes Delete possible later. A blank description is omitted rather than sent as an empty one. |
| Subscribe | Invite Code | Baileys only; whatsapp-web.js answers 501, because its library subscribes by channel id and has no invite-code path. The part after https://whatsapp.com/channel/. A full link is accepted and reduced to the code. |
| Unsubscribe | Channel Name or ID | A DELETE on the channel — it unfollows rather than deletes. |
| Delete | Channel Name or ID | Irreversible, and every subscriber loses the channel. Owner only. Deliberately a POST on a separate path so a slip of the wrist cannot turn Unsubscribe into this. |
| Mute | Channel Name or ID, Mute | Silences notifications for this account; the subscription is untouched. The flag defaults to on and is always sent, since the server has no default of its own. Turn it off to unmute. |
| Demote Admin | Channel Name or ID, User ID | Demotes an admin back to a subscriber. Owner only, and Baileys only: whatsapp-web.js answers 501 because the module function its library targets no longer exists. Since server v0.28.0 a channelId that does not end in @newsletter answers 404 before calling the engine. There is no promote counterpart on either engine, so an admin is promoted from the WhatsApp app and demoted here. |
| Transfer Ownership | Channel Name or ID, New Owner ID | Irreversible: once it lands this session is no longer the owner and cannot take the channel back through this API. Owner only, and Baileys only; whatsapp-web.js answers 501. Since server v0.28.0 a channelId that does not end in @newsletter answers 404 before calling the engine. |
Channels are the most engine-split resource here, and the split runs both ways: Baileys is the only engine that can subscribe by invite code, and whatsapp-web.js is the only one that can list channels or read their messages. So neither engine covers the whole resource, and a workflow that subscribes to a channel cannot then list it on the same session. Get, Create, Unsubscribe, Delete and Mute are the operations that work on either.
User ID and New Owner ID accept a bare phone number, which the server qualifies into a JID.
Unsubscribe and Delete are the pair to keep straight: the first leaves a channel someone else runs, the second destroys one this account owns. They differ in both verb and path for that reason.
On whatsapp-web.js, since server v0.31.0, Delete, Unsubscribe and Mute answer a 503 that
says the operation may or may not have been applied when WhatsApp reports a timeout, a rate limit or a
server error (408, 423, 429 or 5xx), so check the channel before repeating it; they answered 403, or
a bare 500 for an error of the query itself. An unsubscription from a suspended channel still answers 403. Delete and
Unsubscribe on a page that has not installed whatsapp-web.js's helpers yet, which is a page that is
reloading, answer the retryable 409, where they answered a bare 500.
Call resource
| Operation | Fields | Notes |
|---|---|---|
| Reject | Session Name or ID, Call ID | The call id as delivered by the Trigger's call events. Pair it with call.received to auto-decline. Baileys only: since server v0.23.6 whatsapp-web.js answers 501, where it used to answer 200 without stopping the call from ringing. |
| Create Link | Session Name or ID, Call Type, Start Time | Generates a shareable WhatsApp call link anyone can join. Call Type is Video (the default) or Audio. Start Time is a date-time picker the node converts to epoch milliseconds, reading a date with no timezone in the workflow timezone; leave it empty for now, which is what the blank picker means, because the server requires the field. The response carries the link alone with no expiry, so the node cannot report how long it stays valid. |
Observability resource
Server health, for alerting from inside a workflow. None of these are scoped to a session, so the resource has no Session ID and no other fields.
| Operation | Notes |
|---|---|
| Check | GET /api/health — the server's health JSON as-is. |
| Check Liveness | The liveness probe. |
| Check Readiness | The readiness probe. This is the one that also probes the database connections, so it reports a server that is running but not yet able to serve. |
System resource
Server-wide reporting. Settings are read-only here on purpose: the server derives them from its
environment; the PUT /api/settings route was removed in v0.19.0 after always answering 501.
| Operation | Fields | Notes |
|---|---|---|
| Get Settings | (none) | The server settings document. ADMIN key, unscoped. |
| Get Stats Overview | (none) | Overview statistics across the instance. ADMIN key, unscoped. |
| Get Message Stats | Period | Message statistics across the instance. ADMIN key, unscoped. Period is Last 24 Hours (the default), Last 7 Days, or Last 30 Days, and the bucket size follows from it: hourly for 24 hours, daily for the longer windows. The route binds its query to a DTO, so period is the only key it accepts and anything else is refused rather than ignored. Since server v0.23.6 the byType breakdown counts only messages inside the period; earlier releases let older messages into it. |
| Get Session Stats | Session Name or ID | Statistics for one session. Any valid key except one restricted to selected chats (server v0.23.6+), which answers 403. |
| Get Audit Log | Filters | The audit log. ADMIN key. Unlike the other ADMIN reads here it accepts a session-scoped key, which simply narrows the result. |
| Search | Query, Filters | Cross-session message search. Needs an OPERATOR key, so a VIEWER key answers 403 on this read; q is the only required parameter (checked locally in package 1.4.0: at most 1000 characters and no NUL \u0000 character). 501 means search cannot run: no provider is registered (SEARCH_PROVIDER=none), the built-in provider found no full-text index in the database, or Match is Contains while SEARCH_CONTAINS_ENABLED is not true on the gateway. On an instance running a plugin search provider, 503 means the provider did not answer and is worth retrying, and 502 means it answered with an unusable shape and a retry will not help. The built-in provider returns neither 502 nor 503. |
The Search filters:
| Filter | Type | Notes |
|---|---|---|
| Chat ID | string | Only search within this chat. Deliberately free text, not a dropdown — Search spans every session, so there is no single session whose chats could be listed. From server v0.26.0, with the built-in provider, a phone also matches the chat's other stored forms (the other user dialect and any lid that resolves to it); a plugin provider receives the id as sent. |
| Date From / Date To | dateTime | Bounds on the message time. The UI supplies ISO-8601 and the node converts each to the epoch-milliseconds number the API binds, reading a date with no timezone in the workflow timezone and a date with no time as midnight there; an unparseable value fails the item. |
| Direction | options | Incoming or Outgoing. |
| From | string | Only return messages from this sender. From server v0.26.0, with the built-in provider, it matches from or a group message's author, and a phone also matches any lid that resolves to it; a plugin provider receives the id as sent. |
| Limit / Offset | number | Pagination, defaults 50 and 0. Since server v0.23.6 an Offset above 100000 is refused with 400; before, it was clamped and returned the page at 100000 again. |
| Match | options | Whole Words (word, the default) or Contains (contains), added in package 1.4.0 (server v0.27.0+). On the built-in provider, Contains requires SEARCH_CONTAINS_ENABLED=true on the gateway or answers 501, requires at least one term of 3 or more characters and at most 64 characters across all terms, and ranks the 1,000 most recently stored matches. An older server ignores the parameter and runs a word-prefix search. |
| Session Name or ID | options | Only search within this session. |
| Type | string | Only return messages of this type, for example text or image. |
The Get Audit Log filters:
| Filter | Type | Notes |
|---|---|---|
| Action | string | Only entries for this action, for example session_started or session_stopped. An action the server does not recognise is refused with 400 since server v0.23.7; older servers return an empty page, so a typo looks like no matching activity. Server v0.26.0 adds the plugin actions (plugin_installed, plugin_updated, plugin_uninstalled, plugin_enabled, plugin_disabled, plugin_config_updated, plugin_sessions_updated), which an older server refuses as unknown. Server v0.31.0 writes a webhook_created, webhook_updated or webhook_deleted entry when a webhook is created, changed or deleted through the API (nothing wrote the first and last before) and adds webhook_updated to the list, which an older server refuses as unknown. |
| API Key Name or ID | options | Only entries recorded for this key. Sent to the API as apiKeyId. |
| Limit / Offset | number | Pagination, defaults 50 and 0; Limit is capped at 200 in the UI. |
| Session Name or ID | options | Only entries for this session. |
| Severity | options | One of info (the default), warn or error. A dropdown, not free text. error is reserved: nothing writes it, so that filter returns no rows. |
API Key resource
API-key administration. Every operation except Validate needs the credential itself to carry the ADMIN role. Create returns the new key's plaintext exactly once — capture it in the same execution, because it cannot be read back afterwards.
| Operation | Fields | Notes |
|---|---|---|
| List | (none) | Every key. |
| Create | Name, Fields | Name is required; the Fields collection carries the optional restrictions below. |
| Get | API Key Name or ID | One key. The id, not the key itself. |
| Update | API Key Name or ID, Fields | Partial — only the fields you set are changed, and an empty list never clears an existing whitelist. At least one field is required. |
| Revoke | API Key Name or ID | Deactivates the key. |
| Delete | API Key Name or ID | Removes the key. |
| Validate | (none) | Validates the credential this node is already authenticating with. Works with any valid key except one restricted to selected chats (server v0.23.6+), which answers 403. |
The Fields collection offers:
| Option | Type | Default | Notes |
|---|---|---|---|
| Name | string | — | Update only: a new friendly name for the key. Create takes its name from the required Name field above and does not offer this one. |
| Role | options | Viewer once added; an Operator key if the field is not added | Admin, Operator, or Viewer. Add the field to choose: the node sends no role otherwise, and the server then creates an OPERATOR key. |
| Expires At | dateTime | — | When the key stops working. The node normalises whatever the field resolves to into an ISO-8601 string, reading a date with no timezone in the workflow timezone, and refuses a date already in the past or more than a hundred years out. The server accepts any ISO date and checks neither, so this catches a mistake the API would answer 200 to. |
| Allowed Chats | string list | unset | Restrict the key to these chats. Server v0.23.6 and newer; see the note below the table. |
| Allowed IPs | string list | — | Restrict the key to these addresses. Single IPs and CIDR ranges are both accepted. |
| Allowed Sessions | string list | — | Restrict the key to these sessions, by id. A session name matches nothing, so it silently scopes the key to no session at all. |
Allowed Chats (server v0.23.6+) restricts a key to selected groups and contacts: groups as
<id>@g.us, contacts as <phone>@c.us or <lid>@lid, or bare phone numbers, in any of the shapes
under List fields. A key restricted this way is refused on every route that is not
chat-aware; Credential: OpenWA API lists what stays open to it. An Allowed
IPs, Allowed Sessions or Allowed Chats value that resolves to an empty list fails the item (on Update
too since package 1.2.1), and since package 1.2.1 so does a Role or Expires At that resolves to
nothing, because dropping it would create a key without that restriction or leave an update
unapplied.
Webhook resource
Use these to register, update, or inspect a webhook from a workflow. For an event-driven workflow, prefer the Trigger node, which registers and removes its own webhook automatically.
Create — request body { url, events }, plus secret, retryCount, headers and filters when set.
| Field | Type | Required | Notes |
|---|---|---|---|
| Webhook URL | string | Yes | Destination that receives event deliveries. Surrounding whitespace is dropped, and a blank value fails the item. |
| Events | multiOptions | Yes | One or more events. At least one and at most 27 entries must be selected (the 27-entry ceiling is checked locally since package 1.5.0 and on the gateway since server v0.28.0). An expression can resolve to a comma-separated text, which is read as a list, as on Update (package 1.2.1; before it the text reached the gateway as a string, which it refuses). |
| Webhook Secret | string (password) | No | If set, OpenWA signs each delivery with X-OpenWA-Signature (HMAC-SHA256); 16+ characters required since v0.20.0, and at most 255; the node counts them as the server does, a surrogate pair as one character toward the minimum and code points toward the maximum. Never trimmed. Sent as secret. |
| Additional Fields | collection | No | Optional settings, listed below. |
The Additional Fields collection offers:
| Option | Type | Notes |
|---|---|---|
| Filters | json | Delivery filters as a JSON object in the format of the Trigger's Filters field. Without them, every subscribed event is delivered. |
| Headers | json | Custom delivery headers as a flat JSON object of string values, for example {"X-Team":"ops"}. |
| Retry Count | number | Default 3, 0 to 5. Total delivery attempts per event, including the first; 0 and 1 both mean a single attempt with no retry. |
Update — partial update (PUT): only the fields you set in Update Fields are changed;
everything else keeps its current value.
| Field | Type | Required | Notes |
|---|---|---|---|
| Webhook Name or ID | options | Yes | The webhook to update. The dropdown lists a session's webhooks by delivery URL. |
| Update Fields | collection | No | The changes to apply — see the options below. |
The Update Fields collection offers:
| Option | Type | Notes |
|---|---|---|
| URL | string | New delivery URL. |
| Events | multiOptions | Replaces the full set of subscribed events (not merged). When set, at least one and at most 27 entries must be selected (the 27-entry ceiling is checked locally since package 1.5.0 and on the gateway since server v0.28.0). An expression can resolve to a comma-separated text, which is read as a list (package 1.2.1; before it the text reached the gateway as a string, which it refuses). |
| Active | boolean | Whether the webhook is enabled. |
| Retry Count | number | Total delivery attempts per event, including the first, 0 to 5, default 3. 0 and 1 both mean a single attempt with no retry. An event that exhausts its attempts is listed by Get Delivery Failures, and the webhook stays active. |
| Secret | string (password) | A non-empty value of 16 to 255 characters rotates the HMAC-SHA256 signing secret; an empty value is ignored, so a blank field cannot accidentally unsign a webhook. |
| Clear Secret | boolean | Stops signing. It sends secret: "", which the server reads as "stop signing", so disabling signature verification no longer needs a recreate or a hand-built request. |
| Headers (JSON) | json | Custom delivery headers as a flat JSON object of string values, for example {"X-Team":"ops"}. Headers are non-nullable server-side — clear them by sending {}. |
| Filters (JSON) | json | Advanced delivery filters as a JSON object, for example {"conditions":[...]}. Enter null to clear existing filters. |
Get / List / Delete / Test — read, remove, or probe a webhook.
| Operation | Fields | Notes |
|---|---|---|
| Get | Session Name or ID, Webhook Name or ID | One webhook. |
| List | Session Name or ID | The session's webhooks. |
| Delete | Session Name or ID, Webhook Name or ID | Removes it. |
| Test | Session Name or ID, Webhook Name or ID | Sends a test delivery. |
List All, Get Delivery Failures and Redrive Delivery Failures span every session, so none shows a Session ID field.
| Operation | Options | Notes |
|---|---|---|
| List All | Limit (1 to 1000), Offset | Webhooks across all sessions. GET /api/webhooks binds only limit and offset, so no session filter is offered — one there would be accepted by the UI and then ignored by the server. |
| Get Delivery Failures | Limit (1 to 1000), Offset, Session Name or ID | Failed deliveries; this route is the one that does accept a session filter. ADMIN key. |
| Redrive Delivery Failures | Failure IDs, Limit, Session ID, Webhook ID | Replays recorded failed deliveries. ADMIN key, server v0.25.0 and newer. |
Redrive Delivery Failures replays failed deliveries with one direct POST per row, under the original event's idempotencyKey, so a receiver that already handled the event can drop the replay. The gateway keeps a failed delivery's payload only while WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS is above 0; it defaults to 0, and then nothing is replayed and every count in the answer is zero. An eligible row is a terminal failure, inside the retention window, that still holds its payload. A webhook that was deleted, disabled or unsubscribed from the event is skipped, and a session-restricted key never touches rows outside its sessions. Request body {}, plus ids, limit, sessionId and webhookId when set; the Options collection offers:
| Option | Type | Notes |
|---|---|---|
| Failure IDs | string list | Failure row ids from Get Delivery Failures, at most 500 ids of at most 128 characters each. An explicit empty list replays nothing. |
| Limit | number | Rows replayed by this call, 1 to 500. Left out, the server replays up to 100; the field shows 50 once it is added. |
| Session ID | string | Only failures of this session, at most 128 characters. |
| Webhook ID | string | Only failures of this webhook, at most 128 characters. |
The answer is one item: delivered rows were sent and their failure rows removed, failed replays failed again and their rows stay with the attempt count raised, skipped rows were not replayed, and remaining is how many replayable rows are still in scope. redriven equals delivered, and enqueued is always 0 because a redrive never uses the queue.
Automation Rule resource
Server-side auto-reply rules. Every operation takes Session Name or ID; Get, Update and Delete also take a Rule ID, the value Create or List returned.
| Operation | Fields | Notes |
|---|---|---|
| List | (none beyond the session) | The session's rules, one item per rule. |
| Get | Rule ID | One rule. |
| Create | Name, Reply Text, Conditions, Additional Fields | Name is capped at 100 characters and Reply Text at 4096. |
| Update | Rule ID, Update Fields | Only the fields you add are sent; anything left out keeps its stored value. |
| Delete | Rule ID | Removes it. |
Conditions is JSON in the same shape as a webhook filter,
{"conditions":[{"field":"isGroup","operator":"is","value":false}]}. Every condition must match.
Leave it empty and, since gateway v0.23.7, the rule answers every inbound message except those in chats whose kind is channel, broadcast or status; a kind condition that names them is needed to answer there. The guards a rule always respects are described in Automation rules.
Additional Fields on Create, and Update Fields on Update, both carry Cooldown (Seconds)
(default 60, 0 to 86400, how long the rule stays quiet in a chat once it has fired there) and Enabled (default
true). Update additionally accepts Name, Reply Text and Conditions.
A matching message is answered even when the workflow is not running, which makes them the right tool for an out-of-hours acknowledgement and the wrong one for anything needing workflow logic. Conditions use the same field set as webhook filters, so they only ever see message events.
Catalog resource
Reads a WhatsApp Business product catalog. Every operation takes Session Name or ID.
| Operation | Fields | Notes |
|---|---|---|
| List Products | Options (Limit, Page) | Products, paginated. The fields show a Limit of 50 and a Page of 1 once added; with no option set, the server uses a page size of 20. |
| Get Product | Product ID | One product. |
| Get | (none beyond the session) | The catalog's own metadata. |
503 here can be permanentwhatsapp-web.js answers 501 on every catalog operation. Use List Products to find the product
id that Message → Send Product needs. Baileys reads no stock state from WhatsApp and reports isAvailable as true for every product, including hidden ones. A 503 means WhatsApp did not answer the catalog query
within the request budget, or rate-limited it. For some business accounts WhatsApp never answers it,
so a retry may not help.
Media resource
Server-side conversion into the formats WhatsApp actually plays. Every operation takes Session Name or ID.
| Operation | Fields | Notes |
|---|---|---|
| Check Availability | (none beyond the session) | Whether conversion is configured and ffmpeg is runnable. |
| Convert to Voice Note | Media Source, and the field that source needs | Produces Ogg/Opus. |
| Convert to Video | Media Source, and the field that source needs | Produces a compatible MP4. |
Media Source selects one of Binary (default; takes Input Binary Field, default data),
URL (takes Media URL), or Base64 (takes Base64 Data). No MIME type is sent, because the
server reads it from the bytes.
Conversion returns base64 and mimetype ready to feed straight into a send. Convert to Voice
Note produces the Ogg/Opus that Message → Send Audio (Base64 source, Send as Voice Note on) or
Status → Send Voice needs; Convert to Video produces the MP4 for Message → Send Video.
Nothing else in the pipeline transcodes, so without this an MP3 sent as a voice note produces a
microphone bubble that will not play. Conversion is opt-in on the server and needs ffmpeg: run
Check Availability first, and read a 503 as conversion being disabled or busy (or, since v0.26.0, the gateway shutting down) rather than as a
bad request. A URL source on a session with an egress proxy is the exception: since server v0.23.6
the gateway fetches it through that proxy, as it does for a send (see
Media source model), and a 503 can also mean that fetch failed before any
response. Since v0.23.6 an input that is not a single-file media container, such as a playlist or a
manifest, is refused with 400.
Presence resource
Presence subscription, per-chat reads, and the account's own availability. Every operation takes Session Name or ID.
| Operation | Fields | Notes |
|---|---|---|
| Subscribe | Chat Name or ID | Subscribes to presence updates for that chat, so presence.update events start arriving. A bare number fails the item: give a full WhatsApp ID including its domain, such as 628123456789@c.us. |
| Get | Chat Name or ID | The last reported presence for that chat. Answers an empty object when nothing has been reported yet. |
| Set Own Presence | Available | Whether the account announces itself as online. |
A chat subscription lives on the socket, so a restart, a Stop/Start, or any automatic reconnect
ends it, and nothing on the server re-issues it. The account's own availability is remembered while
the engine runs: since server v0.24.0 the gateway re-applies the last Set Own Presence each time
the same engine's connection reopens, which covers a Baileys transient reconnect. It is dropped when
the engine is replaced by a stop, a restart, a gateway reconnect, a watchdog recycle or a takeover by
another node; every reconnect on whatsapp-web.js is a gateway reconnect, so it never survives one
there. Re-run these from a Trigger branch on session.status reaching ready, not once at workflow
start. Subscribe is Baileys only; whatsapp-web.js answers 501 and never reports presence at
all.
Set Own Presence has a side effect worth knowing: WhatsApp routes notifications away from the phone while a linked device is online, so a workflow-driven session left available suppresses the account holder's own alerts. Turn it off to hand them back. There is no read-back, and the setting is dropped whenever the engine is replaced.
Output and error handling
On success, each input item produces one output item containing the OpenWA JSON response, with two
exceptions. A route answering a bare JSON array emits one item per row on node version 2, each
carrying pairedItem back to the input item that produced it; on node version 1 that array stays
whole on the single item. And the two media reads, Message → Get Media and Status → Get
Media, return raw bytes, which the node attaches as a binary property rather than putting on
json, leaving that item's json empty. A DELETE that answers 204 No Content surfaces as
{ "success": true } so downstream nodes receive a readable item instead of an empty one.
The action node declares versions 1 and 2. Version 2, which a newly added node gets, emits one
item per row for a route answering a bare JSON array. Version 1 keeps the whole array on a
single item's json, exactly as 0.10.0 did. n8n keeps a node's saved version across package
upgrades, so a workflow built before 1.0.0 that reads {{ $json[0].id }} is unaffected by the
upgrade and needs no change.
1.0.0 shipped the per-row output under version 1, so a node added while on 1.0.0 carries
version 1 too and returns to the whole array once the package is upgraded to 1.0.1. Delete and
re-add that node to move it to version 2.
On version 2:
{{ $json[0].id }}becomes{{ $json.id }}, evaluated once per row.{{ $json.length }}becomes{{ $('OpenWA').all().length }}.- A Code node reading
$input.first().jsonas the array reads$input.all().map(item => item.json), or switches to Run Once for Each Item and reads$json. - A Split Out node placed after the operation to fan the array out is redundant, and fails because it has no field left to point at. Remove it.
An empty list emits zero items on version 2, not one holding [], so the next node does not run
at all. Turn on Always Output Data where a branch must continue past an empty result, and drop
any {{ $json.length === 0 }} check, which no longer has an item to run on. With several input items
the output is one flat list: three input items listing ten chats each produce thirty items.
The nineteen affected operations: Session → List All; Chat → List; Contact → List and List Blocked; Group → List and Get Membership Requests; Message → Get History and Get Reactions; Label → List, Get Chats and Get for Chat; Template → List; Channel → List and Get Messages; Webhook → List, List All and Get Delivery Failures; Automation Rule → List; API Key → List.
Contact → List Blocked answers bare id strings, and a string is not valid item json, so on
version 2 each row arrives wrapped: { "data": "628123456789@c.us" }. Version 1 passes the bare
array of strings through untouched.
Operations answering an envelope keep their single item and their nested array on both node
versions, because spreading the rows would lose the envelope's own fields: Message → List
({ messages, total }), System → Search, System → Get Audit Log, Status → List and Get
by Contact, Contact → Get Profile Pictures, and Catalog → List Products, whose pagination
would be lost with it.
The node fails the workflow on the first error unless the node's On Error setting continues past
it. With Continue, the failing item stays on the main output as { "error": "<message>" }, plus a
description holding the gateway's explanation when it gives one that differs from the message, and
processing continues. With Continue (using error output) the item goes to the error output
instead: the input item's own fields plus an error that ends with the gateway's reason,
<message>: <reason>, so a field such as message is still there for a retry (package 1.0.1 sent
that case to the success output as { error, description }). Validation problems
(empty chat id, non-digit phone number, no event selected, malformed session id, a poll outside 2–12
options, an oversized participant list) surface as node errors carrying the offending item's index;
HTTP failures from OpenWA surface as API errors carrying the server's status and message. Since package
1.1.0, input that 1.0.1 dropped, altered or left for the server to reject, such as an update field
whose expression found nothing, fails the item with an error that names the field.
Package 1.2.1 adds three checks that apply across operations, besides the ones in the field tables.
A query option that narrows a list and is left without a value fails the item with its name, where it
used to return everything: Message > List Chat Name or ID and From, the System > Search and Get Audit
Log filters, and Webhook > Get Delivery Failures Session. A blank value in the other Message > List
filters (Since, Until, Direction, Order By, Type and Message ID) already failed in 1.2.0. Limit,
Offset, Page, After Row ID, Inline Media, Deep and Include Media are the exceptions to the blank
rule: left without a value they fall back to the server's default. A list or an object given to any
option of the Session, Chat, Contact, Message, Channel, Catalog, System or Webhook list and search
operations fails the item too, except a list given to Session > List All Name, which is read as
text first (an object still fails there).
A 200 reply that is plain text or a bare number or boolean, such as a page from a proxy, a captive
portal or a wrong path in Server URL, fails the item instead of passing the page on as a result;
a JSON object or array is accepted. And a path ID with no text form, such as an object, fails with
its field name rather than putting [object Object] in the URL.
Since server v0.23.6 some of those statuses changed, which matters to a workflow that branches on
them. On whatsapp-web.js, the operations that read a WhatsApp Web timeout as a missing target or a
refusal now answer 503 when WhatsApp Web does not answer in time: Group → Get, Get Settings, Get
Join Info and Join, Contact → Get Info, Label → Get Chats, Chat → Mark Read, Mark Unread, Clear
Messages, Archive and Delete, and the chat lookup that Chat → Pin and Mute run first. Earlier
releases answered them with a misleading 404, 400 or success: false. Other operations were
not changed by v0.23.6. Since server v0.24.0 a timeout on Chat → List, Contact → List, Group →
List, the Chat → Pin and Mute writes themselves, and Presence → Set Own Presence also answers
503. A timeout on Group → Update Subject or Contact → Block, for example, still answered
500 until server v0.31.0 (see below). That 503 says nothing about whether the target exists, and a write such as Group → Join may
still take effect. Also on whatsapp-web.js, Reply on a chat the session cannot resolve, and
Forward whose From Chat Name or ID the session cannot resolve, answer 404 (an unresolvable
To Chat Name or ID does not), and Status → Delete on a status that is not the account's own
answers 403; all three answered 500 before. On Baileys, a group that no longer exists answers 404 rather
than 403 on every write and on Group → Get Invite Code and Get Membership Requests, while a group
the account left still answers 403. Baileys also answers 404 to Channel → Subscribe for an
unknown invite code and to Channel → Get for an unknown channel, and 403 when WhatsApp refuses a
Subscribe or Unsubscribe; all of these answered 500 before. On either engine, Template → Create
and Automation Rule → Create answer 404 for a session that does not exist, not 500.
Since server v0.26.0, on Baileys a message send, React, Edit, Delete, Pin or Unpin, or a Status post
or delete, that WhatsApp turns away with a rate limit or leaves unanswered answers 503, where it
answered 500. A rate-limited request sent nothing; after a timeout the outcome is not proven. On
whatsapp-web.js, a read that WhatsApp Web's page reload cuts short answers a retryable 409
instead of a bare 500, and a group, contact, label or invite lookup cut short that way is no longer
reported as 404; Group → Join answers 503 then, because the join may have landed. A
whatsapp-web.js write that races a session stop or teardown answers 409, not 500 or 503.
While WhatsApp Web reloads its page, a whatsapp-web.js session still reads ready and an operation
that reaches the engine answers 409. Since server v0.31.0 that 409 carries code
ENGINE_PAGE_RELOADING and retryAfterSeconds (5) in the gateway's body, and its message reads
"WhatsApp Web is reloading its page and the session is re-injecting. Retry every few seconds: this can
last a few minutes.", where it read "Retry in a few seconds.", so a workflow that matched the old text
has to match the new one or the 409 status. Most reloads take seconds, no event marks the end of one,
and a request that gets this 409 is safe to repeat, so ask again at that interval (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). The same 409
answers a read, a write that converges when repeated, the invite code revoke and the check made before
adding participants when they reach a document WhatsApp Web has not booted yet.
A send, Reply, Forward or Status post that a page reload cut 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 above, and nothing was sent) answers a different 409,
with no code, that says the message may or may not have been sent or published (since server v0.31.0;
a bare 500 before). Check the chat, or your Status, before sending again. A keyed send keeps its
Idempotency Key, so a retry with the same key answers 409 with code
IDEMPOTENCY_OUTCOME_UNKNOWN. On Baileys the same kind of 409 answers a send, Status post, Status
delete, React, Edit, Pin or a Delete that revokes the message for everyone, whose connection was replaced or stopped while it was being
written, where it answered that the session was not connected.
Since server v0.31.0 a whatsapp-web.js timeout, where WhatsApp Web does not answer within the protocol
timeout, also answers 503 on these operations, where it answered 500: Contact → Save, Delete, Block
and Unblock; Profile → Set Name, Set Status, Set Picture and Delete Picture; Group → Update Subject,
Update Description, Update Settings, Set Picture, Delete Picture, Get Invite Code and Get Membership
Requests; Channel → List, Get, Get Messages, Unsubscribe, Delete and Mute; Label → List, Get, Get for Chat,
Add to Chat and Remove From Chat; Message → React, Edit, Delete, Star, Pin, Unpin, Vote Poll, Get
Reactions, Get Receipts and Get History; and Status → Delete. A timeout in the group lookup, or in the
check for the invitation sender, in front of a group write answers 503 too, since nothing has been
applied. Sends, Status posts and the other writes keep the answer they had. A timeout on Group →
Revoke Invite Code still answers 500, since the revoke may already have rotated the code: read the
current code before repeating it.
Since server v0.31.0 whatsapp-web.js also answers 501 when the WhatsApp Web build the session runs
has no job to carry the operation out. Nothing is asked of WhatsApp, so the group, picture, About text
or pin is unchanged, and the operation works on a build that has the job. This depends on the build,
not on the engine, and it applies to Group → Join, Get Join Info, Get Invite Code, Revoke Invite Code,
Update Subject, Update Description, Set Picture and Delete Picture; to Update Settings when it sets
Announce, Locked or Member Add Mode; to Profile → Set Status, Set Picture and Delete Picture; and to
Message → Pin and Unpin.
OpenWA Trigger (node)
The trigger node registers a webhook with OpenWA when the workflow activates and starts the workflow each time a subscribed event arrives. It has no input; its single output emits one item per delivery.
Fields
| Field | Type | Required | Notes |
|---|---|---|---|
| Session Name or ID | options | Yes | Session to receive events from, chosen from the same dropdown the action node uses. Sanitized like the action node (no empty, .., /, or \). |
| Events | multiOptions | Yes | Events to subscribe to. Default ['message.received']. At least one and at most 27 entries must be selected (since package 1.6.0, the 27-entry ceiling is checked locally before registration and an expression resolving to a comma-separated text is normalized to a list in both registration and config-hash comparison, matching Webhook → Create and Update). |
| Webhook Secret | string (password) | No | Shared secret for signature verification, 16 to 255 characters. The node checks the length itself before registering, so a short one fails at activation rather than as a server 400. Since package 1.4.0 signature verification also coerces the secret to a string, so an expression resolving to a number verifies deliveries with the same secret string registered on the gateway. See Signature verification. |
| Filters | json | No | Server-side filters, {"conditions":[{"field":"type","operator":"is","value":["text"]}]}. The gateway drops a non-matching event before delivering, so it never starts an execution. Conditions are ANDed, at most 20. Fields: sender, recipient, chatId, body, type, isGroup, kind, fromMe, hasMedia, mentions. chatId (server v0.23.6+) scopes the Trigger to chosen chats or groups; write a group as its full <id>@g.us, since bare digits are read as a contact. An older server refuses a chatId condition as an unrecognized filter field with 400, so the workflow fails to activate. A contact in sender, recipient, chatId or mentions can be written as digits, <phone>@c.us or <lid>@lid. Since server v0.23.6 a condition naming an @lid keeps matching after the gateway learns that contact's phone number; earlier releases silently stopped matching it then, so an is condition went quiet and an isNot condition let the chat through. From server v0.26.0 a lid and a phone count as the same contact only once an engine has reported the pair, so a mapping stored before the upgrade does not bridge them until it is reported again. kind (server v0.23.4+) is the only way to single out or exclude a Channel post, which isGroup reports as false along with everything else. Filters narrow message events only: session, group, call, poll.vote and event.response events arrive regardless. Within the message family an is condition on a field an event does not carry suppresses that event outright, so a sender filter combined with Message Ack or Message Failed suppresses both because they carry no sender. Before server v0.25.0 the same applied to chatId; v0.25.0 adds chatId to these events, so chatId and kind can now scope their delivery, and for message.receipt (server v0.26.0+) only chatId and kind read a value from its payload. Two kinds of condition let every such event through instead: isNot on the missing field, and a boolean (isGroup, fromMe, hasMedia) compared with false, since an absent boolean reads as false. A filtered-out delivery is silent, so an over-strict filter looks exactly like nothing having happened. Each Trigger registers its own webhook, and a session holds 16 by default (WEBHOOK_MAX_PER_SESSION), so give each filter set its own Trigger. |
| Deduplicate Deliveries | boolean | No | Default off. Drops a repeated delivery of the same idempotencyKey, remembering the 500 most recent keys in workflow static data as 16-character fingerprints (package 1.1.0 and newer; keys an earlier release stored raw still match). Best-effort: two deliveries arriving at the same moment can both pass, and a retry whose first run failed is also dropped — enable it only when downstream actions are not idempotent and failed runs are rare. From n8n 2.19.2 until n8n fixed it in 2.46 (the fix is in the source of 2.46.4 and later), n8n does not save the record, so the option has no effect there: de-duplicate downstream on idempotencyKey instead. |
The delivery path carries the session (…/webhook/openwa-<sessionId>), so a glance at the URL says
which session it serves. What keeps two Triggers apart is the prefix n8n puts in front of that path:
the node's own webhook id, or the workflow id plus the node name when the node has none. That prefix
is per node instance, so even two Triggers on the same session inside one workflow get distinct
delivery URLs. The session segment is there for legibility, not isolation.
Webhook lifecycle
The node manages its own OpenWA webhook across activation and deactivation. It stores the returned webhook id — along with the session it was registered on and a hash of the registration configuration — in workflow static data, and reuses them on later checks.
- On activate, the node compares a hash of the delivery URL, events, secret, session, and filters
against the stored one. A mismatch means the registration is stale: it is deleted from the session
it was registered on and recreated with the current configuration. Otherwise the node confirms the
webhook still exists with
GET /api/sessions/{sessionId}/webhooks/{webhookId}, and creates one withPOST /api/sessions/{sessionId}/webhooksif it does not. A404there means recreate; any other error is inconclusive, so it propagates rather than risking a duplicate registration, which the server would not de-duplicate by URL. Since package1.1.0, before it creates one the node also lists the session's webhooks and deletes every one whose URL equals this Trigger's URL, including one made by hand, because an activation that failed at a later Trigger in the same workflow leaves a registration whose id was never saved. - Existing is not the same as delivering, so the node also checks the registration it read back.
The server dispatches only to webhooks with
active: true, and the URL, the event list, and the filters can all be edited out from under the node, from the dashboard, the API, or the action node's own Webhook → Update. Any of those would leave the trigger reporting healthy while nothing reached it, so a drifted registration is deleted and rebuilt exactly like a stale one. Filters are compared ignoring key order, since the server round-trips them through a JSON column. The secret is the one registered field not compared: the server never serializes it back, and the config hash already catches a local change to it. - On deactivate, the node issues
DELETE /api/sessions/{sessionId}/webhooks/{webhookId}. A404is treated as already deleted; any other error propagates so activation fails loudly rather than orphaning a registration that would keep delivering.
Changing the secret, the events, the filters, or the session takes effect on the next activation — deactivate and reactivate the workflow, and the node re-registers automatically. Editing the registration on the server has the same effect in reverse: the node notices on the next activation and rebuilds it from the workflow's own configuration. No manual cleanup on the server is needed. Before changing Server URL on a credential used by an active Trigger, deactivate the workflow while the original server is still configured and confirm its webhook was removed there, then switch servers and activate again.
On a gateway running with QUEUE_ENABLED=true, server v0.23.6 and newer re-read the registration
before each delivery attempt. A delivery still queued when the old registration is deleted, disabled
or unsubscribed from the event is dropped, and one queued before a URL or secret change goes out with
the current values. Earlier releases sent queued deliveries and their retries with the URL and
signature captured when they were queued, so after a secret change the Trigger rejected them with
401 and they appeared under Webhook → Get Delivery Failures.
Events
The Events field offers the same list in both the trigger and the action node's Webhook → Create and
Update operations, mirroring core's own event catalog through v0.31.0. Package 1.8.1 offers all
twenty-six events:
| Event | Fires when |
|---|---|
message.received | A new message is received. |
message.sent | A message is sent successfully. |
message.ack | A message delivery or read acknowledgement occurs (for messages the account sent since server v0.27.0; on Baileys since server v0.28.0 also fires delivered and read for group messages once every non-self member has delivered or read). |
message.receipt | A per-recipient delivery, read, or play receipt arrives for a message the account sent to a group or a Status. Baileys only, and requires server v0.26.0 or newer; delivered only to a webhook that explicitly names message.receipt, because * does not cover it. |
message.failed | A message fails to send. |
message.revoked | A message is deleted for everyone (on Baileys since server v0.28.0 a non-admin group delete of another member's message is ignored). |
message.edited | A message's text, or a media message's caption, is edited. The payload carries the new text and a hasMedia flag, never replacement media: WhatsApp cannot edit the attachment itself. |
message.reaction | A reaction is added to or removed from a message. On Baileys (server v0.23.6+), a reaction the account made from its phone in a one-to-one chat carries the account as senderId; earlier releases reported it as the contact's, replacing the contact's own entry in the payload's reactions map. |
poll.vote | A voter changes their selection on a poll. Both engines: whatsapp-web.js on server v0.26.0 or newer, and Baileys since server v0.30.2, which reports a vote only while the poll's creation message is still in the session's message store (earlier votes are not backfilled). Both engines cap selectedOptions at 32 entries of 1024 characters and pollName at 1024 characters (server v0.30.2+). Not narrowed by server-side message filters. |
status.received | A contact's Status (Story) is received. |
session.status | Any session status change. |
session.qr | A new QR code is generated. |
session.authenticated | The session is authenticated. |
session.disconnected | The session loses connection. |
session.reconnect_loop | A session is stuck in a reconnect loop — once per 5 consecutive attempts. |
session.restriction | WhatsApp places or lifts a restriction on the account (including Baileys kind: "passkey_required" since server v0.30.0). |
presence.update | A subscribed chat's presence changes. Baileys only, and silent until the chat is subscribed with POST /api/sessions/{sessionId}/presence/subscribe; whatsapp-web.js answers that route with 501. |
event.response | A guest RSVPs to a WhatsApp event invitation. Baileys only, and silent on whatsapp-web.js; needs server v0.25.0 or newer. The payload is described under RSVP payloads. |
group.join | A participant joins a group the session belongs to. It also fires when the session itself is added to or joins a group, though not for a group it created. whatsapp-web.js has always reported that join; Baileys does since server v0.23.6, with only the session's own id in participantIds, not the members added with it. |
group.leave | A participant leaves a group the session belongs to. |
group.update | A group's metadata changes (subject, description, settings). A participant joining or leaving is group.join or group.leave, and an admin promotion or demotion produces no event. |
group.join_request | Someone asks to join a group the session administers. Fires only when the group has admin approval enabled. |
call.received | An incoming WhatsApp call is detected. Both engines, but not reliable on whatsapp-web.js; one known cause is a WhatsApp Web build that lacks the call hook the library patches. The caller in data.from can be an @lid privacy id on either engine; resolve it with Contact → Get Phone before using it as a phone number. |
call.accepted | An incoming call is answered. Baileys only. |
call.rejected | An incoming call is declined, including by auto-reject. Baileys only. |
call.missed | An incoming call goes unanswered. Baileys only. |
whatsapp-web.js hooks the call collection's insert and sees no status at all, so it can report the
ring but never how the call ended. A workflow triggered on call.accepted, call.rejected, or
call.missed simply never runs on a whatsapp-web.js session. call.received fires on both engines
but is not reliable on whatsapp-web.js. One known cause is a WhatsApp Web build that lacks the call
hook, which leaves the session reporting no call at all; since server v0.23.6 such a session logs a
call_hook_missing warning when it reaches ready and can see that the hook is missing.
Every event above except event.response, message.receipt, and poll.vote exists on every server this package supports, so no
per-event version floor discriminates between them any more — the ≥ 0.16.0 package floor covers the
rest of the catalog. event.response needs server v0.25.0 or newer, and message.receipt and poll.vote (added in package 1.3.0) need server v0.26.0 or newer, because the gateway refuses to
register a webhook for an event it does not know. On Baileys, poll.vote is accepted from v0.26.0 but reports nothing before v0.30.2. See Compatibility.
group.join_request joined this catalog in package 0.9.2; core has dispatched it since v0.15.0.
On 0.9.1 it is absent, and because the trigger and the Webhook → Create and Update operations
share this one list, no node offers it there. On that version, register the subscription by hand
with n8n's HTTP Request node against POST /api/sessions/{sessionId}/webhooks, pointing it at
an n8n Webhook node's URL.
Output shape
Each delivery is an envelope. The node passes the parsed JSON body straight through, so $json is
the envelope and the event-specific payload is under data.
| Field | Description |
|---|---|
event | The event name, for example message.received. |
timestamp | ISO 8601 time the event was emitted, for example 2024-01-15T10:30:00Z. |
sessionId | Session the event belongs to. |
idempotencyKey | Stable key for the logical event. |
deliveryId | Identifies a single delivery attempt. Re-minted on a crash replay, so it is not a dedup key. |
data | The event payload. Read message fields from here. |
{
"event": "message.received",
"timestamp": "2024-01-15T10:30:00Z",
"sessionId": "default",
"idempotencyKey": "a1b2c3d4-...",
"deliveryId": "e5f6a7b8-...",
"data": {
"id": "3EB0F5A2B4C...",
"chatId": "628123456789@c.us",
"from": "628123456789@c.us",
"body": "Hello!",
"type": "text",
"timestamp": 1705312200
}
}
Reading the output:
- Reference payload fields through
data, for example{{ $json.data.body }}and{{ $json.data.chatId }}. - Read the message identifier from
data.id. Incoming payloads useid, notmessageId. - OpenWA delivers at least once: a failed POST is retried and a crash-stranded delivery is replayed, both under the same
idempotencyKey. De-duplicate on that key if your downstream actions are not idempotent, with a Remove Duplicates node, or with the node's Deduplicate Deliveries toggle where n8n saves its record (not from n8n 2.19.2 until the fix in 2.46, see Deduplicate Deliveries under Fields). Do not key ondeliveryId: a replay carries a new one. - Message
typeis engine-neutral: voice notes arevoice, shared contacts arecontact, and plain chats aretext. - Some payloads carry extra fields under
data:type: "masked"marks a withheld business message, amessage.revokedevent carriesrevokedId(the id of the revoked message), and since server v0.29.1 a forwarded message onmessage.receivedormessage.sent(either engine) carriesisForwarded: trueand, when positive,forwardingScore(both absent on non-forwarded messages and stripped onrevokedplaceholders). - On Baileys (server v0.23.6+), a WhatsApp Business prompt that offers choices carries
buttons: [{ id, text }], leaving out URL and call buttons, and a tapped button, template quick-reply, list row or native-flow control arrives astype: "text"withbutton: { id, text? }and the visible label inbody. Before v0.23.6 button, template and list replies, and list prompts, were typedunknown, so atypefilter ontextnow lets them through. whatsapp-web.js carries neither field. Message → Click Button answers such a prompt: give it the prompt'sdata.idas Message ID and one of itsbuttons[].idas Button ID (see Message resource). - On Baileys (server v0.23.6+), activity from while the session was offline arrives once it reconnects: inbound messages as
message.received, those the account sent from its phone or another linked device in that window asmessage.sent, and reactions, edits and deletions made in that window, by the account or by anyone else, asmessage.reaction,message.editedandmessage.revoked. Earlier releases dropped all of them. A workflow that should not act on that backlog, such as an auto-reply, can comparedata.timestamp(epoch seconds) with the current time; amessage.reactionpayload carries no timestamp, so a reaction from the backlog cannot be told apart this way.
If the request body is missing or not an object, the node emits no items for that delivery rather than failing.
Signature verification
When Webhook Secret is set, OpenWA signs each delivery and the node verifies it before running the workflow. The signature scheme:
- OpenWA computes
HMAC-SHA256(secret, rawBody)over the exact bytes it transmits and sends the result asX-OpenWA-Signature: sha256=<hex>. - The node reads the raw request body — it does not re-serialize the parsed JSON, which could reorder keys or change whitespace and reject a valid delivery — then recomputes the expected
sha256=<hex>and compares. - Comparison uses a constant-time check (
timingSafeEqual). A length mismatch is treated as a non-match before the comparison runs. - Verification returns false when either the secret or the signature header is absent. With a secret configured, a delivery whose signature is missing or wrong is rejected with HTTP 401 and produces no workflow run.
- If the running n8n cannot supply the raw body at all, the node logs a warning and rejects the delivery with
401rather than silently re-serializing and dropping valid deliveries at random. - A delivery whose raw body cannot be read at all, such as a multipart one that n8n consumes before the node runs, is refused with
401the same way. The package notes that before1.2.1the uncaught error was recorded as an error execution, which anyone who knew the URL could repeat.
Leave Webhook Secret empty to skip verification and accept unsigned deliveries, in which case
anyone who knows the Trigger's URL can start the workflow, so set one when n8n is reachable from
outside. The signature covers the body only and OpenWA sends no signed timestamp header, so a captured
delivery can be replayed unless the workflow de-duplicates on idempotencyKey. For end-to-end
webhook setup and the same signature scheme used outside n8n, see Webhooks.
Common errors
| Symptom | Cause | Fix |
|---|---|---|
| Credential test fails on save | API key rejected by GET /api/sessions. A 401 means the key is missing, unknown, revoked or expired. A 403 means the key is valid but refused: it is restricted to selected chats (server v0.23.6+), or, since server v0.24.0, the address n8n calls from is outside its allowedIps or cannot be determined (older servers answered 401 for that). A key restricted only by allowedSessions passes this test. | Use a valid key from the dashboard; see Authentication. Check the key's allowedIps against the address n8n calls from. A chat-restricted key never passes this test, but still works on the operations listed under Credential: OpenWA API. |
Session ID contains invalid characters | Session id has .., /, or \ | Pick the session from the dropdown, or supply its UUID from an expression. |
Chat ID cannot be empty | Message sent with no Chat ID | Provide a chat id like 628123456789@c.us. |
Phone number must be digits in international format | Check Exists or Get LID got an @lid, group, channel, or non-digit input that survived stripping | Pass digits in international format (for example 628123456789) or a @c.us / @s.whatsapp.net user JID. |
| Base64 image or document rejected by OpenWA | Missing MIME type on a base64 payload | Set the MIME Type field, or use the Binary Data or URL source. |
Message → Send Image, Send Video, Send Audio or Send Document, or Status → Send Image, Send Video or Send Voice, answers 500 while Send Text works, and the gateway log shows Data passed to getter must include an id property | A whatsapp-web.js session on a WhatsApp Web build rolled out from 2026-09-17, against a server older than v0.23.6 | Upgrade the gateway to v0.23.6 or newer, which patches whatsapp-web.js at install time. Baileys sessions are not affected. |
400 when creating a webhook | The server does not know one of the selected events, or a filter field | session.restriction, presence.update, call.accepted, call.rejected, and call.missed need OpenWA ≥ 0.14.0; group.join_request needs ≥ 0.15.0; event.response needs ≥ 0.25.0; message.receipt and poll.vote need ≥ 0.26.0. The kind filter field needs ≥ 0.23.4 and chatId ≥ 0.23.6. Upgrade the gateway, or deselect the events and drop the conditions it does not know. |
404 on one operation while the rest work | The route postdates the server | Session → Get Proxy and Update Proxy need a server on v0.23.4 or newer, Message → Click Button v0.23.6, Webhook → Redrive Delivery Failures v0.25.0, Group → Set Member Label v0.27.0, Contact → Get LID v0.27.1, and Message → Get Receipts v0.28.0; every other route the node calls exists from v0.16.0. See Compatibility. |
| A call-outcome trigger never runs | The session runs whatsapp-web.js | call.accepted, call.rejected, and call.missed are Baileys-only. call.received also fires on whatsapp-web.js but is not reliable there; for dependable call events, run the gateway on Baileys (ENGINE_TYPE=baileys). The engine is instance-wide, and a session must be linked again under it unless it still holds a Baileys link from an earlier run. |
501 on Call → Reject | The session runs whatsapp-web.js (server v0.23.6+) | That engine cannot stop a ringing call, so rejection, autoRejectCalls included, is Baileys-only. |
| Trigger fires once and then goes quiet | The webhook was registered against n8n's test URL, which stops after one delivery | Activate the workflow so the trigger registers its production URL. |
| Trigger subscribed to a group event never runs | The session isn't a member of any group, or no group activity has occurred | Confirm the session has joined a group and that group activity (joins, leaves or metadata changes) is happening. group.join, group.leave, and group.update are emitted by both engines. |
401 Unauthorized on every delivery | Signature mismatch between server and node secrets | Use the same Webhook Secret on both sides; reactivate the workflow after changing it. |
403 on an operation that used to work | The credential's role is too low, or its session or chat scope is too narrow | Writes need an OPERATOR key, and so do several reads: Session → Get QR, Contact → Check Exists (server v0.24.0+) and Get LID (server v0.27.1+), Group → Get Invite Code (server v0.23.5+), Template → List and Get, Webhook → Get, List and List All, System → Search, and every Automation Rule operation. The API Key resource (except Validate), System → Get Settings, Get Audit Log, Get Stats Overview and Get Message Stats, and Webhook → Get Delivery Failures and Redrive Delivery Failures need an ADMIN key, and since server v0.24.0 so do Session → Update Proxy and Session → Create with a Proxy URL. Separately, a session-scoped key is refused outright on the API-key operations other than Validate, on System → Get Settings, Get Stats Overview and Get Message Stats, and on Session → Create and Update Proxy, whatever its role. A key restricted to selected chats (allowedChats, server v0.23.6+) is refused on every operation the gateway has not opened to such keys, the credential test and the Trigger's registration included. On an open one it is refused for any chat outside its list, and on a send that carries Quoted Message ID unless the operation is Reply. Credential: OpenWA API lists the open operations. |
409 on Request Pairing Code | The session has not reached qr_ready yet, a code was already accepted, or (whatsapp-web.js, server v0.26.0+) the number is the stored phone of another session on this gateway | Run Session → Get Status until status is qr_ready, then request the code; after a code is accepted, wait for ready. For a number held by another session, delete that session, or log it out while it runs, first. |
409 while the session reads ready | whatsapp-web.js: WhatsApp Web is reloading its page, and the message says to retry every few seconds | Retry at that interval, which can take a few minutes. A 409 that says the message may or may not have been sent (server v0.31.0+) is not this: check the chat before sending again. See Output and error handling. |
502 or 503 on System → Search | A plugin search provider is active and misbehaved | 503 means it did not answer, so wire n8n's retry-on-fail; 502 means it answered with an unusable shape and retrying will not help. The built-in provider returns neither. |
Compatibility
The nodes need an n8n-workflow that exports NodeConnectionTypes (1.83.0 and later, which ships
with n8n 1.85.0) and fail to load with an older copy.
This package targets a self-hosted OpenWA server ≥ 0.16.0, verified against v0.31.0. Two things set that floor independently.
The routes the action node calls set it at v0.16.0, where Call → Create Link arrived. Most of
the rest of the surface landed in v0.14.0 (message pin, star and vote; chat archive and clear;
presence subscribe and read; media conversion; voice statuses; group pictures and join preview;
channel create, delete and mute; label writes; automation rules). Session config followed in
v0.14.5, membership requests, the blocklist read and Presence → Set Own Presence in v0.15.0, and chat
mute and pin, channel Demote Admin and Transfer Ownership in v0.16.0 alongside the call link. Seven operations sit above the floor: Session → Get Proxy and
Session → Update Proxy need ≥ 0.23.4, where the per-session proxy became readable and
patchable rather than fixed at creation, Message → Click Button needs ≥ 0.23.6,
Webhook → Redrive Delivery Failures needs ≥ 0.25.0, Group → Set Member Label needs ≥ 0.27.0, Contact → Get LID needs ≥ 0.27.1, and Message → Get Receipts needs ≥ 0.28.0. Against an older server those specific
operations answer 404 and everything else keeps working.
Some optional fields also need a newer server, and a workflow that leaves them unset runs against
any server at the floor. Setting one against an older server fails differently by kind. A field in
the request body is refused with 400: Quoted Message ID on the nine sends that take it
(≥ 0.17.0), Mentions on Reply, Edit, Send Template and the items of Send Bulk (≥ 0.23.0),
Message IDs on Chat → Mark Read (≥ 0.23.0), Link Preview on Send Template (≥ 0.23.0),
Allowed Chats on API Key Create and Update (≥ 0.23.6), and Thumbnail Base64 and Thumbnail URL on Send Text Custom Link Preview (≥ 0.27.0), and Link Preview in the Session → Update Config fields (≥ 0.30.3). A linkPreview key in the Session Config JSON of Create is stored and ignored by an older server. A query parameter or header is ignored, so
the request reads a broader selection or gives no retry protection: After Row ID and Inline
Media on Message List (≥ 0.23.4), Name on Session List All (≥ 0.23.5), the six newer
Message List filters and Idempotency Key on the twelve sends (≥ 0.25.0), and Match on System Search (≥ 0.27.0). The kind and
chatId filter fields are refused when the webhook is registered; see the Trigger Filters field.
The event catalog is what actually sets 0.15.0. group.join_request does not exist in core
before v0.15.0, and session.restriction, presence.update, call.accepted, call.rejected and
call.missed do not exist before v0.14.0 — a v0.14.x server knows 22 of the 23 events the package offered before 1.2.0 — and the
server validates a webhook registration against its own event list, so a Trigger subscribing to any
of the six is refused at registration rather than degrading quietly. That is a harder failure than a
404 on one operation. Package 0.9.1 and earlier could not select group.join_request at all, so
their effective floor was 0.14.0. event.response, which package 1.2.0 added, does not exist in
core before v0.25.0 (24 events), and message.receipt and poll.vote, which package 1.3.0 added, do not exist in core before v0.26.0 (26 events); all three are refused the same way on an older server.
Since the routes now set the higher of the two, 0.16.0 is the supported floor for 1.8.1, apart from the operations, fields and events named above that need a newer server.
Next steps
- n8n integration guide — install the package and build your first workflow.
- Webhooks — the event payloads and signing scheme behind the Trigger node.
- API Reference — the HTTP endpoints each operation calls.
- Sending messages — payload details for the message operations.