@t0mer/n8n-nodes-openwa

An n8n community node that sends WhatsApp messages through a self-hosted OpenWA gateway.

It sends text, media, locations, polls, contact cards and templates to contacts and groups; replies to, reacts to, forwards, edits, deletes, pins and stars messages; reads message history and downloads media; manages text templates and groups (create, participants, admins, join requests, invite links, settings, picture); posts and reads status updates (stories); updates the account profile; and looks up and manages contacts (list, get, check a number, profile picture, block/unblock, resolve a phone number). It can also be used as a tool by n8n AI Agents.

• Prerequisites
• Installation
• Credentials
• Operations
• Triggers
• Chat ID formats
• Size limits
• Error handling
• Example workflows
• Development
• License

Prerequisites

• A running OpenWA instance, reachable from your n8n server.
• An OpenWA API key.
• At least one OpenWA session that is connected (status ready) to a WhatsApp account.
• n8n 1.x or later (self-hosted or Cloud).

Installation

Community Nodes (recommended)

1. In n8n, open Settings → Community Nodes.
2. Select Install.
3. Enter @t0mer/n8n-nodes-openwa and confirm.

The unscoped n8n-nodes-openwa on npm is a different, unrelated package. Use the scoped name above.

See the n8n community nodes installation guide for details.

Manual install (self-hosted Docker)

Install the package into a folder on the host and point n8n at it with N8N_CUSTOM_EXTENSIONS:

mkdir -p ~/n8n-custom && cd ~/n8n-custom
npm install @t0mer/n8n-nodes-openwa

services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      N8N_CUSTOM_EXTENSIONS: /home/node/custom-nodes
    volumes:
      - ~/n8n-custom/node_modules/@t0mer/n8n-nodes-openwa:/home/node/custom-nodes/n8n-nodes-openwa

Restart n8n after installing or upgrading.

Credentials

Create an OpenWA API credential:

When you save, n8n tests the credential by calling POST /api/auth/validate. A wrong key fails with Authentication failed — check your OpenWA API key.

Operations

Message

Common fields:

• Session: pick a session from the list (shows name and status) or enter its ID.
• Recipient Type: Contact or Group.
  • Phone Number (contact): international format. +, spaces, dashes and parentheses are stripped and @c.us is appended. +972 50-123-4567 becomes 972501234567@c.us.
  • Group: pick a group of the selected session from the list, or enter its ID (must end with @g.us).
• Media Source (media operations):
  • URL: the gateway downloads the file itself.
  • Binary Data: sends the file from a binary field of the input item (default field data), e.g. from an HTTP Request or Read/Write Files from Disk node. The mimetype and file name come from the binary metadata.
• Message ID (Reply, React, Forward, Edit, Delete, Vote Poll, Pin, Star, Download Media): the messageId returned when the message was sent, or waMessageId (not id) from Get Many. The recipient must be the chat that contains the message. You can only edit messages sent by this account.
• Options → Check Number Exists (contacts only, operations that send a new message): looks the number up with GET /contacts/check/{number} before sending and fails the item if it is not on WhatsApp. OpenWA otherwise accepts sends to unregistered numbers without error.
• Options → Reply To Message ID (Send Text, media, Location, Poll, Contact Card): quote a message in the same chat, turning the send into a reply.
• Send Audio → Convert to Voice Note (shown when Send as Voice Note is on): the gateway converts the audio (MP3, M4A, WAV, …) to Ogg/Opus before sending, so it plays as a voice note. Needs media conversion (ffmpeg) enabled on the gateway; otherwise the node fails with a retryable 503.
• Options → Mentions (Send Text, Reply, Edit, Send Template): comma-separated numbers to @mention. The text must contain a matching @<number> token for each one, e.g. Hi @972501234567.

Each item outputs the OpenWA response:

{ "messageId": "true_972501234567@c.us_3EB0123456789", "timestamp": 1758585600 }

A messageId means the gateway accepted the message. It does not confirm delivery.

List operations output one item per entry, and no items when the list is empty, so the next node doesn't run. Turn on the node's Always Output Data setting if a workflow must continue either way. React, Delete and Vote Poll output { "success": true }.

Chat

• Chat: a phone number, a contact ID (@c.us / @lid) or a group ID (@g.us).
• Some gateway operations, such as Mute, only accept the chat's own ID. If an operation fails for a phone number, use the chat's id from Chat → Get Many (often …@lid).

Call

Contact

• Contact: pick a contact of the selected session from the list (searchable by name, number or ID), or enter a phone number or a chat ID ending in @c.us or @lid.
• Phone Number (Check Number): international format; @lid IDs can't be checked.
• Block and Unblock change the WhatsApp account's state. Keep that in mind when giving the node to an AI Agent.

Group

• Group: pick one from the list, or enter its ID (ending in @g.us).
• Participants / Requesters: comma-separated phone numbers or contact IDs (@c.us, @lid), or an array from an expression.
• Most changes need the session account to be a group admin. WhatsApp's refusal comes back as a 403 with the gateway's message.
• Leave, Remove Participants, Revoke Invite Link, Remove Picture, and Approve/Reject with All Pending Requests change the group and can't be undone from the node. Keep that in mind when giving the node to an AI Agent.

Status

Status updates (stories) last 24 hours.

• Post operations output { statusId, timestamp, expiresAt }.
• Recipients (up to 256 phone numbers or contact IDs): the Baileys engine posts only to this list, so it's effectively required there. whatsapp-web.js ignores it and uses the account's status privacy settings.
• Post Voice → Convert to Voice Note: WhatsApp plays a voice status only as Ogg/Opus and the gateway doesn't transcode on its own, so the node converts it first by default. This needs media conversion (ffmpeg) on the gateway. Turn it off if your audio is already Ogg/Opus.

Profile

Changes the session's own WhatsApp account.

Template

Text templates are stored on the gateway per session. Placeholders in double curly braces, e.g. {{name}}, are filled from the Variables of Message → Send Template.

• Template: pick one from the list, or enter its ID.
• Template names are unique per session. Creating or renaming to a name that exists fails with the gateway's message.

Triggers

Trigger nodes start a workflow when OpenWA reports an event. On activation, a trigger registers a webhook for its session on the gateway, with a secret it generates. On deactivation, it deletes the webhook. There's one trigger per event family, plus a general one:

Each run outputs one item with the OpenWA delivery:

{
  "event": "message.received",
  "timestamp": "2026-09-23T10:00:00.000Z",
  "sessionId": "…",
  "idempotencyKey": "msg_…",
  "deliveryId": "dlv_…",
  "data": { "id": "…", "from": "…", "body": "Hi", "type": "chat", "isGroup": false }
}

The gateway must be able to reach n8n. OpenWA refuses webhook URLs on private or local addresses (localhost, 192.168.x.x, …). If activation fails with "refused this n8n webhook URL", you have two options:

• expose n8n on a public URL and set n8n's WEBHOOK_URL to it; or
• add the n8n host to SSRF_ALLOWED_HOSTS on the gateway.

Each session can have up to 16 webhooks. Every active trigger uses one, and so does a trigger listening for a test event (removed when the test ends). Deliveries for another session are ignored.

Options:

• Verify Signature (on by default): each delivery's X-OpenWA-Signature (HMAC-SHA256 of the raw body) is checked against the trigger's secret. Mismatches get 401 and don't run the workflow.
  • The secret is derived from your API key and the trigger node (workflow and node ID), so nothing secret is stored in the workflow, and test and production listens share it.
  • Rotating the API key re-registers the webhook on the next activation.
• Ignore Duplicate Deliveries (on by default): OpenWA delivers at least once and retries failures, so the same event can arrive twice. The trigger drops repeats of an idempotency key it has seen recently.
  • This is best effort: a retry that arrives while the first run is still in progress, or that lands on another n8n worker in queue mode, can still get through.
  • For strict once-only processing, dedupe on idempotencyKey in your own storage.
• Retry Count: delivery attempts per event, 0–5 (default 3).
• Message filters (Message Trigger and OpenWA Events Trigger): Only From, Only In Chats, Body Contains, Chat Type (direct or groups) and Ignore Messages From Me. OpenWA applies them on the gateway, so filtered-out events never reach n8n.
  • They only work with message.received, message.sent, message.edited and message.revoked. Other events carry no sender or text, so the gateway would silently drop them.
  • The node refuses filters combined with any other event, including All Events.

To try a trigger, click Listen for test event (n8n registers a temporary webhook), then send a WhatsApp message to the session's number, or from it.

Chat ID formats

You can enter a phone number (normalized for you), or a full @c.us / @lid ID, which is used unchanged.

Size limits

To send files larger than 18 MB, host them somewhere the gateway can reach and use the URL source.

Error handling

With Settings → On Error → Continue, a failed item outputs { "error": "<message>" } and the rest of the items are still sent.

Example workflows

Alert a group when a form is submitted

Form Trigger → OpenWA (Send Text, Recipient Type: Group, Text: New lead: {{ $json.name }})

Send a generated PDF to a customer

HTTP Request (download the invoice, Response Format: File) → OpenWA (Send Document, Media Source: Binary Data, File Name: invoice-{{ $json.id }}.pdf, Caption: Your invoice)

Voice note from a URL

OpenWA (Send Audio, Media Source: URL, Media URL: https://example.com/note.ogg, Send as Voice Note: on). Use Ogg/Opus audio for voice notes to play reliably.

Development

Requires Node.js 24 LTS.

npm install
npm run dev     # n8n with the node loaded and hot reload, at http://localhost:5678
npm test        # unit tests (vitest)
npm run lint
npm run build

Resources

• n8n community nodes documentation

License

MIT