n8n-nodes-zuckzapgo

This is an n8n community node that provides a complete integration with ZuckZapGo - a multi-user and multi-device REST API for WhatsApp.

ZuckZapGo 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-zuckzapgo
4. Click Install

Manual Installation

npm install n8n-nodes-zuckzapgo

Operations

This package includes 11 specialized nodes, each focused on specific WhatsApp operations:

🔐 ZuckZapGo Credentials

Handles authentication with your ZuckZapGo instance.

📱 ZuckZapGo 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

💬 ZuckZapGo 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

🗨️ ZuckZapGo 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

👤 ZuckZapGo 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

👥 ZuckZapGo 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

🔗 ZuckZapGo Webhook

Configure webhook settings:

• Get - Get current webhook configuration
• Set - Configure webhook URL and events
• Update - Update webhook settings
• Delete - Remove webhook configuration

👨‍💼 ZuckZapGo Admin

Administrative operations (requires admin token):

• List Users - List all ZuckZapGo users
• Create User - Create new user with token
• Delete User - Delete user from database
• Delete User Full - Complete user removal (DB, S3, logout)

🔔 ZuckZapGo 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

⏳ ZuckZapGo 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

🤖 ZuckZapGo 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 ZuckZapGo credentials:

1. API Token - Your ZuckZapGo user token for authentication
2. API URL - The base URL of your ZuckZapGo instance

Credential Validation

The credentials are automatically validated when configured. The validation provides real-time information about your ZuckZapGo 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 ZuckZapGo

1. Install and run ZuckZapGo 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 ZuckZapGo 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 ZuckZapGo Message node
{
  "messageType": "text",
  "phone": "5491155553934",
  "body": "Hello from n8n!"
}

Send an Image with Caption

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

Create a Group

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

Set Up Webhook Trigger

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

Compatibility

• n8n Version: 0.210.0 or higher
• Node.js: 20.15 or higher
• ZuckZapGo: Compatible with all ZuckZapGo 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
• ZuckZapGo Documentation
• ZuckZapGo API Documentation
• WhatsApp Business API

Support

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

License

MIT

Author

Guilherme Jansen - [email protected]

---

Made with ❤️ for the n8n community