n8n-nodes-wuzapi

This is an n8n community node that provides a complete integration with 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 is a fair-code licensed workflow automation platform.

Table of Contents

• Installation
• Operations
• Credentials
• Nodes Overview
• Usage Examples
• Features
• Error Handling
• Compatibility
• Resources

Installation

Follow the installation guide 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

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:

• Send Text - Send text messages with AI-friendly interface
• Send Image - Send images with captions
• Send Document - Send documents with optional captions
• Send Audio - Send audio messages
• Send Video - Send videos with captions
• Send Location - Send geographical locations
• Send Contact - Send contact information
• Batch Processing - Process multiple recipients efficiently
• Error Tolerance - Continue on individual failures
• AI Tools Compatible - Perfect for use with n8n AI Tools

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
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
• 🔄 Automatic Retry Logic - Built-in retry mechanism with exponential backoff
• 🛡️ Robust Error Handling - Graceful error handling with detailed messages
• 🎯 Type Safety - Full TypeScript implementation
• 📦 Binary Data Support - Handle images, videos, documents seamlessly
• 🔐 Multi-tenant Support - Each user has independent WhatsApp sessions
• ☁️ S3 Integration - Optional cloud storage for media files
• 🌐 Proxy Support - HTTP/SOCKS5 proxy configuration
• ⚡ High Performance - Optimized for production use
• 🎨 User-Friendly - Intuitive interface with helpful descriptions
• 🤖 AI-Ready - Dedicated AI node for seamless AI workflow integration
• ✅ Enhanced Validation - Real-time credential validation with session status

Usage Examples

Send a Text Message

// Using Wuzapi Message node
{
  "messageType": "text",
  "phone": "5491155553934",
  "body": "Hello from n8n!"
}

Send an Image with Caption

// Using Wuzapi Message node
{
  "messageType": "image",
  "phone": "5491155553934",
  "imageSource": "binary",
  "binaryProperty": "data",
  "caption": "Check out this image!"
}

Create a Group

// Using Wuzapi Group node
{
  "operation": "create",
  "groupName": "My n8n Group",
  "participants": "5491155553934,5491155553935"
}

Set Up Webhook Trigger

// Using Wuzapi Trigger node - Basic setup
{
  "events": ["Message", "ReadReceipt"],
  "filters": {
    "messageType": "text",
    "isGroup": "false"
  }
}

Advanced Trigger Configuration

// 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

// 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

// 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

// 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

// 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)

// Using Wuzapi AI node with multiple items
[
  {
    "operation": "sendImage",
    "phoneNumber": "5491155553934",
    "mediaUrl": "https://example.com/image1.jpg",
    "caption": "AI Analysis Result 1"
  },
  {
    "operation": "sendDocument",
    "phoneNumber": "5491155553935", 
    "mediaUrl": "https://example.com/report.pdf",
    "caption": "Generated Report"
  }
]

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

Resources

• n8n Community Nodes Documentation
• Wuzapi Documentation
• Wuzapi API Documentation
• WhatsApp Business API

Support

For issues and feature requests, please use the GitHub issues page.

License

MIT

Author

Guilherme Jansen - guilherme@setupautomatizado.com.br

---

Made with ❤️ for the n8n community