# 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