n8n-nodes-wapizap

Official n8n community nodes for the WapiZap WhatsApp API. Send messages, manage instances, handle groups, and automate WhatsApp workflows with ease.

🚀 Features

• 5 Specialized Nodes: Trigger, Instance, Message, Group, and Chat management
• Dual API Support: v2 (Modern REST - recommended) and v1 (Evolution API compatible)
• Advanced Filtering: Powerful webhook filtering system with 5 filter categories
• Zero Dependencies: Lightweight implementation using only n8n-workflow
• Lazy Loading: Operations load on-demand for optimal performance
• Security First: HMAC validation, SSRF protection, input sanitization, API key masking
• TypeScript: Fully typed with strict type checking

📦 Installation

Via n8n Community Nodes

1. Go to Settings → Community Nodes in your n8n instance
2. Click Install
3. Enter: n8n-nodes-wapizap
4. Click Install

Via npm (for self-hosted)

npm install n8n-nodes-wapizap

Manual Installation

cd ~/.n8n/custom
npm install n8n-nodes-wapizap
# Restart n8n

🔧 Nodes Included

1. WapiZap Trigger

Webhook node that receives WhatsApp events with advanced filtering capabilities.

Features:

• Event filtering (message.received, message.sent, connection.update, etc.)
• Context filters (message types, senders, chat types, group whitelist/blacklist)
• Content filters (keywords, regex, URLs, emails, phone numbers)
• Time filters (business hours, days of week, timezone)
• Behavior filters (cooldown, rate limiting, first message only)
• Custom JavaScript filters
• HMAC signature validation for security

Use Cases:

• Auto-respond to customer inquiries
• Filter spam messages
• Route messages to different workflows
• Business hours automation
• Chatbot triggers

2. WapiZap Instance

Manage WhatsApp instances and connections.

Operations (8):

• Create Instance
• List Instances
• Get Instance (v2 only)
• Delete Instance
• Connect Instance
• Disconnect Instance
• Get QR Code
• Check Status

Use Cases:

• Multi-instance management
• Auto-reconnection workflows
• QR code generation
• Instance health monitoring

3. WapiZap Message

Send various types of WhatsApp messages.

Operations (15):

• Send Text
• Send Image
• Send Video
• Send Audio
• Send Document
• Send Sticker
• Send Location
• Send Contact
• Send Poll
• Send Buttons (v1 only)
• Send List (v1 only)
• Send Reaction
• Edit Message (v2 only)
• Delete Message

Use Cases:

• Marketing campaigns
• Customer support
• Automated notifications
• File sharing
• Interactive polls and surveys

4. WapiZap Group

Manage WhatsApp groups.

Operations (11):

• Create Group
• List Groups
• Get Group Info
• Update Picture
• Update Settings
• Add Participants
• Remove Participants
• Promote Admin
• Demote Admin
• Get Invite Code
• Leave Group

Use Cases:

• Automated group creation
• Bulk participant management
• Admin management
• Group moderation

5. WapiZap Chat

Manage chats and download media.

Operations (11):

• List Chats
• Get Messages
• Mark as Read
• Archive Chat
• Check Number
• Get Profile Picture
• Send Presence (typing, recording)
• Download Image
• Download Video
• Download Audio
• Download Document

Use Cases:

• Chat archival
• Message history retrieval
• Media backup
• Presence simulation
• Number validation

🔑 Authentication

1. In n8n, go to Credentials → New
2. Search for WapiZap API
3. Fill in:
   • API Key: Your WapiZap API key
   • Environment: Production, Development, or Custom
   • Base URL (for Custom): Your custom API URL

Get your API key from: https://api.wapizap.com

📚 Usage Examples

Example 1: Auto-Respond to Keywords

[WapiZap Trigger]
  ├─ Event: message.received
  ├─ Content Filter: containsKeyword = "help, ajuda, support"
  └─ Time Filter: Mon-Fri, 9AM-6PM
        ↓
[WapiZap Message: Send Text]
  └─ Text: "Thank you for contacting us! How can we help you?"

Example 2: Group Welcome Message

[WapiZap Trigger]
  ├─ Event: group.participant.add
  └─ Context Filter: chatTypes = "group"
        ↓
[WapiZap Message: Send Text]
  └─ Text: "Welcome to the group! Please read our rules."

Example 3: Media Backup

[WapiZap Trigger]
  ├─ Event: message.received
  └─ Context Filter: messageTypes = "image, video"
        ↓
[WapiZap Chat: Download Image/Video]
        ↓
[Google Drive: Upload File]

Example 4: Business Hours Only

[WapiZap Trigger]
  ├─ Event: message.received
  ├─ Time Filter: Enabled
  ├─ Start Time: 09:00
  ├─ End Time: 18:00
  ├─ Days: Monday to Friday
  └─ Timezone: America/Sao_Paulo
        ↓
[WapiZap Message: Send Text]

Example 5: Rate Limiting

[WapiZap Trigger]
  ├─ Event: message.received
  ├─ Behavior Filter: cooldownSeconds = 60
  └─ Behavior Filter: maxPerMinute = 3
        ↓
[Your Workflow]

🔒 Security Features

• HMAC Validation: Verify webhook authenticity with SHA-256 signatures
• SSRF Protection: Block internal/localhost URLs in media downloads
• Input Sanitization: Clean phone numbers, validate URLs
• API Key Masking: Sensitive data redacted from logs and errors
• Rate Limiting: Built-in cooldown and per-minute limits
• No Data Leaks: Error messages sanitized

🎯 API Version Comparison

Feature	v2 (Modern REST)	v1 (Evolution)
Recommended	✅ Yes	⚠️ Legacy
Edit Messages	✅	❌
Button Messages	❌	✅
List Messages	❌	✅
Cleaner Endpoints	✅	❌
Response Format	Modern	Evolution-like

Recommendation: Use v2 for new projects. Use v1 only if you need button/list messages or Evolution API compatibility.

🛠️ Development

Build from Source

git clone https://github.com/your-repo/n8n-nodes-wapizap.git
cd n8n-nodes-wapizap
npm install
npm run build

Link Locally

npm link
cd ~/.n8n/custom
npm link n8n-nodes-wapizap
n8n start

Linting & Formatting

npm run lint          # Check linting
npm run lint:fix      # Fix linting issues
npm run format        # Format code
npm run format:check  # Check formatting

📝 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

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

📞 Support

• Documentation: https://api.wapizap.com/api-docs
• Issues: https://github.com/your-repo/n8n-nodes-wapizap/issues
• WapiZap Support: Contact via https://wapizap.com

🌟 Credits

Created and maintained by the WapiZap team.

Built with ❤️ for the n8n community.

---

Note: This is a community node. It is not officially maintained by n8n GmbH. For official n8n nodes, please visit the n8n documentation.