n8n-nodes-wuzapi-fork

Maintained fork of n8n-nodes-wuzapi with fixes for recent n8n versions: unified node UI, binary media handling, and local URL media support.

Integration with Wuzapi — a multi-user and multi-device REST API for WhatsApp.

n8n is a fair-code licensed workflow automation platform.

Running n8n in Docker? Mount a persistent volume on /home/node/.n8n before installing. Without it, this node — and every other community node — breaks whenever a container is recreated or the host reboots. See Docker: persistent volume.

What's different in this fork

• Single node in the picker — one Wuzapi node with a Resource dropdown (Message, Chat, Session, Group, User, Webhook, Admin, AI), similar to EvoGo
• Works on recent n8n — no runtime npm dependencies (uses native FormData)
• Binary media fix — uses n8n filesystem-safe binary API (getBinaryDataBuffer)
• Local URL media — downloads media inside n8n before sending (avoids Wuzapi SSRF blocks on docker/internal URLs)
• Backward compatible — existing workflows need a one-time type migration to n8n-nodes-wuzapi-fork.wuzapi

Table of Contents

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

Installation

Three options — pick based on how your n8n runs. See the n8n installation guide for the general background.

Option 1: n8n UI (recommended)

1. In n8n, go to Settings > Community Nodes
2. Click Install
3. Enter n8n-nodes-wuzapi-fork
4. Click Install

The package appears in the Community Nodes list and can be updated or removed from there. Node type is n8n-nodes-wuzapi-fork.wuzapi.

Docker: persistent volume

Packages installed through the UI live in /home/node/.n8n/nodes. On Docker, Swarm and Kubernetes that path is inside the container's own filesystem unless you mount a volume, so it is wiped every time the container is recreated — a redeploy, an image update or a host reboot. n8n then tries to reinstall every package during boot, and that fallback is unreliable: see Troubleshooting for what the failure looks like and why it happens.

Single instance:

services:
  n8n:
    image: n8nio/n8n:latest
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Queue mode (editor + webhook + worker) — give each service its own volume:

services:
  editor:
    image: n8nio/n8n:latest
    command: start
    volumes:
      - n8n_editor_data:/home/node/.n8n

  webhook:
    image: n8nio/n8n:latest
    command: webhook
    volumes:
      - n8n_webhook_data:/home/node/.n8n

  worker:
    image: n8nio/n8n:latest
    command: worker --concurrency=10
    volumes:
      - n8n_worker_data:/home/node/.n8n

volumes:
  n8n_editor_data:
  n8n_webhook_data:
  n8n_worker_data:

One volume per service, not one shared by all three: each instance downloads and loads its own copy of the nodes, so a shared volume makes them write over the same directory at the same time. Splitting them is safe because nothing in .n8n needs to be shared — provided that N8N_ENCRYPTION_KEY is supplied as an environment variable (otherwise each instance would persist a different generated key and credentials would stop decrypting), and that binary data is not in filesystem mode. If you do use N8N_DEFAULT_BINARY_DATA_MODE=filesystem, keep binary data on S3 or on its own shared mount rather than sharing all of .n8n.

On Docker Swarm, local volumes are bound to the node where the task runs, so keep the placement constraints that pin the services to a single node. Avoid more than one replica per service on the same node, since replicas would share one local volume.

A full working Swarm/Portainer stack is in portainer-n8n-stack.example.yml.

To confirm the volumes are in place before relying on them:

# volume mounted on each service
docker service inspect <service> \
  --format '{{range .Spec.TaskTemplate.ContainerSpec.Mounts}}{{.Source}} -> {{.Target}}{{end}}'

# packages actually persisted inside the volume
docker exec <container> cat /home/node/.n8n/nodes/package.json

After a restart, the logs of a healthy setup contain no Attempting to reinstall missing packages line — n8n found everything on disk.

Option 2: mount the built package (~/.n8n/custom)

Nothing is installed at runtime: the node is loaded from disk on every boot. This bypasses the community-package installer completely, so it is immune to the failures described in Troubleshooting, and it lets you pin an exact build.

git clone https://github.com/dersonbsb2022/n8n-nodes-wuzapi-fork.git
cd n8n-nodes-wuzapi-fork
npm install
npm run build

volumes:
  - ./n8n-nodes-wuzapi-fork/dist:/home/node/.n8n/custom/n8n-nodes-wuzapi-fork:ro

n8n scans ~/.n8n/custom recursively for **/*.node.js and **/*.credentials.js, so no environment variable is needed. N8N_CUSTOM_EXTENSIONS=/path/a;/path/b is only for directories outside ~/.n8n/custom. Mount dist rather than the repository root — the scan is recursive and would walk node_modules. In queue mode, mount it into all three services.

Caveat: nodes loaded this way are registered under n8n's reserved CUSTOM package, so the node type becomes CUSTOM.wuzapi, not n8n-nodes-wuzapi-fork.wuzapi. Workflows are not portable between Option 1 and Option 2 without rewriting node types, and the package does not appear in Settings > Community Nodes. Credentials are unaffected: wuzapiApi is registered by plain name and works with either option.

Option 3: npm (self-hosted, without Docker)

cd ~/.n8n/nodes   # create the directory if it does not exist
npm install n8n-nodes-wuzapi-fork

Restart n8n afterwards.

Operations

The Wuzapi node exposes all operations via Resource + Operation dropdowns. Legacy node types remain registered for existing workflows but are hidden from the node picker.

Resources

• Message — text, image, audio, video, document, sticker, location, contact, template, buttons, list, poll
• Chat — delete/edit messages, download media, mark read, reactions, presence
• Session — connect, disconnect, QR code, proxy, S3, etc.
• User — check users, profile, avatar, contacts, presence
• Group — create, join, leave, participants, settings
• Webhook — get/set/update/delete webhook config
• Admin — user management (admin token)
• AI — AI-friendly send operations

Legacy nodes (hidden, compatibility only)

The original package split functionality across 11 nodes. They still work in old workflows:

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

// 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": "[email protected]",
    "chatId": "[email protected]",
    "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": "[email protected]", 
  "sender": "[email protected]",
  "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",
    "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

// 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": "[email protected]"
      }]
    }
  }
}

// Send list for AI-generated menu
{
  "operation": "sendList",
  "phoneNumber": "[email protected]",
  "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": "[email protected]",
  "pollHeader": "Which feature should we prioritize?",
  "pollOptions": "AI Chat Enhancement,Voice Messages,File Sharing,Video Calls"
}

AI Tools Integration Examples

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

Troubleshooting

Node breaks after restarting Docker ("Unrecognized node type", red triangle)

Look for this pattern in the boot logs:

Attempting to reinstall missing packages
Failed to reinstall community package <name>: The specified package could not be loaded
Community package installed: <name>
ENOENT: no such file or directory, lstat '/home/node/.n8n/nodes/<name>-<version>.tgz'
Failed to restore community package after failed installation

This is not specific to this package — it affects every community node in the instance, and the fix is in your n8n deployment, not in the node. The chain is:

1. /home/node/.n8n is not on a persistent volume, so nodes/node_modules comes back empty after every container recreation.
2. Each instance therefore considers all packages missing and reinstalls them at boot (N8N_REINSTALL_MISSING_PACKAGES, enabled by default).
3. n8n downloads each package to a fixed path, ~/.n8n/nodes/<name>-<version>.tgz, extracts it, and removes the tarball in a finally block. In queue mode every successful install is also broadcast over Redis as a community-package-install event, and the instances that receive it install the same package again. Two concurrent installs of one package inside the same container collide on that single tarball path and on the rm -rf/mkdir of the package directory — one of them fails with ENOENT and leaves a half-extracted directory behind.

Fixes, in order of preference: a persistent volume per service, or mounting the built package (Option 2), which never touches the installer at all. Setting N8N_REINSTALL_MISSING_PACKAGES=false does not help on its own — without a volume the nodes simply stay missing after every container recreation.

With the volumes in place, a full host reboot of a three-service Swarm stack produced no reinstall attempts and no errors in any instance: the boot path that causes this never runs, because nothing is missing.

Note that the very first deploy after adding the volumes still performs one reinstall round, since the new volumes start empty. If a package fails during that single transition, reinstall it once from Settings > Community Nodes; from then on it persists.

Behaviour traced in n8n 2.35.7, dist/modules/community-packages/community-packages.service.js (downloadPackage, checkForMissingPackages, and the community-package-install pub/sub handler).

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
• Wuzapi Documentation
• Wuzapi API Documentation
• WhatsApp Business API

Support

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

License

MIT

Credits

• Original package: Guilherme Jansen / n8n-nodes-wuzapi
• Fork maintainer: Anderson Silva

Made with ❤️ for the n8n community