n8n-nodes-openwa

n8n community nodes for the OpenWA WhatsApp API Gateway

Installation • Credentials • Nodes • Examples • Compatibility

---

✨ Overview

Two n8n nodes that connect your workflows to a self-hosted OpenWA WhatsApp API Gateway — send and receive WhatsApp messages, manage contacts, and react to events in real time.

Node	Type	Purpose
OpenWA	Action	Send messages, check contacts, manage sessions and webhooks
OpenWA Trigger	Trigger	Start workflows on incoming messages and session events

---

📦 Installation

Community Nodes (recommended)

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

Manual

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

---

🔑 Credentials

Create an OpenWA API credential:

Field	Description
Server URL	OpenWA server URL, without a trailing slash or /api. Defaults to http://localhost:2785 for a local server (e.g. https://wa.example.com behind a reverse proxy). Use HTTPS in production.
API Key	API key from your OpenWA dashboard. Sent as the X-API-Key header.

The credential is validated with an authenticated GET /api/sessions request, so an invalid API key fails the test.

API key role: send-message and webhook operations require an OPERATOR-role key (the default). A read-only VIEWER key passes the credential test but returns 403 when sending or managing webhooks. VIEWER-safe operations: Session → Get Status / List All, and Contact → Check Exists / Get Info.

---

🧩 Nodes

OpenWA (action)

Resource	Operation	Description
Session	Get Status	Get the status of a session
Session	List All	List all sessions
Message	Send Text	Send a text message
Message	Send Image	Send an image (binary, URL, or Base64)
Message	Send Video	Send a video (binary, URL, or Base64)
Message	Send Document	Send a document / file
Message	Send Audio	Send an audio file or a voice note (PTT)
Message	Send Sticker	Send a sticker (WebP)
Message	Send Location	Send a location pin
Message	Send Contact	Send a contact card (vCard)
Message	Reply	Reply to a message, quoting it
Message	React	Add or remove an emoji reaction
Message	Delete	Delete / revoke a message
Message	Send Bulk	Send up to 100 messages as a throttled batch
Message	Get Batch Status	Poll a bulk batch's progress
Message	Cancel Batch	Cancel a running bulk batch
Contact	Check Exists	Check whether a number is on WhatsApp
Contact	Get Info	Get contact information
Contact	Get Profile Picture	Get a contact's profile-photo URL
Contact	Get Phone	Resolve a contact's phone number
Contact	Block	Block a contact
Contact	Unblock	Unblock a contact
Webhook	Create	Register a webhook (optional signing secret)
Webhook	Update	Update a webhook (partial — only changed fields)
Webhook	Test	Send a test delivery to a webhook
Webhook	Delete	Remove a webhook

Base64 media: when sending an image, document, or audio clip from a Base64 source, also set the MIME Type field (e.g. image/png, application/pdf, audio/ogg; codecs=opus) — OpenWA requires a MIME type for base64 payloads. The Binary source fills it in automatically from the binary metadata, and the URL source needs nothing extra.

Mentions (server ≥ 0.7.14): Send Text, Send Image, Send Video, and Send Document accept an optional Mentions list of WhatsApp IDs (e.g. 628123456789@c.us). For each one to render as an @mention, the message text or caption must also contain the matching @628123456789 token. Leave the list empty on older servers.

Message actions: Reply, React, and Delete act on an existing message identified by its full serialized ID (e.g. true_628123456789@c.us_3EB0…) — the value returned by the send operations and delivered by the Trigger. React with an empty Emoji to remove your reaction; Delete defaults to revoking for everyone.

Bulk send: provide Messages (JSON) as an array of up to 100 items. The media object nests under the type key, and caption sits alongside it on content:

[
  { "chatId": "628123456789@c.us", "type": "text", "content": { "text": "Hello" } },
  { "chatId": "628123456789@c.us", "type": "image", "content": { "image": { "url": "https://example.com/a.jpg" }, "caption": "Hi" } }
]

Media (image/video/audio/document) uses url or base64 (add mimetype for base64) — there is no binary source in bulk. 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 it early with Cancel Batch.

Voice notes (server ≥ 0.7.17): Send Audio has a Send as Voice Note toggle. When on, the clip is delivered as a true WhatsApp voice note (the microphone bubble with a waveform) instead of a plain audio file. Voice notes require audio/ogg; codecs=opus audio for reliable playback. Leave the toggle off (plain audio file) on older servers.

Example — send a text message

1. Add an OpenWA node
2. Select the Message resource and Send Text operation
3. Configure Session ID (default), Chat ID (628123456789@c.us), and Message

OpenWA Trigger

Starts a workflow when the selected events arrive on your session.

Event	Description
message.received	New incoming message
message.sent	Message successfully sent
message.ack	Message delivery / read acknowledgement
message.failed	Message failed to send
message.revoked	Message deleted for everyone
message.reaction	Reaction added to or removed from a message (server ≥ 0.7.2)
session.status	Session status changed
session.qr	QR code generated for scanning
session.authenticated	Session authenticated
session.disconnected	Session lost connection
group.join	Participant joined a group — reserved: accepted on subscribe but not yet emitted by OpenWA
group.leave	Participant left a group — reserved: not yet emitted
group.update	Group metadata changed — reserved: not yet emitted

🔐 Signature verification

The Trigger has an optional Webhook Secret. When set, the secret is registered with OpenWA at webhook creation, 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 (HTTP 401) any that fail. Leave it empty to skip verification.

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

Trigger output

{
  "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
  }
}

Payload notes

• Each delivery is an envelope (event, timestamp, sessionId, idempotencyKey, deliveryId, …); the actual event payload is under data. Read message fields from data (e.g. data.body, data.chatId).
• Read the message identifier from data.id (incoming payloads use id, not messageId).
• OpenWA retries failed deliveries with the same deliveryId — de-duplicate on it if your downstream actions aren't idempotent.
• Message 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).

---

📡 Example Workflows

Pattern	Flow
Auto-reply	[OpenWA Trigger] → [IF: keyword] → [OpenWA: Send Text]
Session monitor	[OpenWA Trigger: session.disconnected] → [Slack: Alert]
Lead capture	[OpenWA Trigger] → [Google Sheets: Append] → [OpenWA: Send Text]

---

🔗 Compatibility

Requires an OpenWA server ≥ 0.4.0 — the webhook event contract and HMAC signature verification the Trigger relies on landed in v0.4.0. Verified against OpenWA v0.8.1.

The Message Reaction event requires server ≥ 0.7.2. Selecting it against an older server returns a 400 when the webhook is created.

---

🛠 Development

npm install      # install dependencies
npm run build    # compile TypeScript + copy icons
npm run dev      # watch mode
npm run lint     # ESLint
npm test         # build + signature-verification unit tests

---

📚 Links

• OpenWA Server — the WhatsApp API Gateway
• OpenWA Documentation
• OpenWA API Reference
• n8n Community Nodes

---

📄 License

MIT — free for personal and commercial use.

---

📦 npm · 🐛 Report Bug · 💡 Request Feature

_{Built for the OpenWA community.}