n8n-nodes-wwebjs-api

n8n community node for WWebJS REST API — automate WhatsApp Web messaging from n8n.

This node provides a bridge between n8n and WhatsApp Web, powered by the excellent whatsapp-web.js library.

Architecture

┌─────────┐     ┌──────────────────────┐     ┌─────────────────┐     ┌──────────────┐
│   n8n   │────▶│  n8n-nodes-wwebjs-api │────▶│   wwebjs-api    │────▶│ whatsapp-web.js │
│         │◀────│    (this package)     │◀────│  (REST server)  │◀────│   (library)     │
└─────────┘     └──────────────────────┘     └─────────────────┘     └──────────────┘
                                                     │
                                                     ▼
                                              ┌──────────────┐
                                              │ WhatsApp Web │
                                              └──────────────┘

• whatsapp-web.js - A WhatsApp client library for NodeJS that connects through the WhatsApp Web browser app
• wwebjs-api - REST API wrapper that exposes whatsapp-web.js functionality via HTTP endpoints
• n8n-nodes-wwebjs-api (this package) - n8n nodes that integrate with wwebjs-api

Features

This package provides two nodes:

• WWebJS API — Action node with 7 resources and 75+ operations
• WWebJS API Trigger — Webhook trigger for incoming WhatsApp events with advanced filtering

Highlights

• Send text, media, location, contacts, and polls
• Manage multiple WhatsApp sessions
• Group management (add/remove participants, admin controls)
• Channel support (WhatsApp Channels/Newsletters)
• Message reactions, replies, forwards, and edits
• Webhook trigger with filters (session, chat, content, sender)
• Webhook authentication (Header Auth, HMAC signature)
• Input validation with descriptive error messages
• Multi-item support — processes each input item independently with pairedItem tracking and input data forwarding

Compatibility

| Component | Required version | Notes | |-----------|-----------------|-------| | n8n | >= 1.0.0 | n8n-workflow >= 2.0.0 | | wwebjs-api | >= 1.34.0 | Tested with avoylenko/wwebjs-api v1.34.x | | Node.js | >= 20.0.0 | Required by dev tooling; n8n itself requires >= 22.16 |

Note: This package depends on the REST API exposed by wwebjs-api. Since wwebjs-api does not version its endpoints, a future major release could introduce breaking changes. Pin your wwebjs-api Docker image to a specific tag (e.g. avoylenko/wwebjs-api:1.34.6) instead of using :latest to avoid surprises.

Prerequisites

1. WWebJS API instance running and accessible — Setup instructions
2. n8n v1.0.0+ instance

Quick start with Docker Compose

version: '3.8'
services:
  wwebjs-api:
    image: avoylenko/wwebjs-api:1.34.6
    ports:
      - "3000:3000"
    environment:
      - API_KEY=your-secret-api-key
      - BASE_WEBHOOK_URL=http://n8n:5678/webhook/whatsapp
    volumes:
      - wwebjs_sessions:/app/sessions

  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  wwebjs_sessions:
  n8n_data:

Installation

Option A: Community Nodes (Recommended)

1. Go to Settings → Community Nodes
2. Click Install a community node
3. Enter: n8n-nodes-wwebjs-api
4. Click Install
5. Restart n8n if prompted

Option B: Install from GitHub

cd ~/.n8n
npm install github:vgpastor/n8n-nodes-wwebjs-api

# Or with a specific version/tag
npm install github:vgpastor/n8n-nodes-wwebjs-api#v1.0.0

Option C: Install from npm

cd ~/.n8n
npm install n8n-nodes-wwebjs-api

Option D: Local development

# Clone and build
git clone https://github.com/vgpastor/n8n-nodes-wwebjs-api.git
cd n8n-nodes-wwebjs-api
npm install
npm run build
npm link

# Link to n8n
cd ~/.n8n
npm link n8n-nodes-wwebjs-api

After installation, restart n8n and the nodes will appear in the node palette.

Configuration

1. Set up WWebJS API credentials

In n8n, go to Settings → Credentials → Add Credential → WWebJS API and configure:

| Field | Description | Example | | ------------------ | ----------------------------------------------------- | ----------------------- | | Base URL | URL of your WWebJS API instance | http://localhost:3000 | | API Key | The API_KEY env var from your WWebJS API | my-secret-key | | Default Session ID | Default session to use when not specified in the node | main-session |

2. Configure webhook in WWebJS API

To receive WhatsApp events in n8n, you need to configure wwebjs-api to send events to your n8n webhook URL.

Steps:

1. Create a workflow in n8n with the WWebJS API Trigger node
2. Activate the workflow - n8n will generate a webhook URL (e.g., https://your-n8n.com/webhook/abc123)
3. Copy that URL and configure it in wwebjs-api environment variables:

Option A: Global webhook (All sessions)

All sessions send events to the same URL:

BASE_WEBHOOK_URL=https://your-n8n.com/webhook/abc123

Tip: Use the Session ID filter in the trigger node to route events from different sessions to different workflows.

Option B: Per-session webhook

Each session can have its own webhook URL using the pattern {SESSIONID}_WEBHOOK_URL:

# Global fallback
BASE_WEBHOOK_URL=https://your-n8n.com/webhook/default

# Session "sales" sends to a different workflow
SALES_WEBHOOK_URL=https://your-n8n.com/webhook/sales-workflow

# Session "support" sends to another workflow
SUPPORT_WEBHOOK_URL=https://your-n8n.com/webhook/support-workflow

Additional webhook options

# Disable webhooks entirely (if using websockets instead)
ENABLE_WEBHOOK=FALSE

# Disable specific events you don't need
DISABLED_CALLBACKS=message_ack,chat_removed,loading_screen

Resources & Operations

Session

| Operation | Description | | ------------------ | ---------------------------- | | Start | Start a new WhatsApp session | | Stop | Stop a session | | Get Status | Get session status | | Get QR Code | Get QR code for login | | Get QR Image | Get QR as PNG image | | Restart | Restart a session | | Terminate | Terminate and delete session | | Terminate All | Terminate all sessions | | Terminate Inactive | Terminate inactive sessions | | Get All Sessions | List all active sessions |

Client (core messaging)

| Operation | Description | | -------------------- | -------------------------------------------- | | Send Message | Send text, media, location, contact, or poll | | Create Group | Create a new group chat with participants | | Get Chats | Get all current chats | | Get Chat By ID | Get a specific chat | | Get Contacts | Get all contacts | | Get Contact By ID | Get a specific contact | | Search Messages | Search for messages | | Is Registered User | Check if a number is on WhatsApp | | Get Number ID | Get the WhatsApp ID for a number | | Get Connection State | Get the client connection state | | Send Seen | Mark a chat as seen | | Set Status | Update your status message | | Get Profile Pic URL | Get a contact's profile picture | | Archive/Unarchive | Archive or unarchive a chat | | Mute/Unmute | Mute or unmute a chat | | Pin/Unpin | Pin or unpin a chat | | Get Blocked | Get blocked contacts |

Message

| Operation | Description | | -------------- | --------------------------- | | Reply | Reply to a specific message | | React | React with an emoji | | Forward | Forward to another chat | | Edit | Edit a sent message | | Delete | Delete a message | | Download Media | Download attached media | | Get Info | Get message delivery info | | Star/Unstar | Star or unstar a message |

Chat

| Operation | Description | | -------------------- | ------------------------ | | Fetch Messages | Load messages from chat | | Get Contact | Get contact for a chat | | Get Info | Get chat details | | Get Labels | Get labels for a chat | | Send Typing State | Show typing indicator | | Send Recording State | Show recording indicator | | Send Seen | Mark messages as seen | | Mark Unread | Mark chat as unread | | Clear Messages | Clear all messages | | Delete | Delete a chat |

Group Chat

| Operation | Description | | -------------------- | ------------------------ | | Get Info | Get group details | | Add Participants | Add members to group | | Remove Participants | Remove members from group| | Promote Participants | Promote to admin | | Demote Participants | Demote from admin | | Get Invite Code | Get group invite link | | Leave | Leave the group | | Revoke Invite | Invalidate invite code | | Set Subject | Update group name | | Set Description | Update group description |

Contact

| Operation | Description | | ---------------- | ------------------------ | | Get Info | Get contact details | | Block | Block a contact | | Unblock | Unblock a contact | | Get About | Get contact status text | | Get Chat | Get chat for a contact | | Get Profile Pic | Get profile picture URL | | Get Common Groups| Get groups in common |

Channel (WhatsApp Newsletters)

| Operation | Description | | -------------- | --------------------------- | | Get All | Get all subscribed channels | | Get Info | Get channel details | | Send Message | Send message to a channel | | Fetch Messages | Load channel messages | | Create | Create a new channel | | Subscribe | Subscribe to a channel | | Unsubscribe | Unsubscribe from a channel | | Search | Search public channels | | Delete | Delete a channel you own |

Trigger Events

The WWebJS API Trigger node can listen for these events:

| Event | Description | | ------------------------- | ----------------------------------------- | | message | New incoming message received | | message_create | Any message created (including sent) | | message_ack | Message status (sent/delivered/read) | | message_revoke_everyone | Message deleted for everyone | | message_revoke_me | Message deleted for me | | qr | QR code for authentication | | authenticated | Client authenticated | | auth_failure | Authentication failed | | ready | Client ready | | disconnected | Client disconnected | | change_state | Connection state changed | | group_join | Someone joined a group | | group_leave | Someone left a group | | group_update | Group info updated | | call | Incoming call | | chat_archived | Chat was archived/unarchived | | chat_removed | Chat was removed | | loading_screen | Loading screen progress | | media_uploaded | Media has been uploaded | | contact_changed | Contact has been updated |

Trigger Filters

Filter incoming events to only trigger workflows when conditions are met:

| Filter | Description | | ------------------------- | ------------------------------------------------ | | Session ID | Only events from a specific session | | Chat ID Contains | Filter by phone number or chat type (@g.us) | | Body Contains | Filter by message content (e.g., /command) | | From Me Only | Only messages sent by you | | Exclude From Me | Only messages from others | | Groups Only | Only group chat messages | | Individuals Only | Only individual chat messages |

Trigger Authentication

Secure your webhook endpoint:

| Method | Description | | -------------- | ---------------------------------------------- | | None | No authentication (not recommended) | | Header Auth | Validate a custom header token | | HMAC Signature | Validate SHA-256 signature (timing-safe) |

Usage Examples

Send a WhatsApp message

1. Add WWebJS API node
2. Select Client → Send Message
3. Set Session ID = my-session
4. Set Chat ID = [email protected]
5. Set Content Type = Text
6. Set Message Text = Hello from n8n!

Auto-reply to incoming messages

1. Add WWebJS API Trigger node with event message
2. Set filter: Exclude From Me = true
3. Add IF node to check message content
4. Add WWebJS API node with Client → Send Message
5. Use expression {{ $json.data.from }} for Chat ID

Send media from URL

1. Add WWebJS API node
2. Select Client → Send Message
3. Set Content Type = Media (URL)
4. Set Content (JSON):

{
  "url": "https://example.com/image.jpg",
  "caption": "Check out this image!"
}

Forward messages to another chat

1. Add WWebJS API Trigger with filter Body Contains = /forward
2. Add WWebJS API node with Message → Forward
3. Use {{ $json.data.id._serialized }} for Message ID
4. Set destination Chat ID

Send a message to multiple contacts (multi-item)

1. Add a node that outputs multiple items (e.g., a Code node returning a list of contacts)
2. Connect it to WWebJS API → Client → Send Message
3. Use expressions: Chat ID = {{ $json.chatId }}, Message Text = Hello {{ $json.name }}!
4. The node processes each item independently — all contacts receive their message
5. Output preserves the original input data (e.g., name, chatId) merged with the API response (success, messageId), so downstream nodes can access both

Webhook Payload Structure

When the trigger node receives an event, the payload has this structure:

{
  "dataType": "message",
  "sessionId": "my-session",
  "data": {
    "from": "[email protected]",
    "to": "[email protected]",
    "body": "Hello!",
    "fromMe": false,
    "hasMedia": false,
    "type": "chat",
    "timestamp": 1234567890,
    "id": {
      "fromMe": false,
      "remote": "[email protected]",
      "id": "ABCDEF123456",
      "_serialized": "[email protected]_ABCDEF123456"
    }
  }
}

Use n8n expressions to access fields, for example:

• Chat ID: {{ $json.data.from }}
• Message text: {{ $json.data.body }}
• Session: {{ $json.sessionId }}
• Message ID: {{ $json.data.id._serialized }}

Content Type JSON Formats

When using Send Message with non-text content types, the Content (JSON) field expects these formats:

Media (Base64) — MessageMedia

{
  "mimetype": "image/jpeg",
  "data": "base64-encoded-data...",
  "filename": "photo.jpg"
}

Media (URL) — MessageMediaFromURL

{
  "url": "https://example.com/image.jpg",
  "caption": "Check this out!"
}

Location

{
  "latitude": 40.4168,
  "longitude": -3.7038,
  "description": "Madrid, Spain"
}

Contact (vCard)

{
  "displayName": "John Doe",
  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+34612345678\nEND:VCARD"
}

Poll

{
  "pollName": "What do you prefer?",
  "pollOptions": ["Option A", "Option B", "Option C"],
  "options": {
    "allowMultipleAnswers": false
  }
}

Troubleshooting

Session not connecting / stuck on STARTING

• Ensure your wwebjs-api instance is running and accessible from n8n
• Check the wwebjs-api logs for errors
• Try terminating and restarting the session

QR code expired

• QR codes expire after ~60 seconds. Use the Get QR Image operation to get a fresh one
• You can set up a workflow to periodically poll the QR code endpoint

status@broadcast errors

• Some events include status@broadcast as the chat ID. Use the Chat ID Contains filter to exclude these by filtering for @c.us or @g.us

Media messages returning empty data

• Ensure the message actually has media (hasMedia: true in the webhook payload)
• Use the Message → Download Media operation with the correct chat ID and message ID

Webhook not receiving events

• Verify BASE_WEBHOOK_URL is set correctly in your wwebjs-api environment
• Make sure the n8n workflow with the trigger is activated
• Check that the webhook URL is reachable from the wwebjs-api container (use container networking if both run in Docker)
• Check DISABLED_CALLBACKS is not blocking the events you need

Invalid chat/contact ID format errors

• Individual chats: [email protected] (e.g., [email protected])
• Group chats: [email protected] or [email protected]
• Channels: number@newsletter
• Phone numbers: digits only, no + sign, 7-15 digits

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Related Projects

• whatsapp-web.js - The underlying WhatsApp Web client library
• wwebjs-api - REST API server that this node connects to
• n8n - Workflow automation platform

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or affiliates. The official WhatsApp website can be found at https://whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners.

Use this software at your own risk. The authors are not responsible for any bans or restrictions imposed by WhatsApp.

Author

Victor García Pastor - @vgpastor

License

MIT - See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request