n8n-nodes-whatsapp-api

Custom n8n nodes for integrating with WhatsApp API Manager. Automate your WhatsApp workflows with powerful nodes for sending messages, managing sessions, labels, and webhooks.

📦 Installation

Option 1: Install from npm (Recommended)

npm install n8n-nodes-whatsapp-api

Option 2: Manual Installation

1. Clone this repository
2. Navigate to the project directory
3. Build the project:

   npm install
   npm run build
   

4. Link to your n8n installation:

   npm link
   cd ~/.n8n
   npm link n8n-nodes-whatsapp-api
   

Option 3: Docker

If you're using n8n with Docker, mount the built nodes:

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v /path/to/n8n-nodes-whatsapp-api/dist:/home/node/.n8n/custom \
  n8nio/n8n

🔐 Credentials Setup

1. In n8n, go to Credentials → New
2. Search for "WhatsApp API"
3. Configure:
   • API URL: Your WhatsApp API base URL (e.g., http://localhost:3001)
   • API Token: Your JWT authentication token
4. Click Test to verify the connection
5. Save the credentials

📚 Available Nodes

1. WhatsApp API Trigger

Receive WhatsApp messages and events via webhook.

Features:

• Real-time message reception
• Event filtering (received, sent, delivered, read, QR updates, etc.)
• Automatic webhook registration

Example Use Cases:

• Auto-respond to customer messages
• Log all incoming messages
• Trigger workflows based on keywords

2. WhatsApp API - Send Message

Send various types of messages through WhatsApp.

Message Types:

• Text: Simple text messages with formatting
• Image: Send images with optional captions
• Video: Send video files
• Audio: Send audio/voice messages
• Document: Send PDF and other documents
• Buttons: Interactive messages with up to 3 buttons
• Bulk: Send to multiple recipients

Features:

• Media support (URL or base64)
• Label assignment
• Bulk sending with delay control
• Rich text formatting

Example Use Cases:

• Send promotional messages
• Share documents with customers
• Create interactive menus with buttons
• Bulk notifications

3. WhatsApp API - Session

Manage WhatsApp sessions (connections).

Operations:

• Create Session
• Get Session Details
• List All Sessions
• Start Session
• Stop Session
• Delete Session

Example Use Cases:

• Initialize new WhatsApp connections
• Monitor session status
• Manage multiple WhatsApp accounts
• Auto-restart disconnected sessions

4. WhatsApp API - Labels

Manage WhatsApp Business labels for organization.

Operations:

• Create Label (20 colors available)
• Get All Labels
• Delete Label
• Apply Label to Chat
• Remove Label from Chat
• Get Chat Labels

Example Use Cases:

• Organize conversations by category
• Tag important customers
• Filter chats by label
• Automated labeling based on message content

5. WhatsApp API - Webhook

Manage webhook configurations.

Operations:

• Register Webhook
• List Webhooks
• Toggle Webhook (enable/disable)
• Delete Webhook
• Get Webhook Logs
• Test Webhook

Example Use Cases:

• Configure multiple webhook endpoints
• Monitor webhook delivery
• Debug webhook issues
• Manage event subscriptions

🚀 Example Workflows

Auto-Reply Bot

WhatsApp Trigger → IF (contains keyword) → Send Message

1. Add WhatsApp API Trigger node
2. Add IF node to check message content
3. Add WhatsApp API - Send Message node to reply

Customer Support Labeling

WhatsApp Trigger → Analyze Message → Apply Label

1. Receive message via WhatsApp API Trigger
2. Process/analyze content (AI, keywords, etc.)
3. Use WhatsApp API - Labels to categorize

Bulk Campaign

Spreadsheet → Loop → Send Message (with delay)

1. Load contacts from spreadsheet
2. Use WhatsApp API - Send Message in bulk mode
3. Add delay to avoid rate limits

Session Monitor

Schedule Trigger → List Sessions → IF (disconnected) → Start Session

1. Run every 5 minutes with Schedule Trigger
2. Get all sessions with WhatsApp API - Session
3. Check status and restart if needed

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• n8n installed (globally or locally)

Setup

# Clone the repository
git clone https://github.com/joaopauloqueiroz/whatsapp-api.git
cd whatsapp-api/n8n-nodes-whatsapp-api

# Install dependencies
npm install

# Build in watch mode
npm run dev

Testing Locally

# Build the project
npm run build

# Link to n8n
npm link

# In your n8n directory
npm link n8n-nodes-whatsapp-api

# Start n8n
n8n start

Your custom nodes will appear in n8n under the "Custom" category.

Project Structure

n8n-nodes-whatsapp-api/
├── credentials/
│   └── WhatsAppApi.credentials.ts    # Authentication
├── nodes/
│   ├── WhatsAppApiTrigger/
│   │   └── WhatsAppApiTrigger.node.ts
│   ├── WhatsAppApiSendMessage/
│   │   └── WhatsAppApiSendMessage.node.ts
│   ├── WhatsAppApiSession/
│   │   └── WhatsAppApiSession.node.ts
│   ├── WhatsAppApiLabels/
│   │   └── WhatsAppApiLabels.node.ts
│   └── WhatsAppApiWebhook/
│       └── WhatsAppApiWebhook.node.ts
├── package.json
├── tsconfig.json
└── gulpfile.js

📖 API Reference

This package integrates with WhatsApp API Manager.

Required API Endpoints:

• POST /api/sessions - Create session
• GET /api/sessions - List sessions
• POST /api/messages/:sessionId/send - Send message
• GET /api/labels/:sessionId/labels - Get labels
• POST /api/webhooks - Register webhook

For full API documentation, see the main project README.

🐛 Troubleshooting

Nodes not appearing in n8n

1. Ensure the package is properly linked: npm link n8n-nodes-whatsapp-api
2. Restart n8n
3. Check n8n logs for errors

Authentication errors

1. Verify your API URL is correct (include http:// or https://)
2. Check that your JWT token is valid
3. Test credentials using the "Test" button

Webhook not receiving events

1. Ensure your n8n instance is publicly accessible
2. Check webhook URL in the WhatsApp API dashboard
3. Verify event types are correctly configured

Build errors

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

🔗 Links

• Main WhatsApp API Project
• n8n Documentation
• n8n Community Nodes

💬 Support

• Open an issue on GitHub
• Check existing issues for solutions
• Refer to the main project documentation

⭐ Credits

Created by ArchCode

Built with:

• n8n - Workflow automation
• WhatsApp Web.js - WhatsApp client

---

Made with ❤️ for the n8n community