ZuckZapGo - Complete WhatsApp API Documentation

📋 API Overview

ZuckZapGo is a powerful WhatsApp Business API that allows you to integrate WhatsApp messaging capabilities into your applications. Built with Go and designed for high performance and scalability.

✨ Key Features:

📱 Full WhatsApp Business API integration
🔐 Secure authentication with tokens
📨 Send text, images, audio, video, documents
👥 Group management and operations
🔗 Webhook support for real-time events
☁️ S3 storage integration
🐰 RabbitMQ message queuing
⚡ Smart event filtering (groups, newsletters, broadcasts)
🐳 Docker deployment ready

🚀 Advanced Integrations:

🔧 n8n Community Node: 10 nodes specialized for visual automation
💬 Chatwoot Gateway: Bidirectional integration with multi-tenant CRM
🤖 Bot Commands: Control WhatsApp via chat commands
⚡ Send & Wait: Interactive workflows with approval
🎯 AI Optimized: Nodes optimized for AI tools
📊 Monitoring: Health checks and real-time metrics

🌐 Base URL

https://api.your-domain.com

📊 API Endpoints Overview

Category	Description	Endpoints
Session Management	Connect, disconnect, and manage WhatsApp sessions	7 endpoints
Messaging	Send messages, media, and interactive content	15 endpoints
Groups	Create, manage, and operate WhatsApp groups	14 endpoints
User Management	Check users, get info, manage contacts, LID conversion	11 endpoints
Administration	User management and system administration	8 endpoints
Advanced Configuration	RabbitMQ, S3, proxy, skip filters, and advanced features	12+ endpoints
Newsletter/Channels	WhatsApp newsletters and channel management	15+ endpoints
Status Management	Send text, image, and video status to WhatsApp	3 endpoints
System Health	Health checks and system monitoring	1 endpoint
Global Admin	System-wide administration and monitoring	5 endpoints

🔐 Authentication

ZuckZapGo uses token-based authentication with two types of tokens for different access levels.

🚨 Security Notice: Keep your tokens secure and never expose them in client-side code. Always use HTTPS in production.

🎫 Token Types

1. User Token

Purpose: Access user-specific endpoints for messaging and session management

Usage: Include in Authorization header for all regular API calls

token: your_user_token_here

2. Admin Token

Purpose: Access administrative endpoints for user management

Usage: Required for all /admin/** endpoints

Configuration: Set via ZUCKZAPGO_ADMIN_TOKEN environment variable

Authorization: your_admin_token_here

📨 Request Format

All API requests must include:

Content-Type: application/json
Authorization: Bearer token or direct token value

curl -X POST \
  https://api.your-domain.com/chat/send/text \
  -H 'Content-Type: application/json' \
  -H 'token: your_user_token' \
  -d '{
    "Phone": "5511999887766",
    "Body": "Hello from ZuckZapGo!"
  }'

📱 Session Management

Manage WhatsApp connections, QR codes, and session status. These endpoints control the core WhatsApp connection lifecycle.

POST /session/connect

Purpose: Establish a WhatsApp connection for the user

📝 Request Body:

{
  "Subscribe": ["Message", "ReadReceipt", "Presence"],
  "Immediate": true
}

📋 Parameters:

Field	Type	Required	Description
Subscribe	array	No	Event types to subscribe to
Immediate	boolean	No	Connect immediately without waiting

✅ Success Response:

{
  "code": 200,
  "data": {
    "qrcode": "base64_qr_code_image",
    "status": "connecting"
  },
  "success": true
}

GET /session/qr

Purpose: Get QR code for WhatsApp pairing

✅ Success Response:

{
  "code": 200,
  "data": {
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "status": "qr_ready"
  },
  "success": true
}

💡 Pro Tip: The QR code is returned as a base64 data URL, ready to display in an <img> tag.

GET /session/status

Purpose: Check current session connection status

✅ Success Response:

{
  "code": 200,
  "data": {
    "connected": true,
    "loggedIn": true,
    "info": {
      "jid": "[email protected]",
      "name": "User Name"
    }
  },
  "success": true
}

📊 Status Values:

Status	Description
disconnected	Not connected to WhatsApp
connecting	Attempting to connect
qr_ready	QR code ready for scanning
connected	Successfully connected and ready

POST /session/pairphone

Purpose: Pair WhatsApp using phone number (alternative to QR)

📝 Request Body:

{
  "Phone": "5511999887766"
}

📱 Phone Format: Use international format without + sign (e.g., 5511999887766 for Brazil)

POST /session/disconnect

Purpose: Disconnect from WhatsApp without logging out

✅ Success Response:

{
  "code": 200,
  "data": "disconnected",
  "success": true
}

POST /session/logout

Purpose: Completely logout from WhatsApp (requires new QR scan)

✅ Success Response:

{
  "code": 200,
  "data": "logged out",
  "success": true
}

⚠️ Warning: After logout, you'll need to scan QR code again to reconnect.

💬 Messaging

Send various types of messages including text, media, interactive content, and more. All messaging endpoints support mentions and context information.

POST /chat/send/text

Purpose: Send text messages to individual users or groups with advanced features

🆕 New Features:

Link Preview: Automatic URL preview generation
Custom Duration: Message expiration time in seconds
Format Compatibility: Both snake_case and PascalCase supported

📝 Request Body:

{
  "Phone": "5511999887766",
  "Body": "Hello! Check this link: https://github.com 🚀",
  "Id": "custom_message_id_123",
  "presence": 3000,
  "link_preview": true,
  "duration": 86400,
  "ContextInfo": {
    "StanzaId": "original_message_id",
    "Participant": "[email protected]"
  },
  "mention_info": {
    "mention_all": false,
    "mentions": ["[email protected]"]
  }
}

📋 Parameters:

Field	Type	Required	Description
Phone	string	Yes	Recipient's phone number (international format). Accepts both 'phone' and 'Phone'
Body	string	Yes	Message text content. Include URLs for automatic link preview. Accepts both 'body' and 'Body'
Id	string	No	Custom message ID for tracking. Accepts both 'id' and 'Id'
presence	integer	No	Milliseconds to simulate typing indicator. Accepts both 'presence' and 'Presence'
link_preview	boolean	No	Enable automatic link preview for URLs in message. Accepts both 'link_preview' and 'LinkPreview'
duration	integer	No	Message expiration time in seconds (default: 86400). Accepts both 'duration' and 'Duration'
ContextInfo	object	No	Reply context information
mention_info	object	No	Mention configuration

POST /chat/send/image

Purpose: Send images with optional captions and mentions

📝 Request Body:

{
  "Phone": "5511999887766",
  "Image": "https://example.com/image.jpg",
  "Caption": "Check out this amazing image! 📸",
  "Id": "img_message_123",
  "MimeType": "image/jpeg",
  "Presence": 3000,
  "ViewOnce": true,
  "Duration": 86400,
  "mention_info": {
    "mentions": ["[email protected]"]
  }
}

🖼️ Image Input: Supports both URLs and base64 data URLs (data:image/jpeg;base64,...)

📋 Supported Formats:

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
GIF (.gif)

POST /chat/send/audio

Purpose: Send audio files or voice notes

📝 Request Body:

{
  "Phone": "5511999887766",
  "Audio": "https://example.com/audio.mp3",
  "Caption": "Listen to this audio message 🎵",
  "PTT": true,
  "Presence": 3000,
  "ViewOnce": true,
  "Duration": 86400,
  "Id": "audio_message_123"
}

📋 Parameters:

Field	Type	Description
PTT	boolean	true = voice note, false = audio file
Audio	string	URL or base64 data URL

🎵 Supported Formats:

MP3 (.mp3)
OGG (.ogg)
WAV (.wav)
M4A (.m4a)
AAC (.aac)

POST /chat/send/document

Purpose: Send documents of various formats

📝 Request Body:

{
  "Phone": "5511999887766",
  "Document": "https://example.com/document.pdf",
  "FileName": "important_document.pdf",
  "Caption": "Please review this document 📄",
  "MimeType": "application/pdf",
  "Presence": 3000,
  "Duration": 86400,
  "Id": "doc_message_123"
}

📄 Supported Document Types:

PDF (.pdf)
Word (.doc, .docx)
Excel (.xls, .xlsx)
PowerPoint (.ppt, .pptx)
Text files (.txt)
ZIP archives (.zip)

POST /chat/send/video

Purpose: Send video files with thumbnails

📝 Request Body:

{
  "Phone": "5511999887766",
  "Video": "https://example.com/video.mp4",
  "Caption": "Check out this video! 🎬",
  "JPEGThumbnail": "base64_thumbnail_data",
  "MimeType": "video/mp4",
  "Presence": 3000,
  "ViewOnce": true,
  "Duration": 86400,
  "Id": "video_message_123"
}

🎬 Supported Video Formats:

MP4 (.mp4)
AVI (.avi)
MOV (.mov)
MKV (.mkv)
WebM (.webm)

POST /chat/send/buttons

Purpose: Send interactive button messages

📝 Request Body:

{
  "Phone": "5511999887766",
  "Title": "Choose an option:",
  "Buttons": [
    {
      "ButtonId": "option_1",
      "ButtonText": "Option 1"
    },
    {
      "ButtonId": "option_2", 
      "ButtonText": "Option 2"
    }
  ],
  "Id": "button_message_123"
}

📱 Interactive Messages: Button responses will be sent to your webhook as interactive events.

POST /chat/send/list

Purpose: Send interactive list messages

📝 Request Body:

{
  "Phone": "5511999887766",
  "ButtonText": "Select Option",
  "TopText": "Please choose from the options below:",
  "FooterText": "Powered by ZuckZapGo",
  "Sections": [
    {
      "title": "Main Options",
      "rows": [
        {
          "title": "Option 1",
          "desc": "Description for option 1",
          "RowId": "row_1"
        },
        {
          "title": "Option 2", 
          "desc": "Description for option 2",
          "RowId": "row_2"
        }
      ]
    }
  ],
  "Id": "list_message_123"
}

POST /chat/send/poll

Purpose: Send polls to groups

📝 Request Body:

{
  "group": "[email protected]",
  "header": "What's your favorite programming language?",
  "options": [
    "JavaScript",
    "Python", 
    "Go",
    "Java",
    "Other"
  ],
  "Id": "poll_message_123"
}

👥 Group Only: Polls can only be sent to WhatsApp groups, not individual chats.

POST /chat/send/text/mention

Purpose: Send text messages with specific user mentions

📝 Request Body:

{
  "to": "[email protected]",
  "text": "Hello @5511999887766! How are you?",
  "mentions": ["[email protected]"],
  "id": "mention_message_123"
}

POST /chat/send/text/mention-all

Purpose: Send messages mentioning all group members

📝 Request Body:

{
  "group_id": "[email protected]",
  "text": "Important announcement for everyone! @everyone",
  "id": "mention_all_123"
}

👥 Group Admin Required: You must be a group admin to mention all members.

🔧 Message Operations

POST /chat/delete

Purpose: Delete sent messages

📝 Request Body:

{
  "Phone": "5511999887766",
  "Id": "message_id_to_delete"
}

⏰ Time Limit: Messages can only be deleted within 7 minutes of sending.

POST /chat/send/edit

Purpose: Edit sent text messages

📝 Request Body:

{
  "Phone": "5511999887766",
  "Body": "This is the corrected message text",
  "Id": "original_message_id"
}

⏰ Time Limit: Messages can only be edited within 15 minutes of sending.

POST /chat/react

Purpose: Add emoji reactions to messages

📝 Request Body:

{
  "Phone": "5511999887766",
  "Body": "👍",
  "Id": "message_id_to_react_to"
}

😀 Supported Reactions:

Any emoji: 👍 ❤️ 😂 😮 😢 🙏 👏 🔥 💯 ⚡

👥 Group Management

Complete WhatsApp group management including creation, member management, settings, and more.

POST /group/create

Purpose: Create a new WhatsApp group

📝 Request Body:

{
  "name": "My Awesome Group",
  "participants": [
    "5511999887766",
    "5511888776655",
    "5511777665544"
  ]
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "groupId": "[email protected]",
    "name": "My Awesome Group",
    "participants": ["[email protected]", ...]
  },
  "success": true
}

GET /group/list?ignoreParticipants=true

Purpose: Get list of all groups the user is part of

✅ Success Response:

{
  "code": 200,
  "data": {
    "Groups": [
      {
        "JID": "[email protected]",
        "Name": "My Awesome Group",
        "Topic": "Group topic here",
        "IsAnnounce": false,
        "IsLocked": false,
        "IsEphemeral": false,
        "CreationTime": 1640995200,
        "ParticipantVersionId": "12345",
        "Size": 3,
        "Participants": [...]
      }
    ]
  },
  "success": true
}

GET /group/[email protected]

Purpose: Get detailed information about a specific group

📋 Query Parameters:

Parameter	Type	Required	Description
GroupJID	string	Yes	Group JID (e.g., [email protected])

POST /group/updateparticipants

Purpose: Add, remove, promote, or demote group participants

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Phone": ["5511999887766", "5511888776655"],
  "Action": "add"
}

🔧 Available Actions:

Action	Description	Admin Required
add	Add new participants to group	Yes
remove	Remove participants from group	Yes
promote	Promote participants to admin	Yes
demote	Demote admins to regular participants	Yes

POST /group/name

Purpose: Change group name

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Name": "New Group Name"
}

POST /group/topic

Purpose: Set or update group description

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Topic": "This is the new group description"
}

POST /group/photo

Purpose: Set group profile photo

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Image": "https://example.com/group-photo.jpg"
}

🖼️ Image Format: Supports URLs and base64 data URLs. Image will be automatically resized for group profile.

⚙️ Group Settings

POST /group/announce

Purpose: Enable/disable group announcement mode (only admins can send messages)

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Announce": true
}

POST /group/locked

Purpose: Lock/unlock group settings (only admins can change group info)

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Locked": true
}

POST /group/ephemeral

Purpose: Set disappearing messages timer

📝 Request Body:

{
  "GroupJID": "[email protected]",
  "Duration": "24h"
}

⏰ Available Durations:

off - Disable disappearing messages
24h - 24 hours
7d - 7 days
90d - 90 days

🔗 Invite Management

GET /group/invitelink

Purpose: Get or reset group invite link

📋 Query Parameters:

Parameter	Type	Description
GroupJID	string	Group JID
Reset	boolean	Reset link (create new)

✅ Success Response:

{
  "code": 200,
  "data": {
    "inviteLink": "https://chat.whatsapp.com/ABC123DEF456"
  },
  "success": true
}

POST /group/join

Purpose: Join group using invite code

📝 Request Body:

{
  "Code": "ABC123DEF456"
}

🔗 Invite Code: Extract from invite link: https://chat.whatsapp.com/ABC123DEF456

POST /group/leave

Purpose: Leave a group

📝 Request Body:

{
  "GroupJID": "[email protected]"
}

⚠️ Warning: If you're the only admin, you cannot leave the group unless you promote another member first.

📢 WhatsApp Newsletters & Channels

Comprehensive newsletter and channel management for WhatsApp. Create, manage, and interact with WhatsApp newsletters (channels) to broadcast content to subscribers. Perfect for content creators, businesses, and community managers.

🎯 Newsletter Features: Create newsletters, send multimedia content, manage subscriptions, track engagement, and build communities with WhatsApp's powerful broadcasting capabilities.

📋 Newsletter Management

GET /newsletter/list

Purpose: Get complete list of subscribed newsletters with metadata

✅ Success Response:

{
  "code": 200,
  "data": [
    {
      "jid": "120363312246943103@newsletter",
      "name": "Tech News Daily",
      "description": "Latest technology news and updates",
      "subscriber_count": 1250,
      "created_at": "2024-01-15T10:30:00Z",
      "muted": false,
      "verified": true
    }
  ],
  "success": true
}

POST /newsletter/create

Purpose: Create a new WhatsApp newsletter/channel with optional picture

📝 Request Body:

{
  "name": "My Tech Newsletter",
  "description": "Latest technology news and updates",
  "picture": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "jid": "120363312246943103@newsletter",
    "name": "My Tech Newsletter",
    "description": "Latest technology news and updates",
    "invite_code": "AbCdEfGhIjKlMnOp",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Required	Description
name	string	Yes	Newsletter name (max 25 characters, auto-truncated)
description	string	No	Newsletter description
picture	string	No	Base64 data URL or HTTP(S) URL for newsletter picture

GET /newsletter/info/{newsletter_jid}

Purpose: Get detailed information about a specific newsletter by JID

🔄 Path Parameters:

Parameter	Description
{newsletter_jid}	Newsletter JID (e.g., 120363312246943103@newsletter)

✅ Success Response:

{
  "code": 200,
  "data": {
    "jid": "120363312246943103@newsletter",
    "name": "Tech News Daily",
    "description": "Latest technology news and updates",
    "subscriber_count": 1250,
    "admin_count": 3,
    "created_at": "2024-01-15T10:30:00Z",
    "verified": true,
    "muted": false,
    "picture_url": "https://..."
  },
  "success": true
}

💬 Newsletter Messaging

POST /newsletter/send

Purpose: Send messages to newsletter subscribers (supports text, images, videos, documents, audio)

📝 Text Message Request:

{
  "jid": "120363312246943103@newsletter",
  "message": "Hello subscribers! 📢 This is a test message from our newsletter."
}

📝 Image Message Request:

{
  "jid": "120363312246943103@newsletter",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "caption": "Check out this amazing image! 📸"
}

📝 Video Message Request:

{
  "jid": "120363312246943103@newsletter",
  "video": "https://sample-videos.com/zip/10/mp4/SampleVideo_1280x720_1mb.mp4",
  "caption": "Sample video from URL! 🎥"
}

📝 Document Message Request:

{
  "jid": "120363312246943103@newsletter",
  "document": "data:application/pdf;base64,JVBERi0xLjQKJcfsj6IAAQ...",
  "filename": "newsletter-guide.pdf"
}

📝 Audio Message Request:

{
  "jid": "120363312246943103@newsletter",
  "audio": "data:audio/ogg;base64,T2dnUwACAAAAAAAAAAA="
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "message_id": "3EB06F9067F80BAB89FF",
    "server_id": 12345,
    "timestamp": "2024-01-15T10:30:00Z",
    "status": "sent"
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Description
jid	string	Newsletter JID (required)
message	string	Text message content
image	string	Base64 data URL or HTTP(S) URL for image
video	string	Base64 data URL or HTTP(S) URL for video
document	string	Base64 data URL or HTTP(S) URL for document
audio	string	Base64 data URL or HTTP(S) URL for audio (sent as voice note)
caption	string	Caption for media messages
filename	string	Filename for document messages

🔔 Newsletter Subscription

POST /newsletter/follow/{newsletter_jid}

Purpose: Subscribe to a newsletter using its JID

🔄 Path Parameters:

Parameter	Description
{newsletter_jid}	Newsletter JID to subscribe to

POST /newsletter/follow-invite/{invite_code}

Purpose: Subscribe to a newsletter using an invite code

🔄 Path Parameters:

Parameter	Description
{invite_code}	Newsletter invite code

POST /newsletter/unfollow/{newsletter_jid}

Purpose: Unsubscribe from a newsletter using its JID

🎯 Newsletter Interactions

POST /newsletter/mute

Purpose: Mute or unmute newsletter notifications

📝 Request Body:

{
  "jid": "120363312246943103@newsletter",
  "mute": true
}

📋 Parameters:

Parameter	Type	Description
jid	string	Newsletter JID
mute	boolean	true to mute, false to unmute

GET /newsletter/messages/{newsletter_jid}

Purpose: Retrieve messages from a newsletter with pagination support

🔄 Query Parameters:

Parameter	Type	Description
count	integer	Number of messages to retrieve (default: 25)
before	integer	Server ID to get messages before this ID (pagination)

✅ Success Response:

{
  "code": 200,
  "data": {
    "messages": [
      {
        "server_id": 12345,
        "message_id": "3EB06F9067F80BAB89FF",
        "content": "Hello subscribers!",
        "timestamp": "2024-01-15T10:30:00Z",
        "type": "text",
        "reactions": {
          "👍": 25,
          "❤️": 18
        }
      }
    ],
    "has_more": true,
    "next_before": 12344
  },
  "success": true
}

POST /newsletter/reaction

Purpose: Send an emoji reaction to a specific newsletter message

📝 Request Body:

{
  "jid": "120363312246943103@newsletter",
  "server_id": 12345,
  "reaction": "👍"
}

📋 Parameters:

Parameter	Type	Description
jid	string	Newsletter JID
server_id	integer	Server ID of the message to react to
reaction	string	Emoji reaction (empty string to remove reaction)

POST /newsletter/mark-viewed

Purpose: Mark specific newsletter messages as viewed to update read status

📝 Request Body:

{
  "jid": "120363312246943103@newsletter",
  "server_ids": [12345, 12346, 12347]
}

📋 Parameters:

Parameter	Type	Description
jid	string	Newsletter JID
server_ids	array	Array of server IDs to mark as viewed

🚀 Advanced Features

POST /newsletter/subscribe-live-updates

Purpose: Subscribe to real-time updates for a newsletter (30 second timeout)

📝 Request Body:

{
  "jid": "120363312246943103@newsletter"
}

POST /newsletter/accept-tos

Purpose: Accept WhatsApp Terms of Service notice required for newsletter creation

📝 Request Body (Optional):

{
  "notice_id": "20601218",
  "stage": "5"
}

💡 Note: If no parameters are provided, default values (notice_id: 20601218, stage: 5) will be used.

👑 Admin Features

POST /newsletter/admin-invite

Purpose: Send an admin invitation to manage a newsletter

📝 Request Body:

{
  "phone": "5491155553934",
  "newsletter_jid": "120363312246943103@newsletter",
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "caption": "You're invited to be an admin of our Tech Newsletter! 🚀",
  "name": "Tech Newsletter Admin Invite"
}

📋 Parameters:

Parameter	Type	Required	Description
phone	string	Yes	Phone number to invite as admin
newsletter_jid	string	Yes	Newsletter JID
image	string	No	Base64 data URL or HTTP(S) URL for invitation image
caption	string	No	Invitation message caption
name	string	No	Invitation name/title

💡 Best Practices

✅ Recommended Practices:

Content Strategy: Plan your content calendar and maintain consistent posting schedule
Engagement: Use reactions and interactive content to boost subscriber engagement
Media Optimization: Optimize images and videos for mobile viewing
Subscriber Management: Monitor subscriber growth and engagement metrics
Terms Compliance: Accept ToS before creating newsletters to avoid issues

⚠️ Important Considerations:

Newsletter names are automatically truncated to 25 characters
Audio messages are automatically sent as voice notes (PTT=true)
Pagination is available for message retrieval using server IDs
Live updates have a 30-second timeout for real-time subscriptions
Admin invitations require proper permissions and valid newsletter JID

🔔 Webhooks & Events

Configure webhooks and RabbitMQ to receive real-time notifications about WhatsApp events. ZuckZapGo supports 47 different event types organized into categories.

📡 Real-time Integration: Choose between webhooks (HTTP POST) or RabbitMQ (AMQP messaging) to receive events in real-time.

🔗 Webhook Configuration

POST /webhook

Purpose: Configure webhook URL and subscribe to events

📝 Request Body:

{
  "webhook": "https://example.com/webhook",
  "events": [
    "Message",
    "ReadReceipt", 
    "Connected",
    "Disconnected",
    "GroupInfo"
  ]
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "webhook": "https://example.com/webhook",
    "events": ["Message", "ReadReceipt", "Connected", "Disconnected", "GroupInfo"]
  },
  "success": true
}

GET /webhook

Purpose: Get current webhook configuration

✅ Success Response:

{
  "code": 200,
  "data": {
    "webhook": "https://example.com/webhook",
    "events": ["Message", "ReadReceipt", "Connected"]
  },
  "success": true
}

DELETE /webhook

Purpose: Remove webhook configuration

✅ Success Response:

{
  "code": 200,
  "data": "Webhook deleted successfully",
  "success": true
}

🐰 RabbitMQ Configuration

🚀 Advanced RabbitMQ System

ZuckZapGo implements a dual-layer RabbitMQ system:

Global RabbitMQ: High-performance system for all events with connection pooling and circuit breaker
Individual RabbitMQ: User-specific configurations with dynamic queues per event type
Auto-Recovery: Both systems feature automatic reconnection and health monitoring
Dynamic Queues: Use placeholders {user_id} and {event_type} for automatic queue creation

POST /session/rabbitmq/config

Purpose: Configure RabbitMQ for event publishing with dynamic queues and automatic recovery

📝 Request Body - Dynamic Queues Configuration:

{
  "enabled": true,
  "url": "amqp://user:pass@rabbitmq:5672/",
  "exchange": "whatsapp_events",
  "exchange_type": "topic",
  "queue": "user_{user_id}_event_{event_type}",
  "queue_type": "classic",
  "routing_key": "whatsapp.{user_id}.{event_type}",
  "events": "All",
  "durable": true,
  "auto_delete": false,
  "exclusive": false,
  "no_wait": false,
  "delivery_mode": 2
}

🎯 Dynamic Queues per Event

Static Pattern: "queue": "user_{user_id}_main" → One queue for all events
Dynamic Pattern: "queue": "user_{user_id}_event_{event_type}" → Event-specific queues
Automatically Generated Examples:
- user_abc123_event_Message - Only messages
- user_abc123_event_Receipt - Only read receipts
- user_abc123_event_ChatPresence - Only chat presence
- user_abc123_event_CallOffer - Only call offers
Benefits: Native event filtering, parallel processing, scalability

⚡ Auto-Recovery System

Continuous Health Check: Monitors connections every 30 seconds
Automatic Reconnection: Reconnects automatically in case of failure
Circuit Breaker: Prevents overload during connectivity issues
Connection Pool: Multiple connections for high performance (50 connections by default)
Smart Retry: Retry with exponential backoff on temporary failures
Queue Cache: Avoids unnecessary recreation of existing queues

📋 Advanced Configuration:

Field	Type	Description	Options
exchange_type	string	RabbitMQ exchange type	topic, direct, fanout, headers
queue	string	Queue pattern with placeholders {user_id} and {event_type}	user_{user_id}_event_{event_type}
queue_type	string	RabbitMQ queue type	classic, quorum, stream
routing_key	string	Routing key pattern with placeholders	whatsapp.{user_id}.{event_type}
delivery_mode	integer	Message persistence	1 (non-persistent), 2 (persistent)
durable	boolean	Exchange/queue survives broker restart	true, false
auto_delete	boolean	Auto-delete when unused	true, false
exclusive	boolean	Queue is exclusive to connection	true, false
no_wait	boolean	Don't wait for server response	true, false

GET /session/rabbitmq/config

Purpose: Get current RabbitMQ configuration

✅ Success Response:

{
  "config": {
    "enabled": true,
    "url": "amqp://***:***@rabbitmq:5672/",
    "exchange": "whatsapp_events",
    "exchange_type": "topic",
    "queue": "user_{user_id}_event_{event_type}",
    "queue_type": "classic",
    "routing_key": "whatsapp.{user_id}.{event_type}",
    "events": "All",
    "durable": true,
    "auto_delete": false,
    "exclusive": false,
    "no_wait": false,
    "delivery_mode": 2
  },
  "stats": {
    "userID": "abc123",
    "dynamicQueues": true,
    "createdQueues": 5,
    "queueNames": [
      "user_abc123_event_Message",
      "user_abc123_event_Receipt", 
      "user_abc123_event_ChatPresence",
      "user_abc123_event_CallOffer",
      "user_abc123_event_Connected"
    ]
  }
}

💡 New: The response now includes statistics for dynamically created queues, showing how many queues were generated and their specific names.

POST /session/rabbitmq/test

Purpose: Test RabbitMQ connection and configuration

✅ Success Response:

{
  "code": 200,
  "data": {
    "status": "connected",
    "exchange": "whatsapp.events",
    "queue": "whatsapp.user.abc123",
    "test_message_sent": true
  },
  "success": true
}

🌐 Global RabbitMQ System (Admin Only)

Purpose: The global RabbitMQ system processes ALL events from ALL users with enterprise-grade performance and reliability.

🏗️ Architecture Features

Connection Pool: 50 concurrent connections for maximum throughput
Worker Pool: 100 workers processing events in parallel
Circuit Breaker: Automatic protection against connection failures
Health Monitoring: Continuous connection health checks every 30 seconds
Auto-Recovery: Automatic reconnection with exponential backoff
Batch Processing: Optimized for high-volume event processing
Performance Metrics: Real-time monitoring of events per second, queue depth, etc.

📊 Admin Endpoints:

GET /admin/stats: Get global system statistics including RabbitMQ metrics
POST /admin/test-systems: Test all global systems including RabbitMQ health
GET /admin/config: View global configuration including RabbitMQ settings
POST /admin/reload-config: Reload configuration from environment variables

🔧 Configuration (Environment Variables):

# Global RabbitMQ Configuration
GLOBAL_RABBITMQ_ENABLED=true
GLOBAL_RABBITMQ_URL=amqp://user:pass@rabbitmq:5672/
GLOBAL_RABBITMQ_EXCHANGE=global_whatsapp_events
GLOBAL_RABBITMQ_QUEUE=global_queue_{user_id}_{event_type}
GLOBAL_RABBITMQ_ROUTING_KEY=whatsapp.{user_id}.{event_type}
GLOBAL_RABBITMQ_EVENTS=All

# Performance Settings
GLOBAL_RABBITMQ_CONNECTION_POOL_SIZE=50
GLOBAL_RABBITMQ_WORKER_COUNT=100
GLOBAL_RABBITMQ_QUEUE_BUFFER_SIZE=100000
GLOBAL_RABBITMQ_BATCH_SIZE=100
GLOBAL_RABBITMQ_BATCH_TIMEOUT_MS=500

# Resilience Settings  
GLOBAL_RABBITMQ_CIRCUIT_BREAKER_THRESHOLD=10
GLOBAL_RABBITMQ_CIRCUIT_BREAKER_TIMEOUT_S=60
GLOBAL_RABBITMQ_MAX_RETRIES=3
GLOBAL_RABBITMQ_RETRY_DELAY_MS=1000

⚠️ Important: The global system works independently of individual user configurations. Both can be active simultaneously, with global events being sent to both systems when configured.

📋 Complete Event Types Reference

ZuckZapGo supports 47 event types organized into logical categories. You can subscribe to specific events or use "All" to receive everything.

💬 Messages and Communication

Event	Description	Webhook Payload Includes
`Message`	Incoming/outgoing messages (text, media, etc.)	content, sender, recipient, timestamp
`UndecryptableMessage`	Messages that couldn't be decrypted	sender, timestamp, error info
`Receipt`	Message delivery receipts (sent, delivered)	message_id, status, timestamp
`MediaRetry`	Media message retry events	message_id, retry_count, status
`ReadReceipt`	Message read receipts (read, played)	message_id, reader, timestamp

👥 Groups and Contacts

Event	Description	Webhook Payload Includes
`GroupInfo`	Group information changes (name, description, photo)	group_id, changes, author
`JoinedGroup`	User joined/left group events	group_id, participants, action
`Picture`	Profile/group picture changes	jid, picture_id, timestamp
`BlocklistChange`	Blocklist modification events	contact, action (block/unblock)
`Blocklist`	Complete blocklist updates	blocked_contacts, timestamp

🔌 Connection and Session

Event	Description	Webhook Payload Includes
`Connected`	Successfully connected to WhatsApp	jid, connection_info, timestamp
`Disconnected`	Disconnected from WhatsApp	reason, timestamp, reconnect_info
`ConnectFailure`	Connection failure events	error, retry_count, timestamp
`KeepAliveRestored`	Connection keep-alive restored	restoration_time, previous_state
`KeepAliveTimeout`	Connection keep-alive timeout	timeout_duration, connection_state
`LoggedOut`	User logged out from WhatsApp	reason, timestamp, session_end
`ClientOutdated`	Client version outdated warning	current_version, required_version
`TemporaryBan`	Temporary account ban notification	ban_duration, reason, appeal_info
`StreamError`	WebSocket stream errors	error_code, error_message, stream_info
`StreamReplaced`	WebSocket stream replaced by another connection	new_stream_info, replacement_reason
`PairSuccess`	Device pairing successful	device_info, pairing_method, timestamp
`PairError`	Device pairing failed	error_code, error_message, retry_info
`QR`	QR code generation/updates	qr_code, expiration, scan_info
`QRScannedWithoutMultidevice`	QR scanned but multidevice not enabled	scanner_info, multidevice_status

🔒 Privacy and Settings

Event	Description	Webhook Payload Includes
`PrivacySettings`	Privacy settings changes	setting_type, new_value, timestamp
`PushNameSetting`	Push name/display name updates	old_name, new_name, timestamp
`UserAbout`	User about/status message changes	jid, about_text, timestamp

🔄 Synchronization and State

Event	Description	Webhook Payload Includes
`AppState`	Application state changes	state_type, state_data, version
`AppStateSyncComplete`	App state synchronization completed	sync_duration, synced_data, timestamp
`HistorySync`	Message history synchronization	progress, total_messages, timestamp
`OfflineSyncCompleted`	Offline synchronization completed	sync_duration, messages_count
`OfflineSyncPreview`	Offline synchronization preview	pending_count, preview_data

📞 Calls

Event	Description	Webhook Payload Includes
`CallOffer`	Incoming call offer	caller, call_id, call_type, timestamp
`CallAccept`	Call accepted by recipient	call_id, participants, accept_time
`CallTerminate`	Call terminated/ended	call_id, duration, end_reason
`CallOfferNotice`	Call offer notification message	caller, call_type, notice_timestamp
`CallRelayLatency`	Call relay latency updates	call_id, latency_ms, relay_info

👁️ Presence and Activity

Event	Description	Webhook Payload Includes
`Presence`	User online/offline status changes	jid, presence_state, last_seen
`ChatPresence`	Chat typing/recording status	chat_id, participant, state, media_type

🔐 Identity, Errors, Newsletter & Special

Event	Description	Webhook Payload Includes
`IdentityChange`	User identity/security changes	jid, identity_change, verification
`CATRefreshError`	CAT token refresh errors	error_code, error_message, retry_info
`NewsletterJoin`	Joined newsletter/channel	newsletter_id, newsletter_info, join_time
`NewsletterLeave`	Left newsletter/channel	newsletter_id, leave_reason, timestamp
`NewsletterMuteChange`	Newsletter mute status changed	newsletter_id, mute_state, timestamp
`NewsletterLiveUpdate`	Newsletter live updates/broadcasts	newsletter_id, update_content, timestamp
`FBMessage`	Facebook/Meta bridge messages	message_content, bridge_info, timestamp
`All`	Special: Subscribe to all events above	All possible event payloads

📦 Event Payload Structure

Standard Webhook/RabbitMQ Event Format

All events follow this consistent structure:

{
  "user_id": "abc123def456",
  "user_token": "user_token_here",
  "event_type": "Message",
  "timestamp": "2024-01-15T10:30:00Z",
  "jid": "[email protected]",
  "data": {
    // Event-specific data here
    // Structure varies by event type
  },
  "webhook_info": {
    "delivery_attempt": 1,
    "webhook_id": "webhook_123"
  }
}

💡 Pro Tips:

Use event_type field to route events in your application
Check user_id for multi-tenant applications
Implement idempotency using timestamp and webhook_id
For RabbitMQ: routing key follows pattern whatsapp.{event_type}

⭐ Best Practices

🔧 Configuration Recommendations:

Webhooks: Ensure your endpoint responds with 200 status within 10 seconds
RabbitMQ: Use durable queues and persistent messages for production
Event Filtering: Subscribe only to events you need to reduce traffic
Error Handling: Implement retry logic for webhook failures
Security: Validate webhook signatures in production
Monitoring: Track delivery success rates and latency

⚡ Skip Media Download Configuration

Configure whether to skip downloading media files (images, videos, audio, documents, stickers) during WhatsApp events. When enabled, events will only contain WhatsApp metadata without base64 content or S3 uploads, dramatically improving performance for high-volume scenarios.

🎯 Performance Benefits: Skip media download can improve event processing speed by up to 90% and reduce bandwidth usage significantly. Perfect for high-volume messaging scenarios where media content is not required.

POST /session/skipmedia/config

Purpose: Configure skip media download for the authenticated user

📝 Request Body:

{
  "enabled": true
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "Details": "Skip media download configuration updated successfully",
    "SkipMediaDownload": true
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Description
enabled	boolean	Whether to skip media download (true/false)

GET /session/skipmedia/config

Purpose: Get current skip media download configuration (user-specific and global)

✅ Success Response:

{
  "code": 200,
  "data": {
    "UserSkipMediaDownload": false,
    "GlobalSkipMediaDownload": false,
    "Details": "Skip media download configuration retrieved successfully"
  },
  "success": true
}

📊 Response Fields:

Field	Type	Description
UserSkipMediaDownload	boolean	User-specific skip media setting
GlobalSkipMediaDownload	boolean	Server-wide skip media setting (read-only)

⚙️ Configuration Hierarchy

🎯 Priority Order

The system uses a hierarchical approach to determine whether to skip media download:

Priority	Configuration	Scope	Description
1 (Highest)	Command Line Flag	Global	`-skipmedia` affects all users system-wide
2	Environment Variable	Global	`GLOBAL_SKIP_MEDIA_DOWNLOAD=true` affects all users
3	User Configuration	Individual	Per-user `skip_media_download` setting
4 (Default)	Normal Behavior	Default	Download and process media normally

⚠️ Important: If any higher priority configuration enables skip media, it overrides all lower priority settings.

📈 Impact and Benefits

✅ When Skip Media is Enabled

🚀 Performance Benefits:

⚡ Faster Event Processing: No download delays
📊 Reduced Bandwidth Usage: No media file transfers
💾 Lower Storage Requirements: No temporary files or S3 uploads
🔄 Better Performance: Ideal for high-volume message processing
📱 Original Metadata: WhatsApp message metadata preserved

❌ What's Not Available:

No base64 content in webhook events
No S3 uploads (regardless of S3 configuration)
No temporary file creation
No media processing or conversion

✅ What's Still Available:

Complete WhatsApp message metadata
Message type identification
Sender and recipient information
Timestamps and message IDs
Event delivery to webhooks and RabbitMQ

🎯 Common Use Cases

Scenario	Recommendation	Reason
High-volume notification processing	✅ Enable skip media	Focus on message delivery tracking, not content
Real-time analytics dashboard	✅ Enable skip media	Only metadata needed for statistics
Message archival system	❌ Disable skip media	Full content preservation required
Customer support integration	❌ Disable skip media	Media content needed for support context
Chatbot with text-only responses	✅ Enable skip media	Media processing unnecessary for bots

🌐 Global Configuration

Environment Variable Configuration

System administrators can configure global skip media behavior using environment variables:

# Enable skip media globally for all users
GLOBAL_SKIP_MEDIA_DOWNLOAD=true

# Disable skip media globally (default)
GLOBAL_SKIP_MEDIA_DOWNLOAD=false

💡 Best Practice: Use global configuration for system-wide policies and individual user configuration for specific use cases.

👥 Skip Groups Processing Configuration

Configure whether to skip processing messages from WhatsApp groups. When enabled, the system will ignore all messages from group chats, processing only direct messages. This can improve performance and reduce processing overhead for applications that don't need group functionality.

🎯 Performance Benefits: Skip groups processing can reduce event volume by 60-80% in typical scenarios and significantly improve performance for applications focused on direct messaging only.

POST /session/skipgroups/config

Purpose: Configure skip groups processing for the authenticated user

📝 Request Body:

{
  "enabled": true
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "Details": "Skip groups configuration updated successfully",
    "SkipGroups": true
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Description
enabled	boolean	Whether to skip group message processing (true/false)

GET /session/skipgroups/config

Purpose: Get current skip groups processing configuration

✅ Success Response:

{
  "code": 200,
  "data": {
    "SkipGroups": false,
    "Details": "Skip groups configuration retrieved successfully"
  },
  "success": true
}

📊 Response Fields:

Field	Type	Description
SkipGroups	boolean	Current skip groups setting for the user

⚙️ User Creation Configuration

🎯 Setting Skip Groups During User Creation

You can configure skip groups behavior when creating a new user via the admin endpoint:

{
  "name": "John Doe",
  "token": "unique_user_token",
  "webhook": "https://example.com/webhook",
  "events": "Message,ReadReceipt",
  "skipGroups": true,
  "s3Config": { ... },
  "rabbitmqConfig": { ... }
}

📋 Skip Groups Parameter:

Parameter	Type	Default	Description
skipGroups	boolean	false	Skip processing messages from WhatsApp groups

📈 Impact and Benefits

✅ When Skip Groups is Enabled

🚀 Performance Benefits:

⚡ Reduced Event Volume: 60-80% fewer events in typical scenarios
📊 Lower Processing Overhead: Focus only on direct messages
💾 Reduced Storage Requirements: Less data to store and process
🔄 Better Performance: Ideal for customer support and direct messaging apps
📱 Cleaner Event Stream: Only relevant direct messages processed

❌ What's Not Available:

No group message events in webhooks
No group message events in RabbitMQ
No group-related notifications
No group media processing
No group member activity tracking

✅ What's Still Available:

All direct message events and processing
Individual chat functionality
Media processing for direct messages
All API endpoints for sending messages
Group management endpoints (create, join, etc.)

🎯 Common Use Cases

Scenario	Recommendation	Reason
Customer support system	✅ Enable skip groups	Focus on direct customer interactions only
Personal assistant chatbot	✅ Enable skip groups	Individual conversations are more relevant
Business communication platform	❌ Disable skip groups	Team collaboration requires group functionality
Community management tool	❌ Disable skip groups	Group interactions are the primary focus
Lead generation system	✅ Enable skip groups	Direct inquiries are more valuable than group chatter
Notification broadcasting	✅ Enable skip groups	One-way communication doesn't need group processing

🔧 Technical Implementation

How Skip Groups Works

When skip groups is enabled, the system performs early filtering at the event processing level:

1. WhatsApp event received
2. Check if message is from group (JID ends with @g.us)
3. If skip_groups = true AND message is from group:
   → Skip all processing (no webhook, no RabbitMQ, no storage)
4. If message is direct (JID ends with @s.whatsapp.net):
   → Process normally (webhook, RabbitMQ, storage as configured)

💡 Performance Note: The filtering happens before any expensive operations like media download, webhook calls, or database writes, maximizing performance benefits.

💡 Best Practices

✅ Recommended Practices:

Combine with Skip Media: Use both skip groups and skip media for maximum performance in high-volume scenarios
Monitor Event Volume: Track the reduction in event volume after enabling skip groups
Test Thoroughly: Ensure your application doesn't depend on group events before enabling
Document Configuration: Keep track of which users have skip groups enabled
Consider Use Case: Enable for customer support, disable for community management

⚠️ Important Considerations:

Group management endpoints still work (create, join, leave groups)
You can still send messages to groups via API
Only incoming group messages are skipped
Configuration can be changed at any time
No retroactive processing of skipped messages

📰 Skip Newsletters Processing Configuration

Configure whether to skip processing messages from WhatsApp newsletters and channels. When enabled, the system will ignore all messages from newsletter channels, processing only direct messages and groups.

🎯 Performance Benefits: Skip newsletters processing can reduce event volume by 20-40% in scenarios with heavy newsletter subscriptions and significantly improve performance for applications that don't need newsletter content.

POST /session/skipnewsletters/config

Purpose: Configure skip newsletters processing for the authenticated user

📝 Request Body:

{
  "enabled": true
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "Details": "Skip newsletters configuration updated successfully",
    "SkipNewsletters": true
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Description
enabled	boolean	true to skip newsletters, false to process them

GET /session/skipnewsletters/config

Purpose: Get current skip newsletters processing configuration

✅ Success Response:

{
  "code": 200,
  "data": {
    "SkipNewsletters": false,
    "Details": "Skip newsletters configuration retrieved successfully"
  },
  "success": true
}

📋 Response Fields:

Field	Type	Description
SkipNewsletters	boolean	Current skip newsletters setting for the user

💡 Configuration Tips:

Content Apps: Disable skip newsletters for content aggregation applications
Customer Support: Enable skip newsletters to focus on direct customer interactions
Performance: Combine with skip groups for maximum event filtering
Monitor Volume: Track the reduction in event volume after enabling
Newsletter Management: You can still manage newsletter subscriptions via API

✅ When Skip Newsletters is Enabled

🚫 Events Filtered (Ignored):

Newsletter message events from channels like 120363144038483540@newsletter
Newsletter media events (images, videos, documents)
Newsletter update notifications
Channel broadcast messages

✅ Events Still Processed:

Direct messages to/from individuals
Group messages (if skip groups is disabled)
Broadcast messages (if skip broadcasts is disabled)
System events (connected, disconnected, etc.)

📊 Newsletter Processing Examples

Event Source	Skip Newsletters = ON	Skip Newsletters = OFF
`120363144038483540@newsletter`	✅ Enable skip newsletters	❌ Process newsletter
`[email protected]`	❌ Process direct message	❌ Process direct message
`[email protected]`	❌ Process group (depends on skip groups)	❌ Process group (depends on skip groups)

🎯 Setting Skip Newsletters During User Creation

You can configure skip newsletters behavior when creating a new user via the admin endpoint:

{
  "name": "Newsletter Skipper User",
  "token": "user_token_123",
  "skipNewsletters": true,
  "webhook": "https://webhook.site/endpoint"
}

📋 Skip Newsletters Parameter:

Parameter	Type	Default	Description
skipNewsletters	boolean	false	Skip processing newsletter messages

📢 Skip Broadcasts Processing Configuration

Configure whether to skip processing messages from WhatsApp broadcasts and status updates. When enabled, the system will ignore all messages from broadcast lists and status updates, processing only direct messages, groups, and newsletters.

🎯 Performance Benefits: Skip broadcasts processing can reduce event volume by 10-30% in scenarios with frequent broadcast interactions and significantly improve performance for applications that don't need broadcast functionality.

POST /session/skipbroadcasts/config

Purpose: Configure skip broadcasts processing for the authenticated user

📝 Request Body:

{
  "enabled": true
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "Details": "Skip broadcasts configuration updated successfully",
    "SkipBroadcasts": true
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Description
enabled	boolean	true to skip broadcasts, false to process them

GET /session/skipbroadcasts/config

Purpose: Get current skip broadcasts processing configuration

✅ Success Response:

{
  "code": 200,
  "data": {
    "SkipBroadcasts": false,
    "Details": "Skip broadcasts configuration retrieved successfully"
  },
  "success": true
}

📋 Response Fields:

Field	Type	Description
SkipBroadcasts	boolean	Current skip broadcasts setting for the user

💡 Configuration Tips:

Business Apps: Disable skip broadcasts for marketing campaign tracking
Personal Apps: Enable skip broadcasts to focus on direct conversations
Status Updates: Enable to ignore WhatsApp status interactions
Broadcast Lists: Enable to ignore broadcast list messages
Performance: Combine with other skip options for maximum efficiency

✅ When Skip Broadcasts is Enabled

🚫 Events Filtered (Ignored):

Broadcast list messages from @broadcast addresses
Status update interactions from status@broadcast
Broadcast media events (images, videos, documents)
Mass message campaigns

✅ Events Still Processed:

Direct messages to/from individuals
Group messages (if skip groups is disabled)
Newsletter messages (if skip newsletters is disabled)
System events (connected, disconnected, etc.)

📊 Broadcast Processing Examples

Event Source	Skip Broadcasts = ON	Skip Broadcasts = OFF
`status@broadcast`	✅ Enable skip broadcasts	❌ Process status update
`12345@broadcast`	✅ Enable skip broadcasts	❌ Process broadcast list
`[email protected]`	❌ Process direct message	❌ Process direct message

🎯 Setting Skip Broadcasts During User Creation

You can configure skip broadcasts behavior when creating a new user via the admin endpoint:

{
  "name": "Broadcast Skipper User",
  "token": "user_token_123",
  "skipBroadcasts": true,
  "webhook": "https://webhook.site/endpoint"
}

📋 Skip Broadcasts Parameter:

Parameter	Type	Default	Description
skipBroadcasts	boolean	false	Skip processing broadcast messages and status updates

🔄 Advanced Filtering Combinations

⚡ Ultra Performance Mode: Enable all skip options for maximum performance in high-volume environments:

skipGroups: true - Skip group messages
skipNewsletters: true - Skip newsletter content
skipBroadcasts: true - Skip broadcast messages
skipMedia: true - Skip media download

Result: Process only direct 1:1 messages for maximum efficiency.

🎯 Smart Filtering Strategy:

Use Case	Skip Groups	Skip Newsletters	Skip Broadcasts
Customer Support	✅ ON	✅ ON	✅ ON
Community Management	❌ OFF	✅ ON	✅ ON
Content Aggregation	❌ OFF	❌ OFF	❌ OFF
Marketing Analytics	✅ ON	❌ OFF	❌ OFF

👤 Skip Own Messages Processing Configuration

Configure whether to skip processing your own sent messages (IsFromMe: true). When enabled, the system will ignore all messages that were sent by you, processing only messages received from others. This can improve performance and reduce processing overhead for applications that don't need to track outgoing messages.

🎯 Performance Benefits: Skip own messages processing can reduce event volume by 30-50% for applications with heavy outgoing message activity and significantly improve performance for applications focused on incoming message monitoring only.

POST /session/skipownmessages/config

Purpose: Configure skip own messages processing for the authenticated user

📝 Request Body:

{
  "enabled": true
}

✅ Success Response:

{
  "Details": "Skip own messages configuration updated successfully",
  "SkipOwnMessages": true
}

📋 Parameters:

Parameter	Type	Required	Description
enabled	boolean	Yes	Whether to skip own message processing (true/false)

GET /session/skipownmessages/config

Purpose: Get current skip own messages processing configuration

✅ Success Response:

{
  "SkipOwnMessages": false,
  "Details": "Skip own messages configuration retrieved successfully"
}

📊 Response Fields:

Field	Type	Description
SkipOwnMessages	boolean	Current skip own messages setting for the user
Details	string	Status message

🎯 Setting Skip Own Messages During User Creation

💡 Pro Tip: You can configure skip own messages behavior when creating a new user via the admin endpoint:

{
  "name": "Own Message Skipper User",
  "token": "user_token_123",
  "skipOwnMessages": true,
  "webhook": "https://webhook.site/endpoint"
}

📋 Skip Own Messages Parameter:

Parameter	Type	Default	Description
skipOwnMessages	boolean	false	Skip processing your own sent messages

✅ When Skip Own Messages is Enabled

📌 What Gets Skipped:

All outgoing messages you send (IsFromMe: true)
Your own message content events
Your own media message events

✅ What Still Gets Processed:

All incoming messages from others
Message delivery confirmations
Read receipts for your messages
Connection and status events
Group notifications and events

How Skip Own Messages Works

🔍 Technical Details: When skip own messages is enabled, the system performs early filtering at the event processing level:

Event received from WhatsApp
Check if it's a message event with IsFromMe: true
If skip_own_messages = true AND message is from you:
- Skip webhook delivery
- Skip RabbitMQ publishing
- Skip S3 upload
- Log as filtered event
Otherwise, process normally

🚀 Best Practices

Bot Applications: Enable skip own messages for better separation of concerns
Monitor Event Volume: Track the reduction in event volume after enabling skip own messages
Test Thoroughly: Ensure your application logic doesn't depend on outgoing message events
Document Configuration: Keep track of which users have skip own messages enabled

🎯 Smart Usage Patterns

🔄 Filtering Strategy for Different Applications:

Application Type	Skip Own Messages	Reason
Customer Support Bot	✅ Enable	Focus only on incoming customer messages
Message Analytics	❌ Disable	Need complete message flow analysis
Auto-responder	✅ Enable	Prevent processing own automated responses
Backup/Archive Service	❌ Disable	Need complete conversation history
Notification System	✅ Enable	Only react to incoming notifications

🔄 Advanced Filtering Combinations

⚡ Ultra Performance Mode: Enable all skip options for maximum performance in high-volume environments:

skipGroups: true - Skip group messages
skipNewsletters: true - Skip newsletter content
skipBroadcasts: true - Skip broadcast messages
skipOwnMessages: true - Skip your own messages
skipMedia: true - Skip media download

Result: Process only incoming direct 1:1 messages for maximum efficiency.

🔧 Administration

Administrative endpoints for user management, system configuration, and monitoring. Requires admin token authentication.

🔒 Admin Access Required: All endpoints in this section require the admin token (ZUCKZAPGO_ADMIN_TOKEN) in the Authorization header.

GET /admin/users

Purpose: Get list of all registered users

✅ Success Response:

[
  {
    "id": "user123",
    "name": "John Doe",
    "token": "user_token_123",
    "webhook": "https://example.com/webhook",
    "jid": "[email protected]",
    "connected": true,
    "events": "Message,ReadReceipt"
  }
]

POST /admin/users

Purpose: Create a new user with optional integrations

📝 Request Body:

{
  "name": "John Doe",
  "token": "unique_user_token",
  "webhook": "https://example.com/webhook",
  "events": "Message,ReadReceipt,Presence",
  "skipMedia": false,
  "skipGroups": false,
  "skipNewsletters": false,
  "skipBroadcasts": false,
  "proxyConfig": {
    "enabled": true,
    "proxyURL": "socks5://user:pass@proxy:1080"
  },
  "s3Config": {
    "enabled": true,
    "endpoint": "https://s3.amazonaws.com",
    "region": "us-east-1",
    "bucket": "my-bucket",
    "accessKey": "AKIAIOSFODNN7EXAMPLE",
    "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "mediaDelivery": "both",
    "retentionDays": 30
  },
  "rabbitmqConfig": {
    "enabled": true,
    "url": "amqp://user:pass@rabbitmq:5672/",
    "exchange": "whatsapp.events",
    "queue": "whatsapp.user.{user_id}",
    "events": ["Message", "ReadReceipt"]
  }
}

📋 Configuration Options:

Config	Purpose	Required
skipGroups	Skip processing messages from WhatsApp groups	No
skipNewsletters	Skip processing messages from WhatsApp newsletters	No
skipBroadcasts	Skip processing messages from WhatsApp broadcasts	No
proxyConfig	HTTP/SOCKS proxy for WhatsApp connections	No
s3Config	S3 storage for media files	No
rabbitmqConfig	RabbitMQ for event messaging	No

DELETE /admin/users/{id}

Purpose: Delete user account (simple deletion)

🔄 Path Parameters:

Parameter	Description
{id}	User ID to delete

DELETE /admin/users/{id}/full

Purpose: Complete user deletion with cleanup

🧹 Cleanup Actions:

WhatsApp logout and disconnect
Database record removal
Local file cleanup
S3 file deletion (if enabled)
RabbitMQ queue cleanup
Memory and cache clearing

💡 Recommended: Use this endpoint for complete user removal in production environments.

🌐 Global System Management

GET /admin/global/stats

Purpose: Get system statistics and metrics

✅ Success Response:

{
  "totalUsers": 15,
  "connectedUsers": 12,
  "totalMessages": 1500,
  "systemUptime": "72h30m",
  "memoryUsage": "1.2GB",
  "version": "1.0.0"
}

POST /admin/global/test

Purpose: Test global webhook and RabbitMQ connections

✅ Success Response:

{
  "webhook": {
    "status": "success",
    "responseTime": "150ms"
  },
  "rabbitmq": {
    "status": "success",
    "connectionStatus": "connected"
  }
}

🐳 Deployment Guide

Complete guide to deploy ZuckZapGo using Docker, Docker Compose, and Docker Swarm for production environments.

📋 Prerequisites:

Docker 20.10+ and Docker Compose 2.0+
At least 2GB RAM and 2 CPU cores
Domain name with SSL certificate (for production)
PostgreSQL database (included in stack)

🚀 Quick Deploy with Docker Compose

1. Clone and Setup

# Clone the repository
git clone https://github.com/your-repo/zuckzapgo-private.git
cd zuckzapgo-private

# Copy environment template
cp _env .env

# Edit environment variables
nano .env

2. Configure Environment

Essential environment variables to configure:

# Authentication
ZUCKZAPGO_ADMIN_TOKEN=your_secure_admin_token_here

# Database
DB_PASSWORD=your_secure_database_password

# Global Webhook (optional)
GLOBAL_WEBHOOK_ENABLED=true
GLOBAL_WEBHOOK_URL=https://your-domain.com/webhook

# Global RabbitMQ (optional)
GLOBAL_RABBITMQ_ENABLED=true
GLOBAL_RABBITMQ_URL=amqp://user:pass@rabbitmq:5672/

# Licensing
LICENSE_KEY=your_license_key
INSTANCE_ID=your_instance_id

3. Deploy Services

# Start all services
docker-compose up -d

# Check services status
docker-compose ps

# View logs
docker-compose logs -f zuckzapgo

🏢 Production Deploy with Docker Swarm

Docker Swarm Stack Deployment

For production environments with high availability and load balancing:

# Initialize Docker Swarm (if not already done)
docker swarm init

# Create external network
docker network create --driver overlay --attachable network_public

# Create volumes
docker volume create postgres_data_zuckzapgo
docker volume create rabbitmq_data_zuckzapgo

# Deploy the stack
docker stack deploy -c docker-compose-swarm.yaml zuckzapgo_stack

# Check stack status
docker stack services zuckzapgo_stack

# Scale services (if needed)
docker service scale zuckzapgo_stack_zuckzapgo_private=3

⚙️ Configuration Reference

Core Configuration

Variable	Description	Default
ZUCKZAPGO_ADMIN_TOKEN	Admin authentication token	Required
ZUCKZAPGO_ADDRESS	Server bind address	0.0.0.0
ZUCKZAPGO_PORT	Server port	8080
LOG_TYPE	Log format (json/console)	console

Database Configuration

Variable	Description	Example
DB_HOST	Database host	localhost
DB_PORT	Database port	5432
DB_USER	Database username	zuckzapgo
DB_PASSWORD	Database password	secure_password
DB_NAME	Database name	zuckzapgo

🏥 Health Monitoring

Health Check Endpoint

Monitor service health using the built-in health check:

# Check service health
curl -f http://localhost:8080/health

# Expected response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "database": "connected",
    "whatsapp": "ready"
  }
}

📈 Scaling and Performance

Resource Requirements

Environment	CPU	Memory	Storage
Development	1 core	1GB	10GB
Production (Small)	2 cores	2GB	50GB
Production (Large)	4+ cores	4GB+	100GB+

🔍 Troubleshooting

Common Issues

🐛 Database Connection Failed:

Check DB_* environment variables
Ensure PostgreSQL is running
Verify network connectivity

🔐 Authentication Errors:

Verify ZUCKZAPGO_ADMIN_TOKEN is set
Check Authorization header format
Ensure user tokens are valid

📱 WhatsApp Connection Issues:

Check internet connectivity
Verify phone number format
Ensure QR code is fresh (< 2 minutes)

n8n Community Node Integration

n8n-nodes-zuckzapgo

Pacote completo de nós para n8n que permite integração total com ZuckZapGo através de workflows visuais.

10 Nós Especializados 70+ Operações v1.6.0 Atual MIT License

zuckzapgoSession

Gerenciamento completo de sessões WhatsApp

Connect/Disconnect
QR Code & Phone Pairing
Status monitoring
Proxy & S3 configuration

zuckzapgoMessage

Envio de todos os tipos de mensagens

Text, Image, Audio, Video
Documents, Stickers, Location
Contacts, Buttons, Lists, Polls
Templates with mentions

zuckzapgoAI

Nó otimizado para workflows de IA

Interface simplificada para AI Tools
Batch processing
Error tolerance
URL/Base64/Binary support

zuckzapgoGroup

Gerenciamento completo de grupos

Create, join, leave groups
Participant management
Settings & permissions
Invite links & info

zuckzapgoTrigger

Recepção de eventos em tempo real

40+ tipos de eventos
Filtros avançados
Content parsing inteligente
Media data extraction

zuckzapgoSendAndWait

Workflows interativos com aprovação

Approval buttons
Form responses
Time limits
Web interface

Instalação

Via NPM

npm install n8n-nodes-zuckzapgo

Via Interface n8n

Vá para Settings > Community Nodes
Clique em Install a community node
Digite: n8n-nodes-zuckzapgo
Clique em Install

Docker Compose

version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    environment:
      - N8N_NODES_INCLUDE=n8n-nodes-zuckzapgo
    volumes:
      - n8n_data:/home/node/.n8n
    ports:
      - "5678:5678"

Exemplos de Workflows

Chatbot Automático com IA

{
  "name": "AI WhatsApp Chatbot",
  "nodes": [
    {
      "name": "zuckzapgoTrigger",
      "type": "n8n-nodes-zuckzapgo.zuckzapgoTrigger",
      "parameters": {
        "events": ["Message"],
        "filters": {
          "messageType": "text",
          "isGroup": false
        }
      }
    },
    {
      "name": "OpenAI",
      "type": "@n8n/n8n-nodes-langchain.openAi",
      "parameters": {
        "prompt": "Responda como assistente da empresa"
      }
    },
    {
      "name": "zuckzapgoAI", 
      "type": "n8n-nodes-zuckzapgo.zuckzapgoAI",
      "parameters": {
        "operation": "sendText",
        "phoneNumber": "={{$('zuckzapgoTrigger').item.json.sender}}",
        "message": "={{$('OpenAI').item.json.response}}"
      }
    }
  ]
}

Sistema de Aprovação de Pedidos

{
  "name": "Order Approval System",
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook"
    },
    {
      "name": "zuckzapgoSendAndWait",
      "type": "n8n-nodes-zuckzapgo.zuckzapgoSendAndWait",
      "parameters": {
        "operation": "sendAndWaitForApproval",
        "phone": "={{$json.manager_phone}}",
        "message": "Aprovar pedido #{{$json.order_id}}?",
        "approvalType": "double"
      }
    },
    {
      "name": "If Approved",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "boolean": [{
            "value1": "={{$json.approved}}",
            "value2": true
          }]
        }
      }
    }
  ]
}

Configuração de Credenciais

Credenciais ZuckZapGo

No n8n, vá para Credentials
Clique em Create New
Selecione zuckzapgo API
Configure:

API Token: Seu token de usuário ZuckZapGo
API URL: URL da sua instância ZuckZapGo (ex: http://localhost:8080)

Chatwoot Gateway Integration

ZuckZapGo-Chatwoot Gateway

Gateway multi-tenant para integração entre ZuckZapGo (WhatsApp) e Chatwoot (CRM) com conversão automática de mensagens bidirecionais.

Multi-tenant

Conversão Bidirecional

Bot de Controle

Painel Admin

Arquitetura

↔

ZuckZapGo

↔

Gateway

↔

Chatwoot

↔

Agents

Funcionalidades Principais

🔄 Core Features

Multi-tenant: Suporte a múltiplas integrações ZuckZapGo-Chatwoot independentes
Conversão Automática: Mensagens bidirecionais ZuckZapGo ↔ Chatwoot
Bot de Controle: Comandos WhatsApp (/connect, /status, /disconnect, /qrcode)
Suporte a Grupos: Tratamento especial para grupos WhatsApp
Cache Redis: Otimização de performance e sessões
Distribuição de Webhooks: Para múltiplos endpoints personalizados

🛠 Management Features

Painel Admin Web: Interface para gerenciamento visual das integrações
API RESTful: Endpoints completos para CRUD de integrações
Health Checks: Monitoramento de saúde da aplicação
Rate Limiting: Proteção contra abuse via Nginx
SSL/TLS Support: Suporte nativo a HTTPS
Docker Ready: Containerização completa com docker-compose

🔒 Security Features

API Key Authentication: Proteção de rotas sensíveis
Headers de Segurança: HSTS, XSS Protection, etc.
Validação de Entrada: Sanitização de todos os inputs
Rate Limiting: Por IP e por endpoint

API Endpoints do Gateway

Method	Endpoint	Description	Auth
GET	/api/v1/integrations	Listar todas as integrações	API Key
POST	/api/v1/integrations	Criar nova integração	API Key
GET	/api/v1/integrations/{uid}	Obter integração específica	API Key
PUT	/api/v1/integrations/{uid}	Atualizar integração	API Key
DELETE	/api/v1/integrations/{uid}	Deletar integração	API Key
POST	/api/v1/integrations/{uid}/test	Testar conectividade	API Key
POST	/api/v1/webhook/zuckzapgo/{token}	Receber webhook ZuckZapGo	None
POST	/api/v1/webhook/chatwoot/{uid}	Receber webhook Chatwoot	None
POST	/api/v1/webhooks/endpoints	Criar endpoint de webhook	API Key
GET	/health	Status básico da aplicação	None
GET	/api/v1/health	Status detalhado com métricas	API Key

Comandos do Bot WhatsApp

/connect

Inicia o processo de conexão com WhatsApp

Resposta: "🔗 Iniciando conexão... Escaneie o QR code no ZuckZapGo"

/status

Mostra status atual da conexão e estatísticas

Resposta: "📊 WhatsApp: Conectado | Chatwoot: Ativo | Mensagens hoje: 150"

/qrcode

Gera novo QR code para conexão

Resposta: "📱 Link QR: http://zuckzapgo.domain.com/qr"

/disconnect

Desconecta do WhatsApp

Resposta: "❌ Desconectado do WhatsApp"

/help

Lista todos os comandos disponíveis

Resposta: Lista completa de comandos com descrições

/info

Informações sobre a integração

Resposta: "ℹ️ Integração: Setup Automatizado | Uptime: 72h30m"

Setup de Integração Completo

1

Deploy do Gateway

git clone https://github.com/guilhermejansen/zuckzapgo-chatwoot-gateway.git
cd zuckzapgo-chatwoot-gateway
cp .env.example .env
nano .env
docker-compose up -d

2

Configurar Variáveis de Ambiente

# .env
SERVER_ADDRESS=0.0.0.0:8080
SERVER_API_KEY=your-super-secret-key
DATABASE_DSN=postgres://user:pass@postgres:5432/gateway?sslmode=disable
REDIS_ADDRESS=redis:6379
AUTH_USERNAME=admin
AUTH_PASSWORD=secure-password

3

Criar Integração via API

curl -X POST http://localhost:8080/api/v1/integrations \
  -H "X-API-Key: your-super-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "integration-001",
    "name": "Minha Primeira Integração", 
    "zuckzapgo_url": "http://zuckzapgo:8080",
    "zuckzapgo_token": "zuckzapgo-token-here",
    "chatwoot_url": "https://chatwoot.mydomain.com",
    "chatwoot_account_id": 1,
    "chatwoot_inbox_id": 1,
    "chatwoot_api_token": "chatwoot-token-here"
  }'

4

Configurar Webhooks

Configure o webhook do ZuckZapGo para apontar para:

http://your-gateway-domain/api/v1/webhook/zuckzapgo/{integration_uid}

Configure o webhook do Chatwoot para apontar para:

http://your-gateway-domain/api/v1/webhook/chatwoot/{integration_uid}

Monitoramento e Logs

Health Check Detalhado

curl http://localhost:8080/api/v1/health \
  -H "X-API-Key: your-api-key"

# Resposta:
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "services": {
    "database": "ok",
    "redis": "ok",
    "integrations": {
      "total": 5,
      "active": 4,
      "inactive": 1
    }
  },
  "uptime": "72h30m15s",
  "version": "1.0.0"
}

Logs em Tempo Real

# Ver todos os logs
docker-compose logs -f gateway

# Filtrar por erros
docker-compose logs -f gateway | grep ERROR

# Logs de uma integração específica
docker-compose logs -f gateway | grep "integration_uid"

Configuração para Produção

Nginx Configuration

server {
    listen 443 ssl http2;
    server_name zuckzapgo-gateway.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=webhook:10m rate=50r/s;

    location /api/v1/webhook/ {
        limit_req zone=webhook burst=20 nodelay;
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/ {
        limit_req zone=api burst=5 nodelay;
        proxy_pass http://localhost:8080;
    }
}

Endpoints Adicionais

Configurações Avançadas

Method	Endpoint	Description	Category
POST	/session/rabbitmq/config	Configurar RabbitMQ para eventos	Messaging
GET	/session/rabbitmq/config	Obter configuração RabbitMQ	Messaging
DELETE	/session/rabbitmq/config	Remover configuração RabbitMQ	Messaging
POST	/session/rabbitmq/test	Testar conexão RabbitMQ	Messaging
POST	/chat/send/text/mention	Enviar texto com menções específicas	Messages
POST	/chat/send/text/mention-all	Enviar texto mencionando todos	Messages
POST	/chat/send/edit	Editar mensagem enviada	Messages
GET	/newsletter/list	Listar newsletters/channels	Newsletter
GET	/user/lid/get	Converter phone/JID para LID	User Management
POST	/user/lid/from-lid	Converter LID para phone/JID	User Management
GET	/user/lid/mappings	Listar mapeamentos LID	User Management
GET	/health	Verificar saúde do sistema	System Health
POST	/group/send/event	Enviar evento para grupo	Groups
POST	/group/inviteinfo	Obter info de convite de grupo	Groups

Endpoints Administrativos Globais

Method	Endpoint	Description	Admin Required
GET	/admin/global/stats	Estatísticas globais do sistema	Yes
POST	/admin/global/test	Testar sistemas globais	Yes
GET	/admin/global/config	Obter configuração global	Yes
POST	/admin/global/config/reload	Recarregar configuração global	Yes
POST	/admin/global/event/test	Enviar evento de teste global	Yes

Exemplos de Uso

Configurar RabbitMQ

curl -X POST http://localhost:8080/session/rabbitmq/config \
  -H "token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "amqp://user:pass@rabbitmq:5672/",
    "exchange": "zuckzapgo.events",
    "exchange_type": "topic",
    "queue": "zuckzapgo.messages",
    "queue_type": "classic",
    "routing_key": "whatsapp.{event_type}",
    "events": "Message,ReadReceipt,Connected,GroupInfo,All",
    "durable": true,
    "auto_delete": false,
    "exclusive": false,
    "no_wait": false,
    "delivery_mode": 2
  }'

Enviar Mensagem com Mencão

curl -X POST http://localhost:8080/chat/send/text/mention \
  -H "token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Phone": "[email protected]",
    "Body": "Olá @user1, como está?",
    "Mentions": [
      {
        "jid": "[email protected]",
        "start": 4,
        "length": 6
      }
    ]
  }'

Editar Mensagem

curl -X POST http://localhost:8080/chat/send/edit \
  -H "token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Phone": "[email protected]", 
    "MessageID": "ABCDEF1234567890",
    "NewText": "Mensagem corrigida"
  }'

👤 User Management

Comprehensive user management endpoints for checking users, getting information, managing contacts, and handling LID (Link ID) conversions.

📋 User Information

POST /user/check Check if phone numbers have WhatsApp

Request Body:

{
  "Phone": ["5491155553934", "5521971532700"]
}

Response:

{
  "results": [
    {
      "phone": "5491155553934",
      "exists": true,
      "jid": "[email protected]"
    },
    {
      "phone": "5521971532700", 
      "exists": false,
      "jid": ""
    }
  ]
}

POST /user/info Get detailed user information

Request Body:

{
  "Phone": ["5491155553934", "5521971532700"]
}

Response:

{
  "results": [
    {
      "phone": "5491155553934",
      "status": "Available",
      "picture_id": "1234567890",
      "devices": ["MOBILE", "WEB"]
    }
  ]
}

POST /user/avatar Get user avatar/profile picture

Request Body:

{
  "Phone": "5491155553934",
  "Preview": true
}

Response:

{
  "url": "https://pps.whatsapp.net/v/...",
  "id": "1234567890",
  "type": "image",
  "direct_path": "/v/..."
}

GET /user/contacts List user contacts

Response:

{
  "contacts": [
    {
      "jid": "[email protected]",
      "name": "John Doe",
      "notify": "John",
      "business_name": "",
      "short_name": "John"
    }
  ]
}

POST /user/presence Set global user presence

Request Body:

{
  "type": "available"
}

Parameters:

Parameter	Type	Description
type	string	Presence type: "available", "unavailable"

🔗 LID (Link ID) Management

WhatsApp LID (Link ID) conversion utilities for handling different identifier formats.

GET /user/lid/get Convert phone/JID to LID format (GET method)

Query Parameters:

GET /user/lid/[email protected]

Response:

{
  "phone": "[email protected]",
  "lid": "2:abcd1234efgh5678@lid",
  "success": true
}

POST /user/lid/get Convert phone/JID to LID format (POST method)

Request Body:

{
  "phone": "[email protected]"
}

Response:

{
  "phone": "[email protected]",
  "lid": "2:abcd1234efgh5678@lid",
  "success": true
}

GET /user/lid/from-lid Convert LID to phone/JID format (GET method)

Query Parameters:

GET /user/lid/from-lid?lid=2:abcd1234efgh5678@lid

Response:

{
  "lid": "2:abcd1234efgh5678@lid",
  "phone": "[email protected]",
  "success": true
}

POST /user/lid/from-lid Convert LID to phone/JID format (POST method)

Request Body:

{
  "lid": "2:abcd1234efgh5678@lid"
}

Response:

{
  "lid": "2:abcd1234efgh5678@lid",
  "phone": "[email protected]",
  "success": true
}

GET /user/lid/mappings List all LID-to-phone mappings

Response:

{
  "mappings": [
    {
      "phone": "[email protected]",
      "lid": "2:abcd1234efgh5678@lid"
    },
    {
      "phone": "[email protected]", 
      "lid": "2:wxyz9876mnop5432@lid"
    }
  ],
  "total": 2
}

💡 About LID (Link ID)

LID (Link ID) is WhatsApp's internal identifier format used for certain operations. These endpoints help convert between standard JID format ([email protected]) and LID format (2:hash@lid) when needed for advanced integrations.

🏥 System Health & Monitoring

Monitor system health and performance with built-in health check endpoints.

📊 Health Check

GET /health Check system health status

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": "2h 15m 30s",
  "database": {
    "status": "connected",
    "type": "postgresql"
  },
  "memory": {
    "used": "45.2MB",
    "available": "512MB"
  },
  "active_sessions": 5,
  "total_users": 12
}

📋 Health Check Details

status: Overall system status (healthy/unhealthy)
database: Database connection status
memory: Memory usage information
active_sessions: Number of active WhatsApp sessions
total_users: Total registered users

🎯 Best Practices

Use health checks for load balancer configuration
Monitor health endpoint for system alerts
Set up automated monitoring based on health status
Check health before deploying updates

🌐 Global Administration

Advanced administration endpoints for managing global system configurations, monitoring, and testing enterprise integrations.

📊 Global Statistics & Monitoring

GET /admin/global/stats Get comprehensive global system statistics

Authentication:

Authorization: Bearer {admin_token}

Response:

{
  "system": {
    "uptime": "5d 12h 30m",
    "version": "1.0.0",
    "go_version": "1.21.0",
    "memory_usage": "128MB",
    "cpu_usage": "15%"
  },
  "users": {
    "total": 25,
    "active_sessions": 18,
    "connected": 15,
    "disconnected": 3
  },
  "webhooks": {
    "total_configured": 20,
    "active": 18,
    "failed_deliveries": 2,
    "success_rate": "95.2%"
  },
  "rabbitmq": {
    "total_configured": 12,
    "active_connections": 10,
    "messages_published": 15420,
    "failed_publishes": 5
  },
  "s3": {
    "total_configured": 8,
    "active_connections": 7,
    "files_uploaded": 2340,
    "storage_used": "1.2GB"
  }
}

POST /admin/global/test Test global system connectivity and functionality

Authentication:

Authorization: Bearer {admin_token}

Response:

{
  "database": {
    "status": "ok",
    "response_time": "2ms",
    "connection_pool": "healthy"
  },
  "global_webhook": {
    "status": "ok",
    "test_delivery": "success",
    "response_time": "150ms"
  },
  "global_rabbitmq": {
    "status": "ok",
    "connection": "established",
    "test_publish": "success"
  },
  "overall_status": "healthy"
}

⚙️ Global Configuration Management

GET /admin/global/config Get current global system configuration

Authentication:

Authorization: Bearer {admin_token}

Response:

{
  "server": {
    "address": "0.0.0.0",
    "port": 8080,
    "ssl_enabled": false,
    "log_type": "console"
  },
  "database": {
    "type": "postgresql",
    "host": "localhost",
    "port": 5432,
    "name": "zuckzapgo"
  },
  "global_webhook": {
    "enabled": true,
    "url": "https://webhook.example.com/global",
    "events": ["All"]
  },
  "global_rabbitmq": {
    "enabled": true,
    "url": "amqp://localhost:5672",
    "exchange": "whatsapp.global"
  },
  "features": {
    "skip_media": false,
    "skip_groups": false,
    "proxy_enabled": false
  }
}

POST /admin/global/config/reload Reload global configurations from environment

Authentication:

Authorization: Bearer {admin_token}

Response:

{
  "status": "success",
  "message": "Global configuration reloaded successfully",
  "reloaded_at": "2024-01-15T10:30:00Z",
  "changes": [
    "Global webhook URL updated",
    "RabbitMQ exchange configuration changed"
  ]
}

⚠️ Important Note

This endpoint reloads configuration from environment variables without requiring a service restart. Use with caution in production environments.

🧪 Global Event Testing

POST /admin/global/event/test Send test event through global systems

Authentication:

Authorization: Bearer {admin_token}

Request Body:

{
  "event_type": "AdminTest",
  "user_id": "admin-test",
  "user_token": "admin-test-token",
  "data": {
    "test": true,
    "message": "This is a test event sent from the admin panel",
    "timestamp": 1705312845
  }
}

Response:

{
  "status": "success",
  "event_sent": true,
  "webhook_delivery": {
    "status": "delivered",
    "response_code": 200,
    "response_time": "120ms"
  },
  "rabbitmq_publish": {
    "status": "published",
    "exchange": "whatsapp.global",
    "routing_key": "whatsapp.AdminTest"
  },
  "test_id": "test_1705312845_abc123"
}

Parameters:

Parameter	Type	Description
event_type	string	Type of test event to send
user_id	string	Test user identifier
user_token	string	Test user token
data	object	Custom test data payload

🎯 Best Practices

Use global statistics for monitoring dashboards
Test global systems before major deployments
Monitor webhook and RabbitMQ success rates
Set up alerts based on global system health
Use configuration reload sparingly in production
Test events help validate integration pipelines

📱 WhatsApp Status

Complete WhatsApp status management system. Send text, image, and video status to your contacts efficiently and effectively. Perfect for sharing moments, promotions, and updates with your network.

🎯 Status Features: Send texts with custom colors and fonts, images with captions, videos with descriptions, and manage your WhatsApp status visibility.

📝 Text Status

POST /status/send-text

Purpose: Send text status with custom formatting, colors, and fonts

📝 Basic Request:

{
  "message": "Hello everyone! 👋 How are you today?"
}

📝 Request with Colors:

{
  "message": "Colorful status! 🌈",
  "background_color": "#FF5733",
  "text_color": "#FFFFFF"
}

📝 Complete Request:

{
  "message": "Status with complete formatting! ✨",
  "background_color": "#4A90E2",
  "text_color": "#FFFFFF",
  "font": "BRYNDAN_WRITE"
}

✅ Success Response:

{
  "code": 200,
  "data": {
    "message_id": "3EB0C67C4D2A1F73E5B4",
    "status": "sent",
    "timestamp": 1705312800
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Required	Description
message	string	Yes	Status text content (max 700 characters)
background_color	string	No	Background color in hex format (e.g., #FF5733)
text_color	string	No	Text color in hex format (e.g., #FFFFFF)
font	string	No	Text font (see available fonts below)

🎨 Available Colors:

Background Colors: Any color in hexadecimal format (#RRGGBB)
Text Colors: Any color in hexadecimal format (#RRGGBB)
Popular Combinations: Blue/White (#4A90E2/#FFFFFF), Green/White (#25D366/#FFFFFF), Black/White (#000000/#FFFFFF)

📝 Available Fonts:

BRYNDAN_WRITE - Elegant handwritten font
BEBASNEUE_REGULAR - Modern and clean font
OSWALD_HEAVY - Strong and impactful font
DAMION_REGULAR - Stylized cursive font
MORNINGBREEZE_REGULAR - Soft and elegant font
CALISTOGA_REGULAR - Unique decorative font
EXO_BOLD - Futuristic and bold font
COURIER_PRIME_BOLD - Classic monospace font

🖼️ Image Status

POST /status/send-image

Purpose: Send image status with optional caption

📝 Request with Base64:

{
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "caption": "Special moment captured! 📸✨"
}

📝 Request with URL:

{
  "image": "https://example.com/images/beautiful-sunset.jpg",
  "caption": "Amazing sunset today! 🌅"
}

📝 Multipart/Form-Data Request:

POST /status/send-image
Content-Type: multipart/form-data

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="status.jpg"
Content-Type: image/jpeg

[binary image data]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="caption"

Image uploaded via file! 🚀
------WebKitFormBoundary7MA4YWxkTrZu0gW--

✅ Success Response:

{
  "code": 200,
  "data": {
    "message_id": "3EB0C67C4D2A1F73E5B4",
    "status": "sent",
    "timestamp": 1705312800,
    "media_url": "https://media.example.com/status/12345.jpg"
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Required	Description
image	string/file	Yes	Image as base64, URL, or file (JPG, PNG, GIF)
caption	string	No	Image caption (max 200 characters)

📐 Supported Formats:

Types: JPEG, PNG, GIF
Max file size: 16MB
Recommended resolution: 1080x1920 (9:16) for best mobile viewing
Upload methods: Base64, direct URL, or multipart upload

🎥 Video Status

POST /status/send-video

Purpose: Send video status with optional caption

📝 Request with Base64:

{
  "video": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28y...",
  "caption": "Amazing video moment! 🎬🔥"
}

📝 Request with URL:

{
  "video": "https://example.com/videos/amazing-moment.mp4",
  "caption": "Check out this incredible video! 🚀"
}

📝 Multipart/Form-Data Request:

POST /status/send-video
Content-Type: multipart/form-data

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="video"; filename="status.mp4"
Content-Type: video/mp4

[binary video data]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="caption"

Video uploaded via file! 🎥
------WebKitFormBoundary7MA4YWxkTrZu0gW--

✅ Success Response:

{
  "code": 200,
  "data": {
    "message_id": "3EB0C67C4D2A1F73E5B4",
    "status": "sent",
    "timestamp": 1705312800,
    "media_url": "https://media.example.com/status/12345.mp4",
    "duration": 15.5
  },
  "success": true
}

📋 Parameters:

Parameter	Type	Required	Description
video	string/file	Yes	Video as base64, URL, or file (MP4, AVI, MOV)
caption	string	No	Video caption (max 200 characters)

🎬 Supported Formats:

Types: MP4, AVI, MOV, 3GP
Max file size: 64MB
Max duration: 30 seconds
Recommended resolution: 1080x1920 (9:16) for best mobile viewing
Recommended codec: H.264 for best compatibility

🎯 Best Practices

Text: Use concise and impactful messages (max 700 characters)
Colors: Choose high readability combinations (adequate contrast)
Images: Use 9:16 resolution for best mobile viewing
Videos: Keep between 10-25 seconds for better engagement
Frequency: Post status regularly but avoid spam
Timing: Publish during your contacts' most active hours
Content: Vary between motivational texts, images, and videos
Quality: Always use high-quality and well-edited media

✨ Pro Tip: Combine vibrant colored texts, high-quality images, and short dynamic videos to maximize engagement with your WhatsApp status!

🚀 Get Started in Minutes

Deploy with Docker

Create User

Connect WhatsApp

Start Messaging

📋 API Overview

🌐 Base URL

📊 API Endpoints Overview

🔐 Authentication

🎫 Token Types

1. User Token

2. Admin Token

📨 Request Format

📱 Session Management

POST /session/connect

📝 Request Body:

📋 Parameters:

✅ Success Response:

GET /session/qr

✅ Success Response:

GET /session/status

✅ Success Response:

📊 Status Values:

POST /session/pairphone

📝 Request Body:

POST /session/disconnect

✅ Success Response:

POST /session/logout

✅ Success Response:

💬 Messaging

POST /chat/send/text

📝 Request Body:

📋 Parameters:

POST /chat/send/image

📝 Request Body:

📋 Supported Formats:

POST /chat/send/audio

📝 Request Body:

📋 Parameters:

🎵 Supported Formats:

POST /chat/send/document

📝 Request Body:

📄 Supported Document Types:

POST /chat/send/video

📝 Request Body:

🎬 Supported Video Formats:

POST /chat/send/buttons

📝 Request Body:

POST /chat/send/list

📝 Request Body:

POST /chat/send/poll

📝 Request Body:

POST /chat/send/text/mention

📝 Request Body:

POST /chat/send/text/mention-all

📝 Request Body:

🔧 Message Operations

POST /chat/delete

📝 Request Body:

POST /chat/send/edit

📝 Request Body:

POST /chat/react

📝 Request Body:

😀 Supported Reactions:

👥 Group Management

POST /group/create

📝 Request Body:

✅ Success Response:

GET /group/list?ignoreParticipants=true

✅ Success Response:

GET /group/[email protected]

📋 Query Parameters:

POST /group/updateparticipants

📝 Request Body:

🔧 Available Actions:

POST /group/name

📝 Request Body:

POST /group/topic

📝 Request Body:

POST /group/photo