N8N WhatsApp Automation Nodes

This package provides N8N nodes for WhatsApp automation using a WhatsApp server API.

Features

• WhatsApp Connect Node: Connect to WhatsApp using QR code (data or image)
• WhatsApp Trigger Node: Listen for incoming messages and connection events
• Credential Management: Secure storage of WhatsApp server connection details

Installation

Option 1: Install from NPM (Recommended)

npm install n8n-whats-auto

Then restart your N8N instance to load the new nodes.

Option 2: Install from Source

1. Clone and build the nodes:

git clone https://github.com/yourusername/n8n-whats-auto.git
cd n8n-whats-auto
npm install
npm run build

2. Link the nodes to your N8N installation:

npm link
cd ~/.n8n/nodes
npm link n8n-whats-auto

3. Restart N8N to load the new nodes.

Configuration

WhatsApp Server API Credentials

Before using the nodes, you need to set up WhatsApp Server API credentials:

1. Go to N8N Credentials
2. Create new "WhatsApp Server API" credential
3. Configure:
   • Server URL: Your WhatsApp server URL (e.g., http://localhost:8000)
   • API Key: Optional API key for authentication
   • Session ID: Unique identifier for your WhatsApp session

Nodes

WhatsApp Connect Node

Connects to WhatsApp and manages sessions.

Operations:

• Connect with QR Data: Get raw QR code data for custom QR generation
• Connect with QR Image: Get QR code as base64 image
• Check Session Status: Check if session is connected and authenticated
• Delete Session: Remove a WhatsApp session

Parameters:

• Use Legacy Mode: Enable legacy WhatsApp mode (boolean)

Output:

{
  "success": true,
  "message": "QR code data received, please scan the QR code.",
  "data": {
    "qr": "2@ABC123...",
    "sessionId": "your-session-id"
  }
}

WhatsApp Trigger Node

Listens for WhatsApp messages and events.

Trigger Options:

• All Messages: Trigger on all incoming messages
• Text Messages Only: Only text messages
• Media Messages Only: Only media messages (images, videos, etc.)
• Group Messages: Only group messages
• Direct Messages: Only direct messages
• Connection Events: Connection status changes

Parameters:

• Polling Interval: How often to check for messages (1-300 seconds)
• Filter Keywords: Comma-separated keywords to filter messages

Output for Messages:

{
  "type": "message",
  "messageId": "message-id",
  "sessionId": "your-session-id",
  "chatId": "chat-id",
  "isGroup": false,
  "sender": "sender-id",
  "timestamp": 1234567890,
  "messageText": "Hello world",
  "hasMedia": false,
  "chat": {
    "id": "chat-id",
    "name": "Chat Name",
    "isGroup": false
  }
}

Output for Connection Events:

{
  "type": "connection_event",
  "event": "connected",
  "sessionId": "your-session-id",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "status": "authenticated",
  "userInfo": {
    "id": "user-id",
    "name": "User Name"
  }
}

Usage Examples

Basic Setup Workflow

1. Connect to WhatsApp:

   • Add WhatsApp Connect node
   • Select "Connect with QR Data" operation
   • Execute to get QR code data
   • Scan QR code with WhatsApp mobile app

2. Listen for Messages:

   • Add WhatsApp Trigger node
   • Select trigger type (e.g., "All Messages")
   • Set polling interval (e.g., 5 seconds)
   • Connect to other nodes for message processing

Advanced Message Filtering

{
  "triggerOn": "textMessages",
  "filterKeywords": "help,support,question",
  "pollingInterval": 3
}

This will trigger only on text messages containing "help", "support", or "question".

API Endpoints Used

The nodes interact with these WhatsApp server endpoints:

• POST /sessions/add-qr-data - Get QR code data
• POST /sessions/add - Get QR code image
• GET /sessions/status/{sessionId} - Check session status
• DELETE /sessions/delete/{sessionId} - Delete session
• GET /chats?id={sessionId} - Get chat list
• GET /chats/{chatId}/messages?id={sessionId} - Get messages

Troubleshooting

Common Issues

1. "Session not found" error:

   • Ensure your session ID is correct in credentials
   • Check if the session was created successfully

2. "Connection timeout" error:

   • Verify your WhatsApp server is running
   • Check the server URL in credentials

3. No messages received:

   • Verify the session is authenticated
   • Check polling interval settings
   • Ensure message filters are not too restrictive

Debug Mode

Enable debug logging in N8N to see detailed API requests and responses.

Development

Building

npm run build

Development Mode

npm run dev

Linting

npm run lint
npm run lintfix

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section
2. Review WhatsApp server logs
3. Open an issue on GitHub