Free, Open Source, Self-Hosted WhatsApp API Gateway
22 - n8n Integration
Overview
OpenWA provides official n8n community nodes for integrating WhatsApp automation into n8n workflows. This enables users to build powerful automations combining WhatsApp messaging with hundreds of other services available in n8n.
Repository: https://github.com/rmyndharis/OpenWA-n8n
npm Package: @rmyndharis/n8n-nodes-openwa
Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ n8n Workflow │────▶│ OpenWA Node │────▶│ OpenWA API │
│ │ │ (credentials) │ │ (your server) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ n8n Workflow │◀────│ OpenWA Trigger │◀────│ Webhook POST │
│ (triggered) │ │ (listens) │ │ from OpenWA │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Installation
Via n8n Community Nodes (Recommended)
- Go to Settings > Community Nodes
- Select Install
- Enter
@rmyndharis/n8n-nodes-openwa - Agree to the risks and install
- Restart n8n
Manual Installation
cd ~/.n8n/nodes
npm install @rmyndharis/n8n-nodes-openwa
Nodes
OpenWA Node
Execute operations on your OpenWA server.
Credentials Setup
| Field | Description | Example |
|---|---|---|
| Server URL | OpenWA server URL (without /api) | https://wa.example.com |
| API Key | API key from OpenWA dashboard | owa_xxxxxxxx... |
Resources & Operations
| Resource | Operation | Description | Endpoint |
|---|---|---|---|
| Session | Get Status | Get session status | GET /api/sessions/:id |
| Session | List All | List all sessions | GET /api/sessions |
| Message | Send Text | Send text message | POST /api/sessions/:id/messages/send-text |
| Message | Send Image | Send image (URL/Base64) | POST /api/sessions/:id/messages/send-image |
| Message | Send Document | Send file/document | POST /api/sessions/:id/messages/send-document |
| Message | Send Location | Send location pin | POST /api/sessions/:id/messages/send-location |
| Contact | Check Exists | Check if number on WhatsApp | GET /api/sessions/:id/contacts/check/:number |
| Contact | Get Info | Get contact information | GET /api/sessions/:id/contacts/:contactId |
| Webhook | Create | Create a webhook | POST /api/sessions/:id/webhooks |
| Webhook | Delete | Delete a webhook | DELETE /api/sessions/:id/webhooks/:webhookId |
OpenWA Trigger Node
Start workflows when WhatsApp events occur.
Supported Events
| Event | Description | Use Case |
|---|---|---|
message.received |
New incoming message | Auto-reply, lead capture |
message.sent |
Message sent successfully | Delivery confirmation |
message.ack |
Delivery/read status advanced | Read receipts |
message.receipt |
Per-recipient group/status receipt (Baileys) | Per-member read tracking (not in node 1.2.0) |
message.failed |
Outgoing message failed | Failure alerting |
message.revoked |
Message deleted for everyone | Deletion tracking |
message.reaction |
Reaction added / changed / removed | Reaction tracking |
message.edited |
Message body or caption edited | Content synchronization |
status.received |
Contact posted a Status update | Status archiving |
session.status |
Session status changed | Lifecycle tracking |
session.qr |
QR code generated | Reconnection alerts |
session.authenticated |
Session logged in (phone available) | Startup notifications |
session.disconnected |
Session lost connection | Alert monitoring |
session.reconnect_loop |
Every 5th consecutive reconnect attempt | Stuck-session alerting |
session.restriction |
WhatsApp restricted the account, or lifted it | Pausing outreach while an account is limited |
presence.update |
A watched chat's online/typing state changed | Live agent hand-off, presence-aware routing |
event.response |
A guest answered a WhatsApp event (Baileys) | RSVP and attendance tracking |
poll.vote |
A voter changed their poll answer (wwebjs) | Surveys, check-ins and approvals |
call.accepted / call.rejected / call.missed |
A ringing call ended — Baileys only | Missed-call follow-up, call logging |
group.join |
Participant(s) joined a group | Welcome messages |
group.leave |
Participant(s) left a group | Churn tracking |
group.update |
Group subject/description/settings changed | Group administration |
group.join_request |
Someone asked to join an administered group | Auto-approve/vet join requests |
call.received |
Call ringing, not reliable on whatsapp-web.js | Auto-reject + auto-reply bots |
[!NOTE] The three call-outcome events fire on Baileys only: whatsapp-web.js has no call-outcome event, so a workflow triggered on
call.missednever runs on a whatsapp-web.js session.call.receivedfires on both engines but is not reliable on whatsapp-web.js: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10. Rejecting a call, the session's auto-reject setting included, is Baileys only: a rejection sent by whatsapp-web.js did not stop the call from ringing in a live test. Reliable call automation needs a gateway runningENGINE_TYPE=baileys. The caller infrommay be an@lidprivacy id on either engine; resolve it withGET /api/sessions/{sessionId}/contacts/{contactId}/phone.
How It Works
- When workflow is activated, the trigger creates a webhook in OpenWA
- OpenWA sends events to n8n's webhook URL
- When workflow is deactivated, the webhook is automatically deleted
Output Data Format
{
"event": "message.received",
"timestamp": "2024-01-15T10:30:00Z",
"sessionId": "default",
"idempotencyKey": "msg_default_3EB0F5A2B4C..._f1e2d3c4-b5a6-7890-1234-567890abcdef",
"deliveryId": "dlv_0f8c1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"data": {
"id": "3EB0F5A2B4C...",
"chatId": "[email protected]",
"from": "[email protected]",
"body": "Hello!",
"type": "text",
"timestamp": 1705312200
}
}
Deduplication. Every delivery includes
idempotencyKeyanddeliveryIdin the body and as theX-OpenWA-Idempotency-Key/X-OpenWA-Delivery-Idheaders.idempotencyKeyis stable across retries of the same event;deliveryIdidentifies one delivery to one webhook and is stable across that delivery's retry attempts too — read theX-OpenWA-Retry-Countheader for the attempt number. Because a webhook can be retried, add a dedup step keyed onidempotencyKey(e.g. an n8n IF or "Remove Duplicates" node) so a retried delivery isn't processed twice.
Example Workflows
1. Auto-Reply Bot
Automatically reply to incoming messages with a welcome message.
[OpenWA Trigger] → [IF: Check keyword] → [OpenWA: Send Text]
│
└── Events: message.received
Configuration:
- Trigger:
message.received - IF Node: Check if
{{$json.data.body}}contains "hello" - OpenWA: Send Text with welcome message
2. Lead Collection to Google Sheets
Capture incoming messages and save to Google Sheets.
[OpenWA Trigger] → [Google Sheets: Append] → [OpenWA: Send Text]
│ │
│ └── Save: name, phone, message
└── Events: message.received
3. Session Monitoring
Get notified on Slack when WhatsApp session disconnects.
[OpenWA Trigger] → [Slack: Send Message]
│
└── Events: session.disconnected
Slack Message:
⚠️ WhatsApp session "{{$json.sessionId}}" disconnected!
Time: {{$json.timestamp}}
Please check and reconnect.
4. Order Notification
Send WhatsApp notification when new order is received.
[Webhook: New Order] → [OpenWA: Send Text]
│
└── "Thank you for your order #{{$json.orderId}}"
5. Scheduled Reminders
Send daily reminders to a list of contacts.
[Schedule Trigger] → [Google Sheets: Get Rows] → [Loop] → [OpenWA: Send Text]
│ │ │
└── Daily 9AM └── Get contacts └── Send reminder
6. Appointment Booking
Collect appointment requests over WhatsApp, check availability in an external scheduling source, and send a confirmation or alternative time slots.
See n8n Appointment Booking Workflow for a complete example.
[OpenWA Trigger] → [IF: Booking intent?] → [Set: Normalize request]
│
▼
[Availability Source]
│
┌─────────────────────┴─────────────────────┐
▼ ▼
[Create Booking] → [OpenWA: Send Text] [OpenWA: Send Text]
confirmed confirmation alternative slots
Best Practices
1. Error Handling
Always add error handling in your workflows:
[OpenWA Node] → [IF: Check success] → [Continue...]
│
└── [Error Handler]
2. Rate Limiting
WhatsApp has rate limits. Add delays between messages:
[Loop Over Items] → [Wait: 2 seconds] → [OpenWA: Send Text]
3. Message Formatting
Use WhatsApp formatting in your messages:
- Bold:
*text* - Italic:
_text_ - Strikethrough:
~text~ - Monospace:
`text`
4. Phone Number Format
Always use the correct format for chat IDs:
- Personal:
[email protected] - Group:
[email protected]
Troubleshooting
Credential Test Failed
- Verify OpenWA server is running
- Check API key is correct
- Ensure server URL doesn't have trailing slash
- Verify network connectivity between n8n and OpenWA
Trigger Not Receiving Events
- Confirm you registered the production webhook URL, not the test one. n8n gives every Webhook
node two URLs: a test URL (
https://your-n8n/webhook-test/…) and a production URL (https://your-n8n/webhook/…). The test URL is registered only while the editor is listening and stops after a single request, so a workflow wired to it receives one event and then goes silent. Activate the workflow and point OpenWA at the production URL. - Check webhook was created in OpenWA dashboard
- Verify n8n webhook URL is accessible from OpenWA server
- Check firewall/proxy settings
- Ensure session is connected and active
- For a call trigger, check the session's engine: the call-outcome events never fire on
whatsapp-web.js and
call.receivedis not reliable there (see the note under the trigger event table above) - Ask OpenWA which side dropped the event:
GET /api/webhooks/delivery-failures?sessionId={sessionId}(ADMIN key). A row with an HTTPlastStatusCodemeans OpenWA delivered and n8n rejected it. A row without one and withattempts: 0was never sent (shed under load, dropped at shutdown, over the payload size cap, or failed before sending; a shed or shutdown row is replayed later), except one that shutdown stopped between retries with the queue disabled, whose earlier attempts were sent; with attempts, n8n timed out or was unreachable. An empty list means nothing has failed permanently yet: retries still in flight show only in the server logs, and an event that never matched the webhook leaves no row
Message Not Sending
- Verify session status is
ready(the API returns lowercase status values) - Check chat ID format is correct
- Ensure recipient number exists on WhatsApp
- Check message content isn't empty
Development
Building from Source
git clone https://github.com/rmyndharis/OpenWA-n8n.git
cd OpenWA-n8n
npm install
npm run build
Local Development
# Watch mode
npm run dev
# Link to local n8n
cd ~/.n8n/nodes
npm link /path/to/OpenWA-n8n
Testing
Test your changes with a local n8n instance:
# Start n8n
n8n start
# Or with Docker
docker run -it --rm \
-p 5678:5678 \
-v ~/.n8n:/home/node/.n8n \
n8nio/n8n
Related Documentation
- OpenWA API Specification
- Webhook System
- n8n Appointment Booking Workflow
- n8n to Discord Workflow, built from n8n's own Webhook and HTTP Request nodes
- n8n Documentation