ghiovanidebrians/go-whatsapp-multi-session-rest-api repository overview

⁠Go WhatsApp Multi-Session REST API

⁠📚 API Documentation

⁠📋 Table of Contents

• Features⁠
• Requirements⁠
• Installation⁠
• Configuration⁠
• How to Use⁠
• API Endpoints⁠
• Authentication Flow⁠
• Environment Variables⁠
• Contributing⁠
• License⁠
• Disclaimer⁠

⁠✨ Features

• 🔐 Multi-Session Support - Handle multiple WhatsApp accounts simultaneously
• 📱 Multi-Device Support - Up to 4 devices per WhatsApp account
• 🎫 JWT Token Authentication - Stateless, high-performance authentication for 1000+ sessions
• 🚀 120+ Production-Ready Endpoints - Full whatsmeow coverage including all media types
• 📨 Rich Messaging - Text, images, videos, audio, stickers, locations, contacts, documents
• 📊 Polls - Create polls, vote, and receive real-time results via webhooks
• 📰 Newsletter/Channels - Full channel support - create, follow, message, react, TOS acceptance
• 📱 Status/Stories - Post and manage WhatsApp Status updates
• 📞 Call Handling - Reject incoming WhatsApp calls programmatically
• 💼 Business Profiles - Get business profiles and resolve wa.me/message links
• 🤖 WhatsApp AI Bots - List and get profiles of available WhatsApp bots
• 📲 Contact QR Codes - Generate and resolve contact QR links
• 👁️ Presence Subscriptions - Subscribe to user online/offline/typing status
• 🌳 RESTful Architecture - Hierarchical resource-based routes
• 👥 Group Management - Full CRUD for groups, participants, admins, community unlinking
• 🔄 Message Operations - Edit, react, delete, reply, forward, mark read
• 📊 Presence & Status - Online status, typing indicators, disappearing messages, passive mode
• 🔄 App State Synchronization - Fetch, send, and manage app state patches
• 📜 Message History Sync - Request and download message history on demand
• 🌐 Per-Device Proxy - Configure HTTP proxy per device (overrides global setting)
• 📴 Passive Mode - Read-only mode to reduce bandwidth usage
• 🔄 Advanced Media Retry - Handle media retry notifications automatically
• 🔁 WA Web Version Auto-Refresh - Auto-refreshes WhatsApp Web version to handle "client outdated" during pairing
• 🧯 Startup Reconnect Storm Protection - Concurrency limit + jitter + retry/backoff for 100s of sessions
• 🔔 Push Notifications - Register for push notifications (reuses webhook system)
• 🪝 Webhook Integration - 35+ event types with real-time notifications and retry support
• 🏗️ Production Ready - Docker support, environment configuration, logging
• 📖 OpenAPI/Swagger - Interactive API documentation at /docs/
• 🔑 Admin Dashboard Ready - Manage API keys and devices with admin endpoints
• 📈 Admin Dashboard APIs - System stats, health monitoring, device status, batch reconnect

⁠💡 Why Teams Choose This API

• Stateless speed: JWT-first flow eliminates per-request database lookups for messaging throughput.
• Auto-resilience: Devices restore and reconnect on startup with health checks for steady uptime (includes "client outdated" WA Web version auto-refresh).
• Operational control: Admin endpoints manage API keys, devices, and webhook delivery visibility.
• Webhook reliability: Built-in workers, retries, and per-device quotas keep downstream systems in sync.
• Deployment-ready: Docker-compose defaults, environment-first config, and structured logging out of the box.
• Developer experience: Full Swagger (JSON/YAML) at /docs/, with consistent JSON error envelopes and request IDs for tracing.

⁠📋 Requirements

⁠System Requirements

• Go: 1.24 or higher (matches go.mod 1.24.5; use the latest stable toolchain)
• PostgreSQL: Primary datastore for sessions and app metadata
• FFmpeg: For media processing (optional but recommended)

⁠Platform Support

• ✅ Linux (x86_64, ARM64)
• ✅ macOS (Intel, Apple Silicon)
• ✅ Windows (x86_64) - WSL recommended for better compatibility

⁠Dependencies

⁠Mac OS

brew install ffmpeg
export CGO_CFLAGS_ALLOW="-Xpreprocessor"

⁠Linux (Debian/Ubuntu)

sudo apt update
sudo apt install -y ffmpeg postgresql-client

⁠Windows

• Install FFmpeg from official website⁠
• Add FFmpeg to environment PATH
• Note: WSL (Windows Subsystem for Linux) is recommended

⁠🚀 Installation

⁠Using Docker (Recommended)

⁠Images & Tags

This project publishes container images to:

• Docker Hub (stable releases): ghiovanidebrians/go-whatsapp-multi-session-rest-api
  • Tags: vX.Y.Z, X.Y, and latest (updated on each new release tag)
• GitHub Container Registry (edge/dev): ghcr.io/gdbrns/go-whatsapp-multi-session-rest-api
  • Tags: latest (on main/master), sha-..., and also vX.Y.Z on release tags

Examples:

# Stable (recommended for production)
docker pull ghiovanidebrians/go-whatsapp-multi-session-rest-api:latest
docker pull ghiovanidebrians/go-whatsapp-multi-session-rest-api:v1.2.0

# Edge/dev (latest main)
docker pull ghcr.io/gdbrns/go-whatsapp-multi-session-rest-api:latest

⁠Docker Compose

version: '3.8'

services:
  whatsapp-api:
    image: ghiovanidebrians/go-whatsapp-multi-session-rest-api:latest
    container_name: whatsapp-api
    restart: always
    ports:
      - "7001:7001"
    environment:
      - ADMIN_SECRET_KEY=your-super-secret-admin-key-change-this
      - JWT_SECRET_KEY=your-jwt-secret-key-at-least-32-chars
      - SERVER_PORT=7001
      - WHATSAPP_DATASTORE_TYPE=postgres
      - WHATSAPP_DATASTORE_URI=postgres://whatsapp:secret@postgres:5432/whatsapp?sslmode=disable

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=whatsapp
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=whatsapp
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Then run:

docker-compose up -d

⁠From Source

# Clone repository
git clone https://github.com/gdbrns/go-whatsapp-multi-session-rest-api.git
cd go-whatsapp-multi-session-rest-api

# Install dependencies
go mod download

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Build
go build -o whatsapp-api cmd/main/main.go

# Run
./whatsapp-api

⁠⚙️ Configuration

Configuration can be set via:

1. Environment variables (highest priority)
2. .env file in the application directory
3. Default values (lowest priority)

See Environment Variables⁠ section for all options.

⁠📖 How to Use

⁠1. Start the Application

# Using Docker
docker-compose up -d

# From source
go run cmd/main/main.go

⁠2. Access API Documentation

Online Documentation (Recommended):

• 🌐 bump.sh/gdbrns/doc/go-whatsapp-multi-session-rest⁠ - Interactive API explorer with examples

Local Documentation (when running):

• Swagger UI: http://localhost:7001/docs/
• OpenAPI JSON: http://localhost:7001/docs/swagger.json
• OpenAPI YAML: http://localhost:7001/docs/swagger.yaml

⁠3. Create an API Key (Admin)

# Create a new API key for a customer
curl -X POST "http://localhost:7001/admin/api-keys" \
  -H "X-Admin-Secret: YOUR_ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Acme Corp",
    "max_devices": 10
  }'

# Response:
# {
#   "status": true,
#   "code": 201,
#   "data": {
#     "api_key": "wam_a1b2c3d4e5f6g7h8..."
#   }
# }

⁠4. Create a Device (Customer)

# Create a new device using API key
curl -X POST "http://localhost:7001/devices" \
  -H "X-API-Key: wam_a1b2c3d4e5f6g7h8..." \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "Production Bot 1"
  }'

# Response (SAVE BOTH device_secret AND token!):
# {
#   "device_id": "550e8400-e29b-41d4-a716-446655440000",
#   "device_secret": "a1b2c3d4e5f6g7h8...",
#   "token": "eyJhbGciOiJIUzI1NiIs...",
#   "message": "Use the token in Authorization header for all API calls."
# }

⁠5. Login via QR Code

# Generate QR code for device login (using JWT token)
curl -X POST "http://localhost:7001/devices/me/login" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "output=json"

# Scan the QR code with your WhatsApp mobile app:
# WhatsApp > Settings > Linked Devices > Link a Device

⁠6. Send a Message

# Send text message (using JWT token)
curl -X POST "http://localhost:7001/chats/[email protected]/messages" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from WhatsApp API!"
  }'

# Send image
curl -X POST "http://localhost:7001/chats/[email protected]/images" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@/path/to/image.jpg" \
  -F "caption=Check this out!"

# Send document (with optional caption)
curl -X POST "http://localhost:7001/chats/[email protected]/documents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@/path/to/document.pdf" \
  -F "filename=document.pdf" \
  -F "caption=Here is the document."

⁠7. Regenerate Token (When Needed)

# Regenerate JWT token using device credentials
# This invalidates all previous tokens
curl -X POST "http://localhost:7001/devices/token" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_secret": "a1b2c3d4e5f6g7h8..."
  }'

# Response:
# {
#   "device_id": "550e8400-e29b-41d4-a716-446655440000",
#   "token": "eyJhbGciOiJIUzI1NiIs...(NEW TOKEN)",
#   "message": "Token regenerated successfully. All previous tokens are now invalid."
# }

⁠8. Webhook Configuration

# Create a webhook
curl -X POST "http://localhost:7001/webhooks" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "connection.connected"]
  }'

⁠Webhook Events Summary (31 Event Types)

📖 See docs/WEBHOOK_EVENTS.md⁠ for detailed event payloads.

⁠📚 API Endpoints

⁠All Endpoints

Organized by category with most commonly used endpoints first. All paths honor optional HTTP_BASE_URL (prefix not shown below). Total: 122 endpoints (123 when HTTP_BASE_URL is set because the index path is registered with and without a trailing slash).

Input & validation notes

• Phone numbers must be in international format (no leading 0, digits only, 6-16 chars). Requests with invalid/unknown numbers return 4xx.
• chat_jid/sender_jid must be provided for message operations; missing values return 4xx.
• All errors are JSON with {status, code, message, data?} (and error for compatibility).
• Every response carries X-Request-ID; you can supply your own header to correlate logs.

Authentication Types:

• Admin: X-Admin-Secret header
• API-Key: X-API-Key header
• JWT: Authorization: Bearer <token> header
• -: No authentication required

⁠🔐 Authentication Flow

This API uses a JWT Token authentication system optimized for high-volume operations (1000+ sessions with non-stop messaging).

⁠Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                           ADMIN (X-Admin-Secret)                            │
├─────────────────────────────────────────────────────────────────────────────┤
│  GET  /admin/stats             → System statistics (API keys, devices)      │
│  GET  /admin/health            → System health (memory, uptime, DB status)  │
│  GET  /admin/whatsapp/version   → WhatsApp Web version status                │
│  P