n8n-nodes-whatsapp-bridge-xyz

v1.0.11

Published

5 months ago

n8n community nodes for WhatsApp Bridge service

0High
0Medium
0Low

appsthecoordinates

n8n-community-node-package whatsapp messaging bridge

WhatsApp Bridge n8n Node Package

A professional n8n community node package for integrating WhatsApp messaging capabilities directly into your n8n workflows.

🚀 Quick Start

Prerequisites

Before installing this package, you MUST have the WhatsApp Bridge service running:

The package requires a backend service running locally or remotely. You have two options:

Option 1: Docker (Recommended)

Download and run the Docker container:

git clone https://github.com/jonathanicq/whatsapp-n8n-bridge.git
cd whatsapp-n8n-bridge
docker compose up -d

Docker Details:

Service runs on http://localhost:4000
Includes MySQL, Redis, and Node.js services
Requires: 512MB RAM, 1 core CPU (1GB/2 cores recommended)
Chromium/Puppeteer included for WhatsApp automation

GitHub Repository: https://github.com/jonathanicq/whatsapp-n8n-bridge

Option 2: Local Installation

npm install
npm run dev  # Starts on http://localhost:4000

Installing the n8n Node Package

Method 1: Via n8n UI (Recommended)

Open n8n: http://your-n8n-address:5678
Go to Settings → Community Nodes
Click Install
Search for n8n-nodes-whatsapp-bridge-xyz
Click Install
n8n will restart automatically

Method 2: Via npm

cd /path/to/your/n8n
npm install n8n-nodes-whatsapp-bridge-xyz

Method 3: Docker Mount

docker run -v ~/.n8n:/home/node/.n8n \
  -e NODE_PATH=/home/node/.n8n/node_modules \
  n8n/n8n

Then inside the container:

npm install n8n-nodes-whatsapp-bridge-xyz

🔧 Configuration

Step 1: Create Credentials

Open any n8n workflow
Add a WhatsApp Bridge node
Click Create Credentials → WhatsApp Bridge API
Fill in the fields:
| Field | Value | Example | |-------|-------|---------| | Base URL | Your Bridge service URL | http://localhost:4000 | | API Key | (Optional) API key if configured | Leave empty if not required |
Save credentials

Step 2: Use in Workflows

Now you can use the WhatsApp Bridge nodes in your workflows!

📋 Available Nodes

1. WhatsApp Bridge (Action Node)

Perform operations on the WhatsApp service.

Operations:

Send Message

Send an immediate WhatsApp message.

To: Phone number in E.164 format (e.g., +351999888777)
Text: Message content

{
  "to": "+351999888777",
  "text": "Hello there!"
}

Queue Message

Queue a message for reliable delivery with automatic retries.

To: Phone number
Text: Message content

Get Status

Check the WhatsApp connection status.

Response:

{
  "connected": true,
  "authenticated": true,
  "phoneNumber": "351999888777"
}

Get Webhooks

List all registered webhooks.

2. WhatsApp Bridge Trigger (Webhook Node)

Trigger workflows when WhatsApp messages are received.

How it works:

Activate the trigger
Service automatically registers webhook
When message arrives, workflow is triggered
Deactivate to unregister webhook

Received Message Format:

{
  "id": "msg-123456",
  "from": "+351999888777",
  "text": "Hello from WhatsApp",
  "timestamp": "2026-03-08T12:00:00Z",
  "type": "text"
}

💡 Workflow Examples

Example 1: Send a Message on Demand

Manual Trigger
  ↓
WhatsApp Bridge (Send Message)
  - To: +351999888777
  - Text: "Hello There"
  ↓
Notification Node (Success)

Example 2: Auto-Reply to Messages

WhatsApp Bridge Trigger (Webhook)
  ↓
Extract Sender: {{ $json.from }}
  ↓
WhatsApp Bridge (Send Message)
  - To: {{ $json.from }}
  - Text: "Thanks for your message! We'll respond soon."

Example 3: Forward to External API

WhatsApp Bridge Trigger
  ↓
HTTP Request (POST to your API)
  ↓
Process Response
  ↓
WhatsApp Bridge (Send Message - Reply)

⚠️ Troubleshooting

"Connection refused"

Problem: Can't connect to Bridge service Solution:

Verify Bridge is running: curl http://localhost:4000/health
Check firewall settings
Ensure correct Base URL in credentials

"Credentials not found"

Problem: Node says credentials missing Solution:

Create new credentials (Settings → Community Nodes → Manage)
Verify credentials are selected in the node
Test connection by clicking node settings

"Phone number format error"

Problem: Message failed to send Solution:

Use E.164 format: +[country-code][number]
Example: +351999888777 (Portugal)
Remove spaces or dashes

"Webhook registration failed"

Problem: Trigger won't activate Solution:

Check Bridge service logs
Verify n8n instance is reachable
Ensure API Key (if required) is correct
Check network connectivity

"Message says queued but not sent"

Problem: Messages not being delivered Solution:

Check WhatsApp authentication: Use "Get Status" operation
Verify phone number format
Check Bridge service logs for errors
Ensure message text is not empty

🐛 Getting Help & Reporting Issues

Found a Bug?

Create an issue on GitHub:

Steps:

Go to: https://github.com/jonathanicq/whatsapp-n8n-bridge/issues
Click New Issue
Provide:
- Description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Environment (n8n version, OS, Docker version)
- Error logs (if available)

Feature Requests

Open a GitHub Discussion or Issue with:

Use case
Expected behavior
Why it would be useful

Need Help?

Check existing issues: https://github.com/jonathanicq/whatsapp-n8n-bridge/issues
Read the documentation: https://github.com/jonathanicq/whatsapp-n8n-bridge#documentation
Create an issue with the [help] tag for guidance

🔐 Security

✅ API credentials stored securely in n8n
✅ Webhook signatures verified with HMAC-SHA256
✅ No sensitive data logged
✅ HTTPS support in production
✅ Secrets never exposed in logs

📦 What's Included

WhatsApp Bridge Node - Action node for sending messages
WhatsApp Bridge Trigger - Webhook trigger for incoming messages
WhatsApp Bridge API Credentials - Secure credential management
Full TypeScript support - Type definitions included
Complete documentation - Inline help and examples

📋 Requirements

| Component | Version | Notes | |-----------|---------|-------| | n8n | 1.0+ | Works with n8n 1.0 and later | | Node.js | 20+ | For bridge service | | Docker | Latest | For running bridge service | | RAM | 512MB | Minimum (1GB recommended) | | Storage | 500MB | For dependencies and session |

📄 License

MIT License - See LICENSE for details

🔗 Useful Links

Bridge Service Repository: https://github.com/jonathanicq/whatsapp-n8n-bridge
Issue Tracker: https://github.com/jonathanicq/whatsapp-n8n-bridge/issues
n8n Documentation: https://docs.n8n.io
n8n Nodes Guide: https://docs.n8n.io/integrations/creating-nodes/

💬 Questions?

📍 Issues & Bugs: GitHub Issues
📚 Documentation: Repository README
🆘 Help: Create an issue with [help] tag

Made with ❤️ for the n8n community