aldinokemal/go-whatsapp-web-multidevice v8.0.0

on GitHub

What's New in v8.0.0

🚀 Major Release: Multi-Device Support

This major release introduces the ability to manage multiple WhatsApp accounts in a single server instance, along with significant architectural improvements and new APIs.

✨ New Features & Enhancements

Multi-Device Management

• Multiple WhatsApp Accounts: Connect and manage multiple WhatsApp accounts simultaneously on a single server
• Device Management API: New /devices endpoints for complete device lifecycle management
  • GET /devices - List all registered devices
  • POST /devices - Add a new device
  • GET /devices/{device_id} - Get device details
  • DELETE /devices/{device_id} - Remove a device
  • POST /devices/{device_id}/login - Login with QR code
  • POST /devices/{device_id}/login-with-code - Login with pairing code
  • POST /devices/{device_id}/logout - Logout device
  • POST /devices/{device_id}/reconnect - Reconnect device
• Device Scoping: All REST API calls and WebSocket connections now support device-specific routing via X-Device-ID header
• Device Manager UI: New visual interface for managing multiple devices
• Auto-Connect All Devices: Server automatically reconnects all available devices on startup

New API Endpoints

• Connection Status: GET /app/status to check device connection and login status
• Media Download: GET /message/{message_id}/download for downloading media from messages
• APP_HOST Configuration: New APP_HOST environment variable to specify server binding address

Enhanced Webhook System

• Device Identification: All webhook payloads now include device_id for multi-device identification
• Consistent Payload Structure: Updated webhook format with event type and device context
• Improved Event Handling: Better JID normalization and sender resolution

🔧 Refactoring & Improvements

Architecture Overhaul

• Modular Code Structure: Split monolithic init.go into focused modules:
  • device_manager.go - Device lifecycle management
  • device_instance.go - Individual device state
  • event_handler.go - Centralized event handling
  • history_sync.go - Message history synchronization
  • cleanup.go - Database cleanup operations
  • auto_reply.go - Auto-reply functionality
  • jid_utils.go - JID normalization utilities
• Context-Based Client Access: Refactored services to use WhatsApp client from context
• Database Compatibility: Replaced SQLite-specific ON CONFLICT with cross-database compatible patterns
• Race Condition Prevention: Enhanced database cleanup with proper locking
• Goroutine Leak Prevention: Added timeouts and buffered channels for QR code handling

CI/CD Improvements

• Docker Build Updates: Upgraded docker/build-push-action to v6
• New Workflow: Added workflow for setting latest Docker image tag
• Cleanup: Removed obsolete code review workflows

🎯 What This Means for You

For Multi-Account Users

• Single Server, Multiple Accounts: Run one server instance to manage all your WhatsApp accounts
• Isolated Sessions: Each device maintains its own session and message history
• Centralized Management: UI dashboard for managing all devices
• Scalable Architecture: Add or remove accounts without server restart

For API Users

• Device Selection: Use X-Device-ID header to target specific devices
• Backward Compatible: Without header, uses default device behavior
• Enhanced Webhooks: Identify which device triggered each webhook event
• New Endpoints: Check connection status and download media programmatically

For Webhook Users

• Device Context: Know exactly which account received/sent each message
• Consistent Format: Standardized payload structure across all events
• Better Debugging: Improved event metadata for troubleshooting

⚠️ Breaking Changes

API Version

• Version Bump: API version updated to 8.0.0
• Webhook Payload Changes: New top-level structure includes event_type and device_id

Migration Guide

Webhook Handlers:
Update your webhook handlers to handle the new payload structure:

{
  "event_type": "message",
  "device_id": "device-123",
  "data": {
    // existing payload fields
  }
}

API Calls with Multiple Devices:
Add X-Device-ID header to target specific devices:

curl -X POST "http://localhost:3000/send/message" \
  -H "X-Device-ID: device-123" \
  -H "Content-Type: application/json" \
  -d '{"phone": "6281234567890", "message": "Hello"}'

Configuration Examples

Add APP_HOST Configuration:

APP_HOST=0.0.0.0
APP_PORT=3000

Multi-Device Setup:

# Start server
./whatsapp rest

# Add first device via API
curl -X POST "http://localhost:3000/devices" \
  -H "Content-Type: application/json" \
  -d '{"id": "account-1"}'

# Login first device
curl -X POST "http://localhost:3000/devices/account-1/login"

# Add second device
curl -X POST "http://localhost:3000/devices" \
  -H "Content-Type: application/json" \
  -d '{"id": "account-2"}'

# Login second device with pairing code
curl -X POST "http://localhost:3000/devices/account-2/login-with-code" \
  -H "Content-Type: application/json" \
  -d '{"phone": "6281234567890"}'

Send Message to Specific Device:

curl -X POST "http://localhost:3000/send/message" \
  -H "X-Device-ID: account-1" \
  -H "Content-Type: application/json" \
  -d '{"phone": "6281234567890", "message": "Hello from account 1"}'

Docker Compose with Multi-Device:

services:
  whatsapp:
    image: aldinokemal/go-whatsapp-web-multidevice:v8.0.0
    environment:
      - APP_HOST=0.0.0.0
      - APP_PORT=3000
      - WHATSAPP_WEBHOOK=https://your-webhook.com/handler
    volumes:
      - ./data:/app/storages
    ports:
      - "3000:3000"

Summary

Version 8.0.0 is a major release that introduces multi-device support, allowing you to manage multiple WhatsApp accounts from a single server instance. The release includes new device management APIs, enhanced webhook payloads with device identification, architectural improvements for better maintainability, and cross-database compatibility. While there are breaking changes in the webhook payload structure, migration is straightforward and the release maintains backward compatibility for single-device usage.

What's Changed

• feat: implement multi devices in c33b46a
• refactor: update context handling for WhatsApp client across services in 53b56c2
• feat: enhance device management and auto-connect functionality in 272ff3e
• refactor: enhance webhook payload structure and event handling in 582ee44
• feat: add APP_HOST configuration for server binding in 968fb55
• chore: update Docker build-push action and clean up workflows in f306254
• feat: introduce multi-device support and device management API in eda4795
• feat: update homepage in cc2509d
• refactor(chatstorage): replace ON CONFLICT with update-then-insert pattern in 8da6ee3
• refactor: improve database cleanup and event handling in f66525b
• feat: update dependency in a03d389
• feat: enhance API documentation and add new endpoints in fec26a2
• feat: update all dependency in 1cf3057
• feat: support multi account in 1b762b8
• feat: update mod golang in fe2ca83

Full Changelog: v7.10.2...v8.0.0