n8n-nodes-whatsapp-web

This is an n8n community node package that provides WhatsApp Web integration using the whatsapp-web.js library. It allows you to connect to WhatsApp Web, receive messages, and send messages directly from your n8n workflows.

Features

• WhatsApp Web Connect Node: Authenticate and connect to WhatsApp Web using QR code
• WhatsApp Web Trigger Node: Receive WhatsApp messages in real-time
• WhatsApp Web Send Node: Send text messages, media, locations, and replies

Installation

To install this package in your n8n instance:

npm install @salmaneelidrissi/n8n-nodes-whatsapp-web

Important: This package includes Puppeteer as a dependency, which will automatically download Chromium (~170MB). This is required for WhatsApp Web to work.

Docker Installation

For n8n running in Docker, you may need to install additional dependencies:

# Add to your Dockerfile
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Set Puppeteer to use system Chromium
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

Or add the package to your package.json and rebuild your container.

Configuration

Credentials

Create a WhatsApp Web credential with the following fields:

• Session Name: Unique identifier for your WhatsApp session
• Whitelist Numbers: Comma-separated list of phone numbers (with country code and @c.us)
• Webhook URL: Optional webhook URL for message processing

Example whitelist: [email protected],[email protected]

Nodes

WhatsApp Web Connect

Connect to WhatsApp Web and authenticate using QR code.

Operations:

• Connect: Display QR code and authenticate
• Send Message: Send a text message
• Check Status: Check connection status
• Disconnect: Disconnect from WhatsApp Web

WhatsApp Web Trigger

Trigger workflows when WhatsApp messages are received.

Trigger Options:

• All Messages: Trigger on all received messages
• Whitelisted Only: Only trigger for whitelisted numbers
• Groups Only: Only trigger for group messages
• Direct Messages Only: Only trigger for direct messages

Features:

• Whitelist support for specific phone numbers
• Group message handling with mention detection
• Optional webhook processing
• Auto-reply functionality

WhatsApp Web Send

Send various types of messages through WhatsApp Web.

Operations:

• Send Text: Send text messages with optional @mentions
• Send Media: Send images, videos, audio, or documents
• Send Location: Send location coordinates
• Reply to Message: Reply to specific messages

Usage Example

1. Set up credentials with your session name and whitelist numbers
2. Use WhatsApp Web Connect to authenticate (scan QR code)
3. Add WhatsApp Web Trigger to receive messages
4. Use WhatsApp Web Send to respond to messages

Whitelist Logic

• Direct Messages: Sender must be in whitelist
• Group Messages: Any mentioned user must be in whitelist
• Format: Phone numbers with country code and @c.us suffix

Requirements

• n8n version 0.198.0 or later
• Node.js 16 or later
• WhatsApp account

Troubleshooting

Browser/Chromium Issues

Error: Could not find expected browser (chrome) locally

Solution: Install Puppeteer dependencies:

npm install puppeteer

For Docker environments, ensure Chromium is installed:

apt-get update && apt-get install -y chromium

QR Code Not Displaying

• For n8n workflows, use "Return QR Data Only" option to get QR code data in the output
• The QR code data can be used to generate QR codes in your workflow
• Check that QR display is set to "terminal" in Connect node if you want console display
• Ensure console/logs are accessible

Authentication Issues

• Clear browser cache and WhatsApp Web sessions
• Use a unique session name for each instance
• Ensure phone is connected to internet

Message Not Triggering

• Verify whitelist numbers format (include @c.us)
• Check trigger settings (all/whitelisted/groups/direct)
• Ensure sender is in whitelist for restricted triggers

Performance Issues

• Puppeteer downloads ~170MB of Chromium on first install
• Consider using system Chromium in production environments
• Set PUPPETEER_EXECUTABLE_PATH to use system browser

Contributing

This package is based on the original WhatsApp bot code and converted to n8n nodes. Feel free to contribute improvements or report issues.

License

MIT

Author

Salmane El Idrissi ([email protected])

Links

• GitHub Repository
• npm Package
• whatsapp-web.js Documentation