npm package: @salmaneelidrissi/n8n-nodes-whatsapp-web
Description: n8n nodes for WhatsApp Web integration using whatsapp-web.js
Author: Salmane El Idrissi
Latest version: 1.0.25

# 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:

```bash
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:

```dockerfile
# 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: `919876543210@c.us,919876543211@c.us`

## 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:

```bash
npm install puppeteer
```

For Docker environments, ensure Chromium is installed:

```bash
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 (salmaneelidrissi97@gmail.com)

## Links

- [GitHub Repository](https://github.com/salmaneelidrissi/n8n-nodes-whatsapp-web)
- [npm Package](https://www.npmjs.com/package/@salmaneelidrissi/n8n-nodes-whatsapp-web)
- [whatsapp-web.js Documentation](https://wwebjs.dev/)