Skip to main content
Version: v0.31.0

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.

List results emit one item per row on node version 2

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​

Noden8n typeDirectionPurpose
OpenWAopenWaActionSend messages and manage sessions, chats, contacts, groups, labels, templates, status, channels, keys, and webhooks
OpenWA TriggeropenWaTriggerTriggerStart 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.

FieldRequiredDescription
Server URLYesBase 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 KeyYesSent 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.

ResourceOperationMethod + path
SessionCreatePOST /api/sessions
SessionStartPOST /api/sessions/{sessionId}/start
SessionStopPOST /api/sessions/{sessionId}/stop
SessionForce KillPOST /api/sessions/{sessionId}/force-kill
SessionDeleteDELETE /api/sessions/{sessionId}
SessionGet QRGET /api/sessions/{sessionId}/qr
SessionRequest Pairing CodePOST /api/sessions/{sessionId}/pairing-code
SessionGet StatusGET /api/sessions/{sessionId}
SessionList AllGET /api/sessions
SessionGet Stats OverviewGET /api/sessions/stats/overview
SessionLog OutPOST /api/sessions/{sessionId}/logout
SessionGet ConfigGET /api/sessions/{sessionId}/config
SessionUpdate ConfigPATCH /api/sessions/{sessionId}/config
SessionGet ProxyGET /api/sessions/{sessionId}/proxy
SessionUpdate ProxyPATCH /api/sessions/{sessionId}/proxy
MessageSend TextPOST /api/sessions/{sessionId}/messages/send-text
MessageSend ImagePOST /api/sessions/{sessionId}/messages/send-image
MessageSend VideoPOST /api/sessions/{sessionId}/messages/send-video
MessageSend AudioPOST /api/sessions/{sessionId}/messages/send-audio
MessageSend DocumentPOST /api/sessions/{sessionId}/messages/send-document
MessageSend StickerPOST /api/sessions/{sessionId}/messages/send-sticker
MessageSend LocationPOST /api/sessions/{sessionId}/messages/send-location
MessageSend ContactPOST /api/sessions/{sessionId}/messages/send-contact
MessageSend PollPOST /api/sessions/{sessionId}/messages/send-poll
MessageSend TemplatePOST /api/sessions/{sessionId}/messages/send-template
MessageSend BulkPOST /api/sessions/{sessionId}/messages/send-bulk
MessageGet Batch StatusGET /api/sessions/{sessionId}/messages/batch/{batchId}
MessageCancel BatchPOST /api/sessions/{sessionId}/messages/batch/{batchId}/cancel
MessageReplyPOST /api/sessions/{sessionId}/messages/reply
MessageReactPOST /api/sessions/{sessionId}/messages/react
MessageEditPOST /api/sessions/{sessionId}/messages/edit
MessageDeletePOST /api/sessions/{sessionId}/messages/delete
MessageForwardPOST /api/sessions/{sessionId}/messages/forward
MessageListGET /api/sessions/{sessionId}/messages
MessageGet HistoryGET /api/sessions/{sessionId}/messages/{chatId}/history
MessageGet ReactionsGET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/reactions
MessageGet ReceiptsGET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/receipts
MessageGet MediaGET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/media
MessagePinPOST /api/sessions/{sessionId}/messages/pin
MessageUnpinPOST /api/sessions/{sessionId}/messages/unpin
MessageStarPOST /api/sessions/{sessionId}/messages/star
MessageVote PollPOST /api/sessions/{sessionId}/messages/vote-poll
MessageClick ButtonPOST /api/sessions/{sessionId}/messages/click-button
MessageSend ProductPOST /api/sessions/{sessionId}/messages/send-product
ContactCheck ExistsGET /api/sessions/{sessionId}/contacts/check/{phoneNumber}
ContactGet InfoGET /api/sessions/{sessionId}/contacts/{contactId}
ContactGet LIDGET /api/sessions/{sessionId}/contacts/{phoneNumber}/lid
ContactGet PhoneGET /api/sessions/{sessionId}/contacts/{contactId}/phone
ContactGet Profile PictureGET /api/sessions/{sessionId}/contacts/{contactId}/profile-picture
ContactGet Profile PicturesGET /api/sessions/{sessionId}/contacts/profile-pictures?ids=
ContactListGET /api/sessions/{sessionId}/contacts
ContactList BlockedGET /api/sessions/{sessionId}/contacts/blocked
ContactSavePUT /api/sessions/{sessionId}/contacts/{contactId}
ContactDeleteDELETE /api/sessions/{sessionId}/contacts/{contactId}
ContactBlockPOST /api/sessions/{sessionId}/contacts/{contactId}/block
ContactUnblockDELETE /api/sessions/{sessionId}/contacts/{contactId}/block
ChatListGET /api/sessions/{sessionId}/chats
ChatMark ReadPOST /api/sessions/{sessionId}/chats/read
ChatMark UnreadPOST /api/sessions/{sessionId}/chats/unread
ChatDeletePOST /api/sessions/{sessionId}/chats/delete
ChatClear MessagesDELETE /api/sessions/{sessionId}/chats/{chatId}/messages
ChatArchivePOST /api/sessions/{sessionId}/chats/archive
ChatPinPOST /api/sessions/{sessionId}/chats/pin
ChatMutePOST /api/sessions/{sessionId}/chats/mute
ChatSet StatePOST /api/sessions/{sessionId}/chats/typing
GroupListGET /api/sessions/{sessionId}/groups
GroupCreatePOST /api/sessions/{sessionId}/groups
GroupJoinPOST /api/sessions/{sessionId}/groups/join
GroupGet Join InfoGET /api/sessions/{sessionId}/groups/join-info?code=
GroupGetGET /api/sessions/{sessionId}/groups/{groupId}
GroupLeavePOST /api/sessions/{sessionId}/groups/{groupId}/leave
GroupAdd ParticipantsPOST /api/sessions/{sessionId}/groups/{groupId}/participants
GroupRemove ParticipantsDELETE /api/sessions/{sessionId}/groups/{groupId}/participants
GroupPromote ParticipantsPOST /api/sessions/{sessionId}/groups/{groupId}/participants/promote
GroupDemote ParticipantsPOST /api/sessions/{sessionId}/groups/{groupId}/participants/demote
GroupUpdate SubjectPUT /api/sessions/{sessionId}/groups/{groupId}/subject
GroupUpdate DescriptionPUT /api/sessions/{sessionId}/groups/{groupId}/description
GroupSet Member LabelPUT /api/sessions/{sessionId}/groups/{groupId}/member-label
GroupGet SettingsGET /api/sessions/{sessionId}/groups/{groupId}/settings
GroupUpdate SettingsPUT /api/sessions/{sessionId}/groups/{groupId}/settings
GroupGet Invite CodeGET /api/sessions/{sessionId}/groups/{groupId}/invite-code
GroupRevoke Invite CodePOST /api/sessions/{sessionId}/groups/{groupId}/invite-code/revoke
GroupGet Membership RequestsGET /api/sessions/{sessionId}/groups/{groupId}/membership-requests
GroupApprove Membership RequestsPOST /api/sessions/{sessionId}/groups/{groupId}/membership-requests/approve
GroupReject Membership RequestsPOST /api/sessions/{sessionId}/groups/{groupId}/membership-requests/reject
GroupGet PictureGET /api/sessions/{sessionId}/groups/{groupId}/picture
GroupSet PicturePUT /api/sessions/{sessionId}/groups/{groupId}/picture
GroupDelete PictureDELETE /api/sessions/{sessionId}/groups/{groupId}/picture
ProfileSet NamePUT /api/sessions/{sessionId}/profile/name
ProfileSet StatusPUT /api/sessions/{sessionId}/profile/status
ProfileSet PicturePUT /api/sessions/{sessionId}/profile/picture
ProfileDelete PictureDELETE /api/sessions/{sessionId}/profile/picture
LabelListGET /api/sessions/{sessionId}/labels
LabelGetGET /api/sessions/{sessionId}/labels/{labelId}
LabelCreate or UpdatePUT /api/sessions/{sessionId}/labels/{labelId}
LabelDeleteDELETE /api/sessions/{sessionId}/labels/{labelId}
LabelGet ChatsGET /api/sessions/{sessionId}/labels/{labelId}/chats
LabelGet for ChatGET /api/sessions/{sessionId}/labels/chat/{chatId}
LabelAdd to ChatPOST /api/sessions/{sessionId}/labels/chat/{chatId}
LabelRemove From ChatDELETE /api/sessions/{sessionId}/labels/chat/{chatId}/{labelId}
StatusListGET /api/sessions/{sessionId}/status
StatusGet by ContactGET /api/sessions/{sessionId}/status/{contactId}
StatusGet MediaGET /api/sessions/{sessionId}/status/{statusId}/media
StatusDeleteDELETE /api/sessions/{sessionId}/status/{statusId}
StatusSend TextPOST /api/sessions/{sessionId}/status/send-text
StatusSend ImagePOST /api/sessions/{sessionId}/status/send-image
StatusSend VideoPOST /api/sessions/{sessionId}/status/send-video
StatusSend VoicePOST /api/sessions/{sessionId}/status/send-voice
TemplateListGET /api/sessions/{sessionId}/templates
TemplateCreatePOST /api/sessions/{sessionId}/templates
TemplateGetGET /api/sessions/{sessionId}/templates/{templateId}
TemplateUpdatePUT /api/sessions/{sessionId}/templates/{templateId}
TemplateDeleteDELETE /api/sessions/{sessionId}/templates/{templateId}
ChannelListGET /api/sessions/{sessionId}/channels
ChannelGetGET /api/sessions/{sessionId}/channels/{channelId}
ChannelGet MessagesGET /api/sessions/{sessionId}/channels/{channelId}/messages
ChannelCreatePOST /api/sessions/{sessionId}/channels
ChannelSubscribePOST /api/sessions/{sessionId}/channels/subscribe
ChannelUnsubscribeDELETE /api/sessions/{sessionId}/channels/{channelId}
ChannelDeletePOST /api/sessions/{sessionId}/channels/{channelId}/delete
ChannelMutePOST /api/sessions/{sessionId}/channels/{channelId}/mute
ChannelDemote AdminPOST /api/sessions/{sessionId}/channels/{channelId}/admins/demote
ChannelTransfer OwnershipPOST /api/sessions/{sessionId}/channels/{channelId}/owner/transfer
CallRejectPOST /api/sessions/{sessionId}/calls/{callId}/reject
CallCreate LinkPOST /api/sessions/{sessionId}/calls/link
ObservabilityCheckGET /api/health
ObservabilityCheck LivenessGET /api/health/live
ObservabilityCheck ReadinessGET /api/health/ready
SystemGet SettingsGET /api/settings
SystemGet Stats OverviewGET /api/stats/overview
SystemGet Message StatsGET /api/stats/messages
SystemGet Session StatsGET /api/stats/sessions/{sessionId}
SystemGet Audit LogGET /api/audit
SystemSearchGET /api/search
API KeyListGET /api/auth/api-keys
API KeyCreatePOST /api/auth/api-keys
API KeyGetGET /api/auth/api-keys/{keyId}
API KeyUpdatePUT /api/auth/api-keys/{keyId}
API KeyRevokePOST /api/auth/api-keys/{keyId}/revoke
API KeyDeleteDELETE /api/auth/api-keys/{keyId}
API KeyValidatePOST /api/auth/validate
WebhookCreatePOST /api/sessions/{sessionId}/webhooks
WebhookGetGET /api/sessions/{sessionId}/webhooks/{webhookId}
WebhookListGET /api/sessions/{sessionId}/webhooks
WebhookUpdatePUT /api/sessions/{sessionId}/webhooks/{webhookId}
WebhookDeleteDELETE /api/sessions/{sessionId}/webhooks/{webhookId}
WebhookTestPOST /api/sessions/{sessionId}/webhooks/{webhookId}/test
WebhookList AllGET /api/webhooks
WebhookGet Delivery FailuresGET /api/webhooks/delivery-failures
WebhookRedrive Delivery FailuresPOST /api/webhooks/delivery-failures/redrive
Automation RuleListGET /api/sessions/{sessionId}/automation-rules
Automation RuleCreatePOST /api/sessions/{sessionId}/automation-rules
Automation RuleGetGET /api/sessions/{sessionId}/automation-rules/{ruleId}
Automation RuleUpdatePUT /api/sessions/{sessionId}/automation-rules/{ruleId}
Automation RuleDeleteDELETE /api/sessions/{sessionId}/automation-rules/{ruleId}
CatalogGetGET /api/sessions/{sessionId}/catalog
CatalogList ProductsGET /api/sessions/{sessionId}/catalog/products
CatalogGet ProductGET /api/sessions/{sessionId}/catalog/products/{productId}
MediaCheck AvailabilityGET /api/sessions/{sessionId}/media/convert
MediaConvert to Voice NotePOST /api/sessions/{sessionId}/media/convert/voice
MediaConvert to VideoPOST /api/sessions/{sessionId}/media/convert/video
PresenceSubscribePOST /api/sessions/{sessionId}/presence/subscribe
PresenceGetGET /api/sessions/{sessionId}/presence/{chatId}
PresenceSet Own PresencePUT /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.

Not offered by the node

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.

Using the OpenWA node as an AI tool

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 allowedSessions and allowedChats. 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:

SourceExtra fieldsRequest fields sent
Binary DataBinary Property (default data)base64 (the buffer encoded) and mimetype, read from the binary metadata
URL(the media URL field)url
Base64Base64 Data, MIME Typebase64 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.

Base64 needs a MIME type

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.

OperationFieldsNotes
CreateSession Name, Session Config (JSON), Proxy URLSession 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.
StartSession Name or IDStarts the session and connects to WhatsApp.
StopSession Name or IDStops the session and disconnects.
Force KillSession Name or IDForce-kills a stuck session's engine.
DeleteSession Name or IDDeletes the session.
Get QRSession Name or IDReturns the QR code for scanning authentication.
Request Pairing CodeSession Name or ID, Phone NumberPhone 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 StatusSession Name or IDReturns the status of one session.
List AllOptions: Limit (1 to 1000), Offset, NameReturns 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 OutSession Name or IDAsks 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 ConfigSession Name or IDThe session's effective configuration: the four recognised keys, as the engine will apply them (linkPreview, server v0.30.3+, reads null while unset).
Update ConfigSession Name or ID, Config FieldsA 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 ProxySession Name or IDServer v0.23.4 and newer. Reports the scheme, the host and port, and whether credentials are embedded. It never returns the credentials themselves.
Update ProxySession Name or ID, Proxy URL, Clear ProxyServer 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:

FieldTypeNotes
Auto Reject CallsbooleanDefault 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 PreviewoptionsDefault 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 AttemptsnumberHow 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)numberBase 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.

FieldTypeRequiredDescription
Session Name or IDoptionsYesThe session to act through.
Chat Name or IDoptionsYes (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 }.

FieldTypeRequiredMaps to
MessagestringYestext. 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 PreviewoptionsNolinkPreview. 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 PreviewcollectionNocustomLinkPreview. 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.

FieldTypeRequiredNotes
Image Sourceoptions: Binary Data, URL, Base64YesDefault URL.
Binary PropertystringYes (binary)Default data.
Image URLstringYes (url)Public URL of the image.
Base64 DatastringYes (base64)Base64-encoded image bytes.
MIME TypestringYes (base64)For example image/png. Default image/jpeg.
CaptionstringNoSent 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.

FieldTypeRequiredNotes
Audio Sourceoptions: Binary Data, URL, Base64YesDefault URL.
Binary PropertystringYes (binary)Default data.
Audio URLstringYes (url)Public URL of the audio.
Base64 DatastringYes (base64)Base64-encoded audio bytes.
MIME TypestringYes (base64)Default audio/ogg; codecs=opus. For a plain audio file set its real type (for example audio/mpeg).
Send as Voice NotebooleanNoDefault 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.

FieldTypeRequiredNotes
Document Sourceoptions: Binary Data, URL, Base64YesDefault URL.
Binary PropertystringYes (binary)Default data.
Document URLstringYes (url)Public URL of the document.
Base64 DatastringYes (base64)Base64-encoded document bytes.
MIME TypestringYes (base64)For example application/pdf. Default application/pdf.
FilenamestringNoSent 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.
CaptionstringNoSent as caption when set.

Send Sticker — same source model. WhatsApp expects a WebP sticker, ideally 512×512.

FieldTypeRequiredNotes
Sticker Sourceoptions: Binary Data, URL, Base64YesDefault URL.
Binary PropertystringYes (binary)Default data.
Sticker URLstringYes (url)Public URL of the sticker (WhatsApp expects a WebP image).
Base64 DatastringYes (base64)Base64-encoded sticker bytes.
MIME TypestringYes (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.
Mentions

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.

Idempotent sends

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.

Quoting from a send

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 }.

FieldTypeRequiredMaps to
LatitudenumberYeslatitude
LongitudenumberYeslongitude
Location NamestringNoSent as description (OpenWA's field for the location label) when set.
AddressstringNoSent as address, the street line WhatsApp shows under the label.

Send Contact — request body { chatId, contactName, contactNumber }.

FieldTypeRequiredMaps to
Contact NamestringYescontactName — display name for the shared contact card.
Contact NumberstringYescontactNumber — 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.

FieldTypeRequiredNotes
QuestionstringYesSent as name. Maximum 255 characters.
Optionsstring listYesThe 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 AnswersbooleanNoDefault 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.

FieldTypeRequiredNotes
Template Name or IDoptionsYes (or Template Name)Id of the template to render. When both this and Template Name are set, the id wins.
Template NamestringYes (or Template Name or ID)Used only when the id is empty. Providing neither fails the item.
Variables (JSON)jsonNoValues substituted into the template's {{placeholder}} tokens, as a JSON object such as {"name":"Alice"}. A non-object value fails the item.
Link PreviewoptionsNoThe 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.

FieldTypeRequiredNotes
Messages (JSON)jsonYesArray 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 IDstringNoCustom 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.
OptionscollectionNoLeft empty, the server applies its own defaults (delay 3000 ms, randomize on, stop-on-error off).

The Options collection offers:

OptionTypeDefaultNotes
Delay Between Messages (Ms)number3000Milliseconds to wait between sends, 1000–60000.
Randomize DelaybooleanonAdds a random 0–2000 ms on top of the delay.
Stop on ErrorbooleanoffAborts 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:

FieldTypeRequiredNotes
Batch IDstringYesThe batch id returned by Send Bulk.

Reply — request body { chatId, quotedMessageId, text }.

FieldTypeRequiredNotes
Quoted Message IDstringYesFull serialized id of the message to quote (for example true_628123456789@c.us_3EB0…), as returned by send operations or delivered by the Trigger.
MessagestringYesThe 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 }.

FieldTypeRequiredNotes
Message IDstringYesFull serialized id of the target message.
EmojistringNoThe 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 }.

FieldTypeRequiredNotes
Message IDstringYesFull serialized id of the message to edit.
MessagestringYesThe 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 }.

FieldTypeRequiredNotes
Message IDstringYesFull serialized id of the message to delete.
Delete for EveryonebooleanNoDefault 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.

FieldTypeRequiredNotes
From Chat Name or IDoptionsYesThe chat the message currently lives in.
To Chat Name or IDoptionsYesThe chat to forward it to.
Message IDstringYesFull 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.

OptionTypeDefaultNotes
After Row IDstringunsetKeyset 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 IDoptions—Only return messages from this chat.
DirectionoptionsIncomingIncoming or Outgoing. Left out, both directions are returned. Server v0.25.0 and newer.
Fromstring—Only return messages from this sender.
Inline MediabooleantrueTurn 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.
Limitnumber50Max results, 1 to 100.
Message IDstringunsetExact 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.
Offsetnumber0Records to skip before collecting the result set.
Order ByoptionsCreated AtNewest 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.
SincedateTimeunsetInclusive lower bound on message time. Server v0.25.0 and newer.
TypestringunsetExact stored message type, for example text, image, voice or poll. Server v0.25.0 and newer.
UntildateTimeunsetExclusive 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:

OptionTypeDefaultNotes
DeepbooleanoffAllows 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 MediabooleanoffInclude media payloads in the returned messages. Ignored while Deep is on.
Limitnumber50Max 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the message lives in.
Message IDstringYesFull 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the message was sent to.
Message IDstringYesFull serialized id of the outbound message.

Get Media downloads the media attached to one message.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the message lives in.
Message IDstringYesFull serialized id of the message.
Put Output in FieldstringYesName 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the message lives in.
Message IDstringYesFull serialized id of the message.
Pin DurationoptionsPin only24 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 }.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the message lives in.
Message IDstringYesFull serialized id of the message.
StarbooleanYesOn 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the poll lives in.
Message IDstringYesThe poll message's id. Sent as pollMessageId, not messageId.
Selected Optionsstring listYesThe 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesThe chat the prompt arrived in.
Message IDstringYesThe prompt's own id, data.id on its message.received event.
Button IDstringYesOne of the prompt's buttons[].id, at most 256 characters. An id that is not among its choices answers 400.
Button TextstringNoThe 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.

FieldTypeRequiredNotes
Chat Name or IDoptionsYesRecipient.
Product IDstringYesThe 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.
MessagestringNoOptional text alongside the card. Sent as body.
Some sends to a channel or a broadcast list are refused on whatsapp-web.js

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).

OperationFieldTypeRequiredNotes
Check ExistsPhone NumberstringYesDigits 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 InfoContact Name or IDoptionsYesFor example 628123456789@c.us. Empty values fail the item.
Get LIDPhone NumberstringYesLooks 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 PhoneContact Name or IDoptionsYesResolves 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 PictureContact Name or IDoptionsYesReturns the contact's profile-photo URL.
Get Profile PicturesContact IDsstring listYesPictures 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.
ListOptions: Limit (1 to 1000), OffsetcollectionNoReturns the session's contacts, paginated. On Baileys (server v0.23.6+) that is the saved address book only; see below.
List Blocked(none)n/an/aThe ids this account has blocked. Bare id strings, not contact objects; see the wrapping note under Output and error handling.
SaveContact Name or ID, First Name, Last NamestringFirst Name yesWrites the addressbook entry. Both names are capped at 100 characters.
DeleteContact Name or IDoptionsYesRemoves the entry from the addressbook. The chat and its history are untouched.
BlockContact Name or IDoptionsYesBlocks 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.
UnblockContact Name or IDoptionsYesUnblocks 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.

OperationFieldsNotes
ListOptions: Limit (1 to 1000), OffsetThe 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 ReadChat Name or ID, Message IDsBody { 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 UnreadChat Name or IDBody { chatId }.
DeleteChat Name or IDBody { chatId }. A POST, not a DELETE — the server takes the chat id in the body here.
Clear MessagesChat Name or IDDELETE /api/sessions/{sessionId}/chats/{chatId}/messages. Empties the chat but keeps it in the list.
ArchiveChat Name or ID, ArchiveBody { chatId, archive }. Set Archive off to unarchive.
PinChat Name or ID, PinBody { 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).
MuteChat Name or ID, Mute UntilBody { 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 StateChat Name or ID, StateBody { 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.

OperationFieldsNotes
ListOptions: Limit (1–1000), OffsetLeft empty, the server applies its own defaults (limit 1000, offset 0).
CreateGroup Name, ParticipantsName 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.
JoinInvite CodeThe 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 InfoInvite CodePreviews 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.
GetGroup Name or IDGroup info including participants.
LeaveGroup Name or IDLeaves the group.
Add / Remove / Promote / Demote ParticipantsGroup Name or ID, ParticipantsBody { 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 SubjectGroup Name or ID, SubjectRequired, maximum 100 characters.
Update DescriptionGroup Name or ID, DescriptionMaximum 1024 characters. An empty value is sent as-is and clears the description.
Set Member LabelGroup Name or ID, Member LabelBody { 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 SettingsGroup Name or IDReads announce, locked, the member-add mode, and the disappearing-message timer.
Update SettingsGroup Name or ID, SettingsPartial — settings you leave out stay untouched, and at least one is required.
Get Invite CodeGroup Name or IDThe 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 CodeGroup Name or IDRevokes 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 RequestsGroup Name or IDThe 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 RequestsGroup Name or ID, RequestersBody { 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 PictureGroup Name or IDThe group picture's URL.
Set PictureGroup 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 PictureGroup Name or IDRemoves 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:

OptionTypeDefaultNotes
AnnouncebooleanoffOnly admins can send messages to the group.
LockedbooleanoffOnly admins can edit the group info.
Member Add ModeoptionsAll MembersWho may add participants: All Members (all) or Admins Only (admins).
Disappearing Messages (Seconds)number604800Disappearing-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.

OperationFieldsNotes
Set NameNameRequired, maximum 25 characters.
Set StatusStatusMaximum 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 PicturePicture Source, and the matching Binary Property / Picture URL / Base64 Data + MIME TypeThe 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.

OperationFieldsNotes
List(none)whatsapp-web.js only; Baileys answers 501. Every label on the account.
GetLabel Name or IDwhatsapp-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 UpdateLabel ID, Fields: Name, ColorBaileys 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.
DeleteLabel IDBaileys only; whatsapp-web.js answers 501. The label disappears from every chat it was on.
Get ChatsLabel Name or IDwhatsapp-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 ChatChat Name or IDwhatsapp-web.js only; Baileys answers 501. The labels attached to a chat.
Add to ChatChat Name or ID, Label Name or IDBody { 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 ChatChat Name or ID, Label Name or IDBoth 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:

FieldTypeNotes
NamestringLabel 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.
ColornumberAn 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.

OperationFieldsNotes
List(none)The status feed.
Get by ContactContact Name or IDOne contact's status updates.
Get MediaStatus ID, Put Output in FieldStreams 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.
DeleteStatus IDDeletes one of your own status updates.
Send TextText, Background Color, Font, RecipientsBody { text } plus backgroundColor, font, and recipients when set. Text is required, maximum 4096 characters.
Send ImageImage Source (+ source fields), Caption, RecipientsThe media object nests under image rather than sitting flat on the body.
Send VideoVideo Source (+ source fields: Binary Property, Video URL, Base64 Data, MIME Type), Caption, RecipientsThe media object nests under video.
Send VoiceAudio Source (+ source fields), Background Color, RecipientsPosts 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.
FieldTypeNotes
Background ColorcolorSent as backgroundColor. Leave empty for the server default.
FontoptionsFont 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.
CaptionstringMaximum 1024 characters.
Recipientsstring listWho 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.

OperationFieldsNotes
List(none)Every template in the session.
CreateName, Body, Header, FooterName (max 100) and Body (max 4096) are required; Header and Footer are optional, max 1024 each.
GetTemplate Name or IDOne template.
UpdateTemplate Name or ID, Update FieldsPartial: the collection offers Body, Footer, Header, and Name, with the same limits. At least one is required.
DeleteTemplate Name or IDDeletes 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.

OperationFieldsNotes
List(none)whatsapp-web.js only; Baileys answers 501. Followed channels.
GetChannel Name or IDOne channel. Works on both engines.
Get MessagesChannel Name or ID, Options: Limit (1 to 100, default 50)whatsapp-web.js only; Baileys answers 501. A channel's messages.
CreateChannel Name, DescriptionName 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.
SubscribeInvite CodeBaileys 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.
UnsubscribeChannel Name or IDA DELETE on the channel — it unfollows rather than deletes.
DeleteChannel Name or IDIrreversible, 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.
MuteChannel Name or ID, MuteSilences 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 AdminChannel Name or ID, User IDDemotes 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 OwnershipChannel Name or ID, New Owner IDIrreversible: 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​

OperationFieldsNotes
RejectSession Name or ID, Call IDThe 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 LinkSession Name or ID, Call Type, Start TimeGenerates 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.

OperationNotes
CheckGET /api/health — the server's health JSON as-is.
Check LivenessThe liveness probe.
Check ReadinessThe 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.

OperationFieldsNotes
Get Settings(none)The server settings document. ADMIN key, unscoped.
Get Stats Overview(none)Overview statistics across the instance. ADMIN key, unscoped.
Get Message StatsPeriodMessage 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 StatsSession Name or IDStatistics for one session. Any valid key except one restricted to selected chats (server v0.23.6+), which answers 403.
Get Audit LogFiltersThe audit log. ADMIN key. Unlike the other ADMIN reads here it accepts a session-scoped key, which simply narrows the result.
SearchQuery, FiltersCross-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:

FilterTypeNotes
Chat IDstringOnly 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 TodateTimeBounds 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.
DirectionoptionsIncoming or Outgoing.
FromstringOnly 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 / OffsetnumberPagination, 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.
MatchoptionsWhole 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 IDoptionsOnly search within this session.
TypestringOnly return messages of this type, for example text or image.

The Get Audit Log filters:

FilterTypeNotes
ActionstringOnly 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 IDoptionsOnly entries recorded for this key. Sent to the API as apiKeyId.
Limit / OffsetnumberPagination, defaults 50 and 0; Limit is capped at 200 in the UI.
Session Name or IDoptionsOnly entries for this session.
SeverityoptionsOne 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.

OperationFieldsNotes
List(none)Every key.
CreateName, FieldsName is required; the Fields collection carries the optional restrictions below.
GetAPI Key Name or IDOne key. The id, not the key itself.
UpdateAPI Key Name or ID, FieldsPartial — only the fields you set are changed, and an empty list never clears an existing whitelist. At least one field is required.
RevokeAPI Key Name or IDDeactivates the key.
DeleteAPI Key Name or IDRemoves 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:

OptionTypeDefaultNotes
Namestring—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.
RoleoptionsViewer once added; an Operator key if the field is not addedAdmin, Operator, or Viewer. Add the field to choose: the node sends no role otherwise, and the server then creates an OPERATOR key.
Expires AtdateTime—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 Chatsstring listunsetRestrict the key to these chats. Server v0.23.6 and newer; see the note below the table.
Allowed IPsstring list—Restrict the key to these addresses. Single IPs and CIDR ranges are both accepted.
Allowed Sessionsstring 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.

FieldTypeRequiredNotes
Webhook URLstringYesDestination that receives event deliveries. Surrounding whitespace is dropped, and a blank value fails the item.
EventsmultiOptionsYesOne 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 Secretstring (password)NoIf 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 FieldscollectionNoOptional settings, listed below.

The Additional Fields collection offers:

OptionTypeNotes
FiltersjsonDelivery filters as a JSON object in the format of the Trigger's Filters field. Without them, every subscribed event is delivered.
HeadersjsonCustom delivery headers as a flat JSON object of string values, for example {"X-Team":"ops"}.
Retry CountnumberDefault 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.

FieldTypeRequiredNotes
Webhook Name or IDoptionsYesThe webhook to update. The dropdown lists a session's webhooks by delivery URL.
Update FieldscollectionNoThe changes to apply — see the options below.

The Update Fields collection offers:

OptionTypeNotes
URLstringNew delivery URL.
EventsmultiOptionsReplaces 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).
ActivebooleanWhether the webhook is enabled.
Retry CountnumberTotal 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.
Secretstring (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 SecretbooleanStops 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)jsonCustom 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)jsonAdvanced 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.

OperationFieldsNotes
GetSession Name or ID, Webhook Name or IDOne webhook.
ListSession Name or IDThe session's webhooks.
DeleteSession Name or ID, Webhook Name or IDRemoves it.
TestSession Name or ID, Webhook Name or IDSends a test delivery.

List All, Get Delivery Failures and Redrive Delivery Failures span every session, so none shows a Session ID field.

OperationOptionsNotes
List AllLimit (1 to 1000), OffsetWebhooks 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 FailuresLimit (1 to 1000), Offset, Session Name or IDFailed deliveries; this route is the one that does accept a session filter. ADMIN key.
Redrive Delivery FailuresFailure IDs, Limit, Session ID, Webhook IDReplays 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:

OptionTypeNotes
Failure IDsstring listFailure row ids from Get Delivery Failures, at most 500 ids of at most 128 characters each. An explicit empty list replays nothing.
LimitnumberRows replayed by this call, 1 to 500. Left out, the server replays up to 100; the field shows 50 once it is added.
Session IDstringOnly failures of this session, at most 128 characters.
Webhook IDstringOnly 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.

OperationFieldsNotes
List(none beyond the session)The session's rules, one item per rule.
GetRule IDOne rule.
CreateName, Reply Text, Conditions, Additional FieldsName is capped at 100 characters and Reply Text at 4096.
UpdateRule ID, Update FieldsOnly the fields you add are sent; anything left out keeps its stored value.
DeleteRule IDRemoves 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.

These rules run on the gateway, not in n8n

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.

OperationFieldsNotes
List ProductsOptions (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 ProductProduct IDOne product.
Get(none beyond the session)The catalog's own metadata.
Baileys only, and a 503 here can be permanent

whatsapp-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.

OperationFieldsNotes
Check Availability(none beyond the session)Whether conversion is configured and ffmpeg is runnable.
Convert to Voice NoteMedia Source, and the field that source needsProduces Ogg/Opus.
Convert to VideoMedia Source, and the field that source needsProduces 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 feeds a send, and is optional on the server

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.

OperationFieldsNotes
SubscribeChat Name or IDSubscribes 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.
GetChat Name or IDThe last reported presence for that chat. Answers an empty object when nothing has been reported yet.
Set Own PresenceAvailableWhether the account announces itself as online.
Presence is connection-scoped

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.

List output depends on the node version

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().json as 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​

FieldTypeRequiredNotes
Session Name or IDoptionsYesSession to receive events from, chosen from the same dropdown the action node uses. Sanitized like the action node (no empty, .., /, or \).
EventsmultiOptionsYesEvents 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 Secretstring (password)NoShared 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.
FiltersjsonNoServer-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 DeliveriesbooleanNoDefault 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 with POST /api/sessions/{sessionId}/webhooks if it does not. A 404 there 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 package 1.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}. A 404 is treated as already deleted; any other error propagates so activation fails loudly rather than orphaning a registration that would keep delivering.
Re-registering after a configuration change

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:

EventFires when
message.receivedA new message is received.
message.sentA message is sent successfully.
message.ackA 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.receiptA 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.failedA message fails to send.
message.revokedA 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.editedA 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.reactionA 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.voteA 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.receivedA contact's Status (Story) is received.
session.statusAny session status change.
session.qrA new QR code is generated.
session.authenticatedThe session is authenticated.
session.disconnectedThe session loses connection.
session.reconnect_loopA session is stuck in a reconnect loop — once per 5 consecutive attempts.
session.restrictionWhatsApp places or lifts a restriction on the account (including Baileys kind: "passkey_required" since server v0.30.0).
presence.updateA 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.responseA 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.joinA 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.leaveA participant leaves a group the session belongs to.
group.updateA 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_requestSomeone asks to join a group the session administers. Fires only when the group has admin approval enabled.
call.receivedAn 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.acceptedAn incoming call is answered. Baileys only.
call.rejectedAn incoming call is declined, including by auto-reject. Baileys only.
call.missedAn incoming call goes unanswered. Baileys only.
The call outcomes fire on one engine 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.

FieldDescription
eventThe event name, for example message.received.
timestampISO 8601 time the event was emitted, for example 2024-01-15T10:30:00Z.
sessionIdSession the event belongs to.
idempotencyKeyStable key for the logical event.
deliveryIdIdentifies a single delivery attempt. Re-minted on a crash replay, so it is not a dedup key.
dataThe 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 use id, not messageId.
  • 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 on deliveryId: a replay carries a new one.
  • Message type is engine-neutral: voice notes are voice, shared contacts are contact, and plain chats are text.
  • Some payloads carry extra fields under data: type: "masked" marks a withheld business message, a message.revoked event carries revokedId (the id of the revoked message), and since server v0.29.1 a forwarded message on message.received or message.sent (either engine) carries isForwarded: true and, when positive, forwardingScore (both absent on non-forwarded messages and stripped on revoked placeholders).
  • 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 as type: "text" with button: { id, text? } and the visible label in body. Before v0.23.6 button, template and list replies, and list prompts, were typed unknown, so a type filter on text now lets them through. whatsapp-web.js carries neither field. Message → Click Button answers such a prompt: give it the prompt's data.id as Message ID and one of its buttons[].id as 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 as message.sent, and reactions, edits and deletions made in that window, by the account or by anyone else, as message.reaction, message.edited and message.revoked. Earlier releases dropped all of them. A workflow that should not act on that backlog, such as an auto-reply, can compare data.timestamp (epoch seconds) with the current time; a message.reaction payload 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 as X-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 401 rather 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 401 the same way. The package notes that before 1.2.1 the 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​

SymptomCauseFix
Credential test fails on saveAPI 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 charactersSession id has .., /, or \Pick the session from the dropdown, or supply its UUID from an expression.
Chat ID cannot be emptyMessage sent with no Chat IDProvide a chat id like 628123456789@c.us.
Phone number must be digits in international formatCheck Exists or Get LID got an @lid, group, channel, or non-digit input that survived strippingPass digits in international format (for example 628123456789) or a @c.us / @s.whatsapp.net user JID.
Base64 image or document rejected by OpenWAMissing MIME type on a base64 payloadSet 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 propertyA whatsapp-web.js session on a WhatsApp Web build rolled out from 2026-09-17, against a server older than v0.23.6Upgrade 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 webhookThe server does not know one of the selected events, or a filter fieldsession.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 workThe route postdates the serverSession → 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 runsThe session runs whatsapp-web.jscall.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 → RejectThe 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 quietThe webhook was registered against n8n's test URL, which stops after one deliveryActivate the workflow so the trigger registers its production URL.
Trigger subscribed to a group event never runsThe session isn't a member of any group, or no group activity has occurredConfirm 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 deliverySignature mismatch between server and node secretsUse the same Webhook Secret on both sides; reactivate the workflow after changing it.
403 on an operation that used to workThe credential's role is too low, or its session or chat scope is too narrowWrites 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 CodeThe 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 gatewayRun 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 readywhatsapp-web.js: WhatsApp Web is reloading its page, and the message says to retry every few secondsRetry 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 → SearchA plugin search provider is active and misbehaved503 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​