Build WhatsApp workflows with n8n

Connect OpenWA to n8n, an open-source workflow automation tool, using the official community nodes. By the end of this page you'll have the nodes installed, an OpenWA credential configured, and a working auto-reply workflow: an incoming WhatsApp message triggers a reply.

• npm package: @rmyndharis/n8n-nodes-openwa (current version 0.9.1)
• Repository: rmyndharis/OpenWA-n8n

The package ships two nodes:

Node	Type	What it does
OpenWA	Action	Calls OpenWA operations as a workflow step — send messages, manage sessions, chats, contacts, groups, labels, templates, status, channels, and webhooks
OpenWA Trigger	Trigger	Starts a workflow when a WhatsApp event arrives — messages, session, group, call, and presence events

Prerequisites

• A running OpenWA gateway that n8n can reach over the network. See Installation.
• A connected session that has finished pairing. See Your first session.
• An API key from the dashboard. See the Authentication guide.
• An n8n instance where you can install community nodes (self-hosted).
• An OpenWA server ≥ 0.14.0. The nodes are verified against v0.23.1.

The server floor is checked when the webhook is registered

Package 0.9.1 raised the required server from 0.10.9 to 0.14.0. Five of the events the Trigger offers — session.restriction, presence.update, call.accepted, call.rejected, and call.missed — do not exist in core before v0.14.0, and the gateway validates a webhook registration against its own event list. A Trigger subscribing to any of them against an older gateway is refused at registration with a 400, so the workflow fails to activate rather than activating and quietly never firing.

Install the nodes

Install the community package on a self-hosted n8n instance.

From the n8n UI

1. In n8n, open Settings → Community Nodes.
2. Click Install.
3. Enter @rmyndharis/n8n-nodes-openwa and accept the community-node risk prompt.
4. Restart n8n.

Manual install

cd ~/.n8n/nodes
npm install @rmyndharis/n8n-nodes-openwa

Restart n8n after installing. Both nodes then appear in the node picker when you search for "OpenWA".

n8n Cloud

n8n Cloud only allows community nodes verified by n8n, and this package is not currently one of them. Use a self-hosted instance to run it.

Configure the OpenWA API credential

Both nodes share one credential. Create it once and reuse it across every OpenWA node in your instance.

Field	Required	Default	Description
Server URL	Yes	http://localhost:2785	Your OpenWA server URL, without a trailing slash or /api. Use HTTPS in production (for example https://wa.yourserver.com).
API Key	Yes	—	The API key from your OpenWA dashboard. The node sends it as the X-API-Key header on every request.

When you click Test in the credential dialog, n8n makes an authenticated GET /api/sessions request to your server. The test passes only if the key is valid, so a wrong key or unreachable server fails immediately.

Use a scoped key

Create a dedicated API key for n8n rather than reusing an admin key, so you can revoke it without disrupting other clients. See the Authentication guide.

Most reads work with a plain VIEWER key. Writes — sends, group changes, profile changes, and webhook management — need an OPERATOR-role key (the default role). The whole API Key resource, plus System → Get Settings, System → Get Audit Log, and Webhook → Get Delivery Failures, needs an ADMIN key. A 403 almost always means the key's role is too low, not that the request was malformed.

You can confirm the same credential by hand with curl before building a workflow. This hits the same send endpoint the Send Text operation uses, so a success here confirms both the credential and a connected session:

curl -X POST http://localhost:2785/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/messages/send-text \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "628123456789@c.us",
    "text": "Hello from OpenWA!"
  }'

On success the gateway returns 201 Created with the message id and timestamp:

{
  "messageId": "true_628123456789@c.us_3EB0123456789",
  "timestamp": 1706868000
}

A 404 means the session id doesn't exist; a 400 means the session isn't connected or the body is invalid. Replace the UUID with your own session id — the id from the create response, not the name you gave it — and 628123456789@c.us with a real recipient chat id.

The OpenWA node (actions)

The action node maps a Resource and Operation to one OpenWA call. Package 0.9.0 extended it from four resources to the fifteen below, covering the usable OpenWA API surface. For field-level detail of every operation, see the n8n Node Reference.

Resource	Operations	What it covers
Session	Create, Start, Stop, Force Kill, Delete, Get QR, Request Pairing Code, Get Status, List All, Get Stats Overview	Session lifecycle and pairing
Message	Send Text / Image / Video / Audio / Document / Sticker / Location / Contact / Poll / Template, Reply, React, Edit, Delete, Forward, Send Bulk, Get Batch Status, Cancel Batch, List, Get History, Get Reactions	Everything that sends or acts on a message
Contact	Check Exists, Get Info, Get Phone, Get Profile Picture, Get Profile Pictures, List, Block, Unblock	Contact lookup and blocking
Chat	List, Mark Read, Mark Unread, Delete, Set State	Conversations, and typing or recording indicators
Group	List, Get, Create, Join, Leave, Add / Remove / Promote / Demote Participants, Update Subject, Update Description, Get Settings, Update Settings, Get Invite Code, Revoke Invite Code	Group administration
Profile	Set Name, Set Status, Set Picture	The session's own WhatsApp profile
Label	List, Get, Get for Chat, Add to Chat, Remove From Chat	WhatsApp Business labels
Status	List, Get by Contact, Get Media, Delete, Send Text, Send Image, Send Video	Reading and posting Status (Stories)
Template	List, Get, Create, Update, Delete	Stored templates with {{variable}} placeholders
Channel	List, Get, Get Messages, Subscribe, Unsubscribe	WhatsApp Channels the session follows
Call	Reject	Declining an incoming call
Observability	Check, Check Liveness, Check Readiness	Server health probes
System	Get Settings, Get Stats Overview, Get Message Stats, Get Session Stats, Get Audit Log, Search	Server-wide reporting and cross-session search
API Key	List, Get, Create, Update, Revoke, Delete, Validate	API-key administration
Webhook	Create, Get, List, List All, Update, Delete, Test, Get Delivery Failures	Webhook registration and delivery inspection

See the n8n Node Reference for the full field-level detail of every operation. A few endpoints are deliberately absent because the server cannot serve them: Send Catalog and PUT /api/settings were removed from the server in v0.19.0 (both always answered 501); catalog reads and Send Product are Baileys-only and have no operations here — call them with n8n's generic HTTP Request node against a Baileys session if you need them; settings are environment-derived and read-only, and /api/metrics authenticates with its own bearer token rather than the X-API-Key this credential carries. Presence subscription (POST /api/sessions/{sessionId}/presence/subscribe) has no operation either — call it with n8n's generic HTTP Request node using the same credential if you want presence.update events. The complete endpoint list is in the API reference.

Base64 media needs a MIME type

When you send an image or document from a Base64 source, also set the MIME Type field (for example image/png or application/pdf) — OpenWA requires it for base64 payloads. The Binary source fills this in from the binary metadata, and the URL source needs nothing extra.

The OpenWA Trigger node (events)

The trigger node starts a workflow when a WhatsApp event occurs. When you activate the workflow, the node registers a webhook in OpenWA pointing at n8n's webhook URL; when you deactivate it, that webhook is removed. You never manage the webhook by hand.

Select one or more events to subscribe to. Package 0.9.1 offers all twenty-two events the gateway dispatches:

Event	Description
message.received	New incoming message
message.sent	Message successfully sent
message.ack	Message delivery or read acknowledgement
message.failed	Message failed to send
message.revoked	Message deleted for everyone
message.edited	Message text or media edited
message.reaction	Reaction added to or removed from a message
status.received	A contact's Status (Story) is received
session.status	Session status changed
session.qr	QR code generated for scanning
session.authenticated	Session authenticated
session.disconnected	Session lost connection
session.reconnect_loop	Session stuck in a reconnect loop (once per 5 consecutive attempts)
session.restriction	WhatsApp places or lifts a restriction on the account
presence.update	A subscribed chat's presence changes — Baileys only
group.join	A participant joins a group the session belongs to
group.leave	A participant leaves a group the session belongs to
group.update	A group's metadata or roster changes
call.received	An incoming WhatsApp call is detected
call.accepted	An incoming call is answered — Baileys only
call.rejected	An incoming call is declined, including by auto-reject — Baileys only
call.missed	An incoming call goes unanswered — Baileys only

Every event above is available on any server this package supports, so there are no per-event version caveats left to track — the ≥ 0.14.0 floor covers them all.

Four events fire on one engine only

The three call-outcome events fire on Baileys only. whatsapp-web.js hooks the call collection's insert and sees no status at all, so it can report the ring but never how the call ended — a workflow triggered on call.missed simply never runs on a whatsapp-web.js session. call.received fires on both engines.

presence.update is also Baileys-only, and it stays silent until you subscribe the chat with POST /api/sessions/{sessionId}/presence/subscribe. whatsapp-web.js answers that route with 501.

Signature verification

The trigger has an optional Webhook Secret. When set, the secret is registered with OpenWA, and OpenWA signs every delivery with HMAC-SHA256 in the X-OpenWA-Signature: sha256=<hex> header. The node verifies each delivery against the raw request body and rejects any that fail with HTTP 401. Leave it empty to skip verification.

note

Changing or clearing the secret takes effect on the next activation. Deactivate and reactivate the workflow to re-register it.

Trigger payload

The trigger emits one item per event. The event is wrapped in an envelope; the actual event data lives under data:

{
  "event": "message.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "sessionId": "default",
  "idempotencyKey": "a1b2c3d4e5f6",
  "deliveryId": "9f8e7d6c5b4a",
  "data": {
    "id": "3EB0F5A2B4C1",
    "chatId": "628123456789@c.us",
    "from": "628123456789@c.us",
    "body": "Hello!",
    "type": "text",
    "timestamp": 1705312200
  }
}

Reference fields in downstream nodes with n8n expressions — for example {{$json.data.body}} for the message text and {{$json.data.chatId}} for the chat to reply to.

A few notes from the payload contract:

• Read message fields from data (data.body, data.chatId), and the message identifier from data.id — incoming payloads use id, not messageId.
• type is engine-neutral: voice notes are voice, shared contacts are contact, and plain chats are text.
• Check Exists returns whatsappId, the engine-canonical chat id, which may differ from the number you sent (for example an @lid id).

Deduplicate retries

OpenWA retries failed deliveries with the same deliveryId. If your downstream actions aren't idempotent, add a dedup step (a Remove Duplicates node or an IF check) keyed on deliveryId so a retried delivery isn't processed twice.

Example: auto-reply to incoming messages

This is the smallest useful workflow — trigger on an incoming message, check the text, and reply.

1. OpenWA Trigger — select your OpenWA API credential and subscribe to message.received.
2. IF — condition: {{$json.data.body}} contains hello (case-insensitive).
3. OpenWA → Send Text — on the true branch, configure:
   • Session Name or ID: pick your session from the dropdown, which lists the sessions on your server
   • Chat ID: {{$json.data.chatId}}
   • Message: Hi! Thanks for reaching out — how can we help?
4. Activate the workflow. The trigger registers its webhook with OpenWA automatically.

Send "hello" to your WhatsApp number, and you'll get the reply within seconds.

From here, swap the IF for a router to branch on keywords, append each new lead to Google Sheets before replying, or post a Slack alert when session.disconnected fires. The trigger gives you the inbound event; the action node sends the response.

Troubleshooting

Symptom	Cause	Fix
Credential Test fails	Server unreachable, wrong key, or a trailing slash in Server URL	Confirm the server is running and reachable from n8n, the key is correct, and Server URL has no trailing / or /api.
Trigger fires once in the editor, then goes quiet	Listen for test event registers n8n's test URL, which stops after a single delivery	Activate the workflow so the trigger registers its production URL.
Trigger never fires	OpenWA can't reach n8n's webhook URL	Confirm n8n's webhook URL is reachable from the gateway (check firewalls and proxies) and that the session is connected. Then ask the gateway which side dropped the event with GET /api/webhooks/delivery-failures?sessionId={sessionId} (ADMIN key): a row means OpenWA delivered and n8n rejected it, an empty list means the event never reached delivery.
A call.accepted, call.rejected, or call.missed trigger never runs	The session runs whatsapp-web.js	Those three outcomes are Baileys-only. Use call.received, which fires on both engines, or move the session to Baileys.
Workflow won't activate; webhook creation fails with 400	The gateway doesn't know one of the selected events	session.restriction, presence.update, and the three call outcomes need OpenWA ≥ 0.14.0. Upgrade the gateway, or deselect the events it doesn't know.
Send Text returns 400	Session not connected, or invalid chat id	Confirm the session status is ready and the chat id format is correct (628123456789@c.us).
Send Text returns 404	Session id doesn't exist	Pick a real session from the node's Session Name or ID dropdown.
Message sends but never arrives	Recipient isn't on WhatsApp	Use the Check Exists operation before sending to unverified numbers.

Next steps

• n8n Node Reference — every operation and field in detail
• Webhooks — the event model behind the trigger node
• Sending messages — every send operation and its fields
• API reference — every endpoint the action node can call
• n8n Community Nodes documentation — installing and managing community nodes