n8n-nodes-wuzapi
Version:
n8n community nodes for Wuzapi - WhatsApp Multi-Device REST API
559 lines (475 loc) • 17.9 kB
Markdown
# n8n-nodes-wuzapi
This is an n8n community node that provides a complete integration with [Wuzapi](https://github.com/asternic/wuzapi) - a multi-user and multi-device REST API for WhatsApp.
Wuzapi implements a robust WhatsApp Web API that allows you to send and receive messages, manage groups, handle media files, and much more through a simple REST interface.
[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
## Table of Contents
- [Installation](#installation)
- [Operations](#operations)
- [Credentials](#credentials)
- [Nodes Overview](#nodes-overview)
- [Usage Examples](#usage-examples)
- [Features](#features)
- [Error Handling](#error-handling)
- [Compatibility](#compatibility)
- [Resources](#resources)
## Installation
Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
### Quick Installation
1. In n8n, go to **Settings** > **Community Nodes**
2. Click **Install a community node**
3. Enter `n8n-nodes-wuzapi`
4. Click **Install**
### Manual Installation
```bash
npm install n8n-nodes-wuzapi
```
## Operations
This package includes 11 specialized nodes, each focused on specific WhatsApp operations:
### 🔐 Wuzapi Credentials
Handles authentication with your Wuzapi instance.
### 📱 Wuzapi Session
- **Connect** - Connect to WhatsApp servers
- **Disconnect** - Disconnect from WhatsApp
- **Get Status** - Check connection status
- **Get QR Code** - Get QR code for scanning
- **Logout** - Logout and terminate session
- **Pair Phone** - Get pairing code for phone
- **Set Proxy** - Configure proxy settings
- **Configure S3** - Set up S3 storage for media
- **Test S3** - Test S3 connection
### 💬 Wuzapi Message
Send various types of messages:
- **Text** - Send text messages
- **Image** - Send images with optional captions
- **Audio** - Send audio messages
- **Video** - Send videos with optional captions
- **Document** - Send documents of any type
- **Sticker** - Send stickers
- **Location** - Send location coordinates
- **Contact** - Send contact cards (vCard)
- **Template** - Send template messages with buttons
- **Buttons** - Send interactive button messages
- **List** - Send list messages
- **Poll** - Send polls to groups
### 🗨️ Wuzapi Chat
Manage chat interactions:
- **Delete Message** - Delete sent messages
- **Edit Message** - Edit previously sent messages
- **Download Media** - Download media from messages
- **Mark as Read** - Mark messages as read
- **React to Message** - Send reactions to messages
- **Set Presence** - Show typing/recording indicators
### 👤 Wuzapi User
User information and presence:
- **Check Users** - Check if users have WhatsApp
- **Get User Info** - Get detailed user information
- **Get Avatar** - Get user profile pictures
- **Get Contacts** - Get all contacts
- **Set Presence** - Set global online/offline status
### 👥 Wuzapi Group
Complete group management:
- **Create** - Create new groups
- **List** - List all groups
- **Get Info** - Get group information
- **Get Invite Link** - Get group invite link
- **Join** - Join group via invite
- **Leave** - Leave a group
- **Set Name** - Change group name
- **Set Description** - Set group description
- **Set Photo** - Set group photo
- **Remove Photo** - Remove group photo
- **Set Announce** - Enable/disable admin-only messages
- **Set Locked** - Lock/unlock group info editing
- **Set Ephemeral** - Configure disappearing messages
- **Update Participants** - Add/remove/promote/demote members
### 🔗 Wuzapi Webhook
Configure webhook settings:
- **Get** - Get current webhook configuration
- **Set** - Configure webhook URL and events
- **Update** - Update webhook settings
- **Delete** - Remove webhook configuration
### 👨💼 Wuzapi Admin
Administrative operations (requires admin token):
- **List Users** - List all Wuzapi users
- **Create User** - Create new user with token
- **Delete User** - Delete user from database
- **Delete User Full** - Complete user removal (DB, S3, logout)
### 🔔 Wuzapi Trigger
Receive real-time WhatsApp events with complete event mapping:
- **Events** - Message, Read Receipt, Presence, History Sync, Chat Presence, All Events
- **Advanced Filters** - Filter by sender phone, chat ID, message type, content, groups/direct, from me/others, token
- **Message Type Detection** - Automatic detection of text, media, PTT, documents, stickers, URLs, locations, contacts, buttons, lists, templates, polls, orders, and unknown types
- **Media Support** - Complete base64 and S3 media data extraction
- **Content Parsing** - Intelligent message content extraction with type-specific fields
- **Simplified Output** - Clean, structured output with all relevant fields mapped
- **Raw Data Access** - Optional complete raw webhook data for debugging
### ⏳ Wuzapi Send and Wait
Send messages and wait for responses:
- **Approval Messages** - Send messages with approval buttons
- **Free Text Response** - Wait for user text input via web form
- **Custom Forms** - Create custom forms for user responses
- **Wait Time Limits** - Set maximum wait times
- **Attribution** - Optional n8n branding
### 🤖 Wuzapi AI
Optimized for AI workflows and tools with complete message type support:
- **Send Text** - Send text messages with AI-friendly interface
- **Send Image** - Send images with captions (Binary/Base64/URL)
- **Send Audio** - Send audio messages with PTT support (Binary/Base64/URL)
- **Send Video** - Send videos with captions (Binary/Base64/URL)
- **Send Document** - Send documents with filenames (Binary/Base64/URL)
- **Send Location** - Send geographical coordinates with location names
- **Send Contact** - Send contact information with VCard data
- **Send Sticker** - Send stickers in WebP format (Binary/Base64/URL)
- **Send Buttons** - Send interactive button messages for AI decision trees
- **Send List** - Send structured lists with multiple options for AI menus
- **Send Poll** - Send group polls for AI-driven surveys and decisions
- **Universal Media Support** - All media types support Binary Data, Base64, and URL sources
- **Mention System** - Complete mention support for specific users and all group members
- **Batch Processing** - Process multiple recipients and message types efficiently
- **Error Tolerance** - Continue workflow execution on individual failures
- **AI Tools Compatible** - Perfect for use with n8n AI Tools and automation
## Credentials
To use these nodes, you need to configure the Wuzapi credentials:
1. **API Token** - Your Wuzapi user token for authentication
2. **API URL** - The base URL of your Wuzapi instance
### Credential Validation
The credentials are automatically validated when configured. The validation provides real-time information about your Wuzapi session:
- **Authentication Status** - Confirms API token validity
- **Session Information** - Shows session name, connection status, and login state
- **Dynamic Messages** - Example: "Connected to setupautomatizado (Connected, Logged In)"
3. **Advanced Options** (Optional):
- **Proxy URL** - HTTP/SOCKS5 proxy for requests
- **Request Timeout** - Timeout in milliseconds
- **Retry on Failure** - Enable automatic retries
- **Max Retries** - Maximum retry attempts
### Setting up Wuzapi
1. Install and run Wuzapi following the [official documentation](https://github.com/asternic/wuzapi)
2. Create a user with an authentication token
3. Use the token and API URL in n8n credentials
## Nodes Overview
### Modular Design
This package follows a modular design where each node focuses on specific functionality:
- **Session Management** - Connection, authentication, and configuration
- **Messaging** - All message sending operations
- **Chat Operations** - Message management and interactions
- **User Operations** - User information and presence
- **Group Management** - Complete group functionality
- **Webhook Configuration** - Event subscription management
- **Administration** - User management (admin only)
- **Event Trigger** - Real-time event reception
- **Send and Wait** - Interactive approval workflows
- **AI Integration** - Optimized node for AI Tools and workflows
### Key Features
- ✅ **Complete API Coverage** - All Wuzapi endpoints implemented across 11 specialized nodes
- 🔄 **Automatic Retry Logic** - Built-in retry mechanism with exponential backoff
- 🛡️ **Robust Error Handling** - Graceful error handling with detailed messages
- 🎯 **Type Safety** - Full TypeScript implementation with comprehensive type checking
- 📦 **Universal Media Support** - Handle all media types with Binary Data, Base64, and URL sources
- 🔐 **Multi-tenant Support** - Each user has independent WhatsApp sessions
- ☁️ **S3 Integration** - Optional cloud storage for media files with automatic delivery
- 🌐 **Proxy Support** - HTTP/SOCKS5 proxy configuration for all operations
- ⚡ **High Performance** - Optimized for production use with efficient media handling
- 🎨 **User-Friendly** - Intuitive interface with helpful descriptions and examples
- 🤖 **Complete AI Integration** - Dedicated AI node with full message type support (11 types)
- 💬 **Interactive Messages** - Full support for buttons, lists, polls, and stickers
- 🎯 **Mention System** - Complete mention support for individuals and group-wide mentions
- 📱 **Media Optimization** - Smart media source detection and URL support for reduced payloads
- ✅ **Enhanced Validation** - Real-time credential validation with session status
- 🔧 **Batch Processing** - Efficient processing of multiple operations with error tolerance
- 🌍 **Multi-format Support** - WebP stickers, VCard contacts, geographic locations
- 📊 **Group Intelligence** - Advanced group management with polls and administrative controls
## Usage Examples
### Send a Text Message
```javascript
// Using Wuzapi Message node
{
"messageType": "text",
"phone": "5491155553934",
"body": "Hello from n8n!"
}
```
### Send an Image with Caption
```javascript
// Using Wuzapi Message node
{
"messageType": "image",
"phone": "5491155553934",
"imageSource": "binary",
"binaryProperty": "data",
"caption": "Check out this image!"
}
```
### Create a Group
```javascript
// Using Wuzapi Group node
{
"operation": "create",
"groupName": "My n8n Group",
"participants": "5491155553934,5491155553935"
}
```
### Set Up Webhook Trigger
```javascript
// Using Wuzapi Trigger node - Basic setup
{
"events": ["Message", "ReadReceipt"],
"filters": {
"messageType": "text",
"isGroup": "false"
}
}
```
### Advanced Trigger Configuration
```javascript
// Complete trigger setup with all features
{
"events": ["Message"],
"filters": {
"fromPhone": "5521971532700@s.whatsapp.net",
"chatId": "120363312246943103@g.us",
"messageType": "media",
"containsText": "urgent",
"isGroup": "true",
"isFromMe": "false",
"tokenFilter": "setupautomatizado"
},
"options": {
"simplifyOutput": true,
"includeMediaData": true,
"parseMessageContent": true,
"includeRawData": false
}
}
```
### Trigger Output Example
```javascript
// Simplified output for a text message
{
"eventType": "Message",
"token": "setupautomatizado",
"messageId": "A6BA5FB09055C47722F936C3FC74D98F",
"chat": "5521971532700@s.whatsapp.net",
"sender": "5521971532700@s.whatsapp.net",
"timestamp": "2025-05-28T06:47:26-03:00",
"messageType": "text",
"isFromMe": false,
"isGroup": false,
"pushName": "Guilherme Jansen",
"verifiedName": "Guilherme Jansen - Setup Automatizado",
"text": "Oi"
}
```
### Media Message Output
```javascript
// Output for audio message with S3 and base64 data
{
"eventType": "Message",
"messageType": "ptt",
"audioUrl": "https://mmg.whatsapp.net/v/...",
"duration": 3,
"mimeType": "audio/ogg; codecs=opus",
"mediaBase64": "T2dnUwACAAAAAAAA...",
"mediaMimeType": "application/ogg",
"mediaFileName": "DB56752B6A203E5A96A2E533C4D0A7CF.oga",
"s3Data": {
"bucket": "evolution",
"key": "users/2fb8378b312c1d2dd127e094d9a99115/inbox/...",
"url": "https://s3.setupautomatizado.com.br/evolution/...",
"size": 8084
}
}
```
### Interactive Message Output
```javascript
// Output for buttons message
{
"eventType": "Message",
"messageType": "buttons",
"text": "ESCOLHA O MENU!",
"buttons": [
{
"id": "81ad952f-1085-4d2c-a4b9-de228cfc4117",
"text": "SUPORTE",
"type": 1
},
{
"id": "a4767ccb-ded6-4edd-be6a-363972fdaa0f",
"text": "COMERCIAL",
"type": 1
},
{
"id": "8f72fd66-1e6f-48bd-a5b5-c509fcc5a9f1",
"text": "ATENDIMENTO",
"type": 1
}
]
}
// Output for list message
{
"eventType": "Message",
"messageType": "list",
"title": "<HEADER_TEXT>",
"text": "<BODY_TEXT>",
"buttonText": "<BUTTON_TEXT>",
"sections": [
{
"title": "<LIST_SECTION_1_TITLE>",
"rows": [
{
"id": "<LIST_SECTION_1_ROW_1_ID>",
"title": "<SECTION_1_ROW_1_TITLE>",
"description": "<SECTION_1_ROW_1_DESC>"
}
]
}
]
}
```
### Send AI-Generated Message
```javascript
// Using Wuzapi AI node - Perfect for AI workflows
{
"operation": "sendText",
"phoneNumber": "5491155553934",
"message": "Hello! This is an AI-generated response from n8n."
}
```
### Send Multiple Media Files (AI Batch)
```javascript
// Using Wuzapi AI node with multiple items
[
{
"operation": "sendImage",
"phoneNumber": "5491155553934",
"imageSource": "url",
"imageUrl": "https://example.com/image1.jpg",
"caption": "AI Analysis Result 1"
},
{
"operation": "sendDocument",
"phoneNumber": "5491155553935",
"documentSource": "url",
"documentUrl": "https://example.com/report.pdf",
"fileName": "AI_Report.pdf",
"caption": "Generated Report"
}
]
```
### Send Interactive Messages with AI
```javascript
// Send sticker for reactions
{
"operation": "sendSticker",
"phoneNumber": "5491155553934",
"stickerSource": "url",
"stickerUrl": "https://example.com/thumbs-up.webp"
}
// Send buttons for AI decision tree
{
"operation": "sendButtons",
"phoneNumber": "5491155553934",
"message": "How can I help you today?",
"additionalOptions": {
"mentions": {
"mentionConfig": [{
"type": "specific",
"jids": "5491155553934@s.whatsapp.net"
}]
}
}
}
// Send list for AI-generated menu
{
"operation": "sendList",
"phoneNumber": "120363312246943103@g.us",
"buttonText": "Choose Service",
"description": "Select the service you need",
"topText": "AI Assistant Services",
"footerText": "Powered by AI",
"listItems": {
"item": [
{
"title": "Technical Support",
"desc": "Get help with technical issues",
"rowId": "tech_support"
},
{
"title": "Sales Information",
"desc": "Learn about our products",
"rowId": "sales_info"
},
{
"title": "General Questions",
"desc": "Ask any general questions",
"rowId": "general_qa"
}
]
}
}
// Send poll for group decisions
{
"operation": "sendPoll",
"phoneNumber": "120363312246943103@g.us",
"pollHeader": "Which feature should we prioritize?",
"pollOptions": "AI Chat Enhancement,Voice Messages,File Sharing,Video Calls"
}
```
### AI Tools Integration Examples
```javascript
// Complete AI workflow with mentions and media
{
"operation": "sendVideo",
"phoneNumber": "5491155553934",
"videoSource": "base64",
"videoBase64": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc...",
"caption": "Here's your AI-generated tutorial video",
"additionalOptions": {
"id": "ai_tutorial_001",
"mentions": {
"mentionConfig": [{
"type": "all"
}]
}
}
}
// AI processing with binary data from previous nodes
{
"operation": "sendDocument",
"phoneNumber": "5491155553934",
"documentSource": "binary",
"documentBinaryProperty": "processed_report",
"fileName": "AI_Analysis_Report.pdf",
"caption": "Your personalized AI analysis is ready!"
}
```
## Error Handling
All nodes include comprehensive error handling:
- **Automatic Retries** - Failed requests are retried with exponential backoff
- **Continue on Fail** - Option to continue workflow execution on errors
- **Detailed Error Messages** - Clear error descriptions for debugging
- **HTTP Status Codes** - Proper status code handling
- **Authentication Errors** - No retry on authentication failures
## Compatibility
- **n8n Version**: 0.210.0 or higher
- **Node.js**: 20.15 or higher
- **Wuzapi**: Compatible with all Wuzapi versions
- **WhatsApp**: Supports all current WhatsApp message types including interactive content
- **Media Formats**:
- Images: JPEG, PNG, WebP
- Videos: MP4, AVI, MOV (H.264 codec recommended)
- Audio: OGG (Opus), MP3, WAV, AAC
- Documents: PDF, DOCX, XLSX, TXT, and all file types
- Stickers: WebP format (recommended), PNG with transparency
## Resources
- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
- [Wuzapi Documentation](https://github.com/asternic/wuzapi)
- [Wuzapi API Documentation](https://github.com/asternic/wuzapi/blob/main/API.md)
- [WhatsApp Business API](https://developers.facebook.com/docs/whatsapp)
## Support
For issues and feature requests, please use the [GitHub issues page](https://github.com/guilhermejansen/n8n-nodes-wuzapi/issues).
## License
[MIT](https://github.com/guilhermejansen/n8n-nodes-wuzapi/blob/master/LICENSE.md)
## Author
Guilherme Jansen - [guilherme@setupautomatizado.com.br](mailto:guilherme@setupautomatizado.com.br)
---
Made with ❤️ for the n8n community