Skip to content

chatwoot-br/go-whatsapp-web-multidevice

BranchesTags
 
 

Repository files navigation

GoWA Logo

Golang WhatsApp - Built with Go for efficient memory use

Patreon If you're using this tools to generate income, consider supporting its development by becoming a Patreon member! Your support helps ensure the library stays maintained and receives regular updates!

release version Build Image Binary Release

Support for ARM & AMD Architecture along with MCP Support

Download:

Support n8n package (n8n.io)

  • n8n package
  • Go to Settings -> Community Nodes -> Input @aldinokemal2104/n8n-nodes-gowa -> Install

Breaking Changes

  • v6
    • For REST mode, you need to run <binary> rest instead of <binary>
      • for example: ./whatsapp rest instead of ./whatsapp
    • For MCP mode, you need to run <binary> mcp
      • for example: ./whatsapp mcp
  • v7
    • Starting version 7.x we are using goreleaser to build the binary, so you can download the binary from release

Feature

  • Send WhatsApp message via http API, docs/reference/api/openapi.yaml for more details

  • Interactive API Documentation with Swagger UI - Built-in Swagger UI for Admin API accessible at /swagger endpoint

  • MCP (Model Context Protocol) Server Support - Integrate with AI agents and tools using standardized protocol

  • Mention someone

    • @phoneNumber
    • example: Hello @628974812XXXX, @628974812XXXX

  • Post Whatsapp Status

  • Send Stickers - Automatically converts images to WebP sticker format

    • Supports JPG, JPEG, PNG, WebP, and GIF formats
    • Automatic resizing to 512x512 pixels
    • Preserves transparency for PNG images

  • Compress image before send

  • Compress video before send

  • Change OS name become your app (it's the device name when connect via mobile)

    • --os=Chrome or --os=MyApplication

  • Basic Auth (able to add multi credentials)

    • --basic-auth=kemal:secret,toni:password,userName:secretPassword, or you can simplify
    • -b=kemal:secret,toni:password,userName:secretPassword

  • Subpath deployment support

    • --base-path="/gowa" (allows deployment under a specific path like /gowa/sub/path)

  • Customizable port and debug mode

    • --port 8000
    • --debug true

  • Auto reply message

    • --autoreply="Don't reply this message"

  • Auto mark read incoming messages

    • --auto-mark-read=true (automatically marks incoming messages as read)

  • Auto download media from incoming messages

    • --auto-download-media=false (disable automatic media downloads, default: true)

  • Webhook for received message

    • --webhook="http://yourwebhook.site/handler", or you can simplify
    • -w="http://yourwebhook.site/handler"
    • for more detail, see Webhook Documentation

  • Webhook Secret Our webhook will be sent to you with an HMAC header and a sha256 default key secret.

    You may modify this by using the option below:

    • --webhook-secret="secret"

  • Webhook Documentation For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Guides and Webhook Reference

  • Webhook TLS Configuration

    If you encounter TLS certificate verification errors when using webhooks (e.g., with Cloudflare tunnels or self-signed certificates):

    tls: failed to verify certificate: x509: certificate signed by unknown authority

    You can disable TLS certificate verification using:

    • --webhook-insecure-skip-verify=true
    • Or environment variable: WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true

    Security Warning: This option disables TLS certificate verification and should only be used in:

    • Development/testing environments
    • Cloudflare tunnels (which provide their own security layer)
    • Internal networks with self-signed certificates

    For production environments, it's strongly recommended to use proper SSL certificates (e.g., Let's Encrypt) instead of disabling verification.

Configuration

You can configure the application using either command-line flags (shown above) or environment variables. Configuration can be set in three ways (in order of priority):

  1. Command-line flags (highest priority)
  2. Environment variables
  3. .env file (lowest priority)

Environment Variables

You can configure the application using environment variables. Configuration can be set in three ways (in order of priority):

  1. Command-line flags (highest priority)
  2. Environment variables
  3. .env file (lowest priority)

To use environment variables:

  1. Copy .env.example to .env in your project root (cp src/.env.example src/.env)
  2. Modify the values in .env according to your needs
  3. Or set the same variables as system environment variables

Available Environment Variables

Variable Description Default Example
APP_PORT Application port 3000 APP_PORT=8080
APP_DEBUG Enable debug logging false APP_DEBUG=true
APP_OS OS name (device name in WhatsApp) Chrome APP_OS=MyApp
APP_BASIC_AUTH Basic authentication credentials - APP_BASIC_AUTH=user1:pass1,user2:pass2
APP_BASE_PATH Base path for subpath deployment - APP_BASE_PATH=/gowa
APP_TRUSTED_PROXIES Trusted proxy IP ranges for reverse proxy - APP_TRUSTED_PROXIES=0.0.0.0/0
DB_URI Database connection URI file:storages/whatsapp.db?_foreign_keys=on DB_URI=postgres://user:pass@host/db
WHATSAPP_AUTO_REPLY Auto-reply message - WHATSAPP_AUTO_REPLY="Auto reply message"
WHATSAPP_AUTO_MARK_READ Auto-mark incoming messages as read false WHATSAPP_AUTO_MARK_READ=true
WHATSAPP_AUTO_DOWNLOAD_MEDIA Auto-download media from incoming messages true WHATSAPP_AUTO_DOWNLOAD_MEDIA=false
WHATSAPP_WEBHOOK Webhook URL(s) for events (comma-separated) - WHATSAPP_WEBHOOK=https://webhook.site/xxx
WHATSAPP_WEBHOOK_SECRET Webhook secret for validation secret WHATSAPP_WEBHOOK_SECRET=super-secret-key
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY Skip TLS verification for webhooks (insecure) false WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true
WHATSAPP_ACCOUNT_VALIDATION Enable account validation true WHATSAPP_ACCOUNT_VALIDATION=false
WHATSAPP_CHAT_STORAGE Enable chat storage true WHATSAPP_CHAT_STORAGE=false

For the Admin API implementation details and complete environment variable mappings for per-instance configuration, see Admin API Guide.

Note: Command-line flags will override any values set in environment variables or .env file.

  • For more command ./whatsapp --help

Requirements

System Requirements

  • Go 1.24.0 or higher (for building from source)
  • FFmpeg (for media processing)

Platform Support

  • Linux (x86_64, ARM64)
  • macOS (Intel, Apple Silicon)
  • Windows (x86_64) - WSL recommended

Dependencies (without docker)

  • Mac OS:
    • brew install ffmpeg
    • export CGO_CFLAGS_ALLOW="-Xpreprocessor"
  • Linux:
    • sudo apt update
    • sudo apt install ffmpeg
  • Windows (not recomended, prefer using WSL):

How to use

Development Environment (Recommended)

For the best development experience with Admin API support:

  1. VS Code Dev Container (Includes everything pre-configured):

    • Clone this repo: git clone https://github.com/chatwoot-br/go-whatsapp-web-multidevice
    • Open in VS Code
    • When prompted, click "Reopen in Container"
    • Wait for the container to build and setup automatically
    • Use ./.devcontainer/dev.sh help for available commands
    • See .devcontainer/README.md for detailed development guide

  2. Features included in Dev Container:

    • ✅ Go 1.24+ with all tools
    • ✅ FFmpeg pre-installed
    • ✅ Supervisord configured and running
    • ✅ Admin API ready to use
    • ✅ Development helper scripts
    • ✅ Port forwarding configured
    • ✅ Environment variables pre-set

Basic

  1. Clone this repo: git clone https://github.com/chatwoot-br/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. run go run . rest (for REST API mode)
  5. Open http://localhost:3000

Helm chart for Admin API

This repository includes a Helm chart that deploys the Admin API and a supervisord sidecar used to manage WhatsApp instances. See charts/README.md for consolidated configuration, deployment and debugging instructions.

Docker (you don't need to install in required)

  1. Clone this repo: git clone https://github.com/chatwoot-br/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run docker-compose up -d --build
  4. open http://localhost:3000

Build your own binary

  1. Clone this repo git clone https://github.com/chatwoot-br/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. run
    1. Linux & MacOS: go build -o whatsapp
    2. Windows (CMD / PowerShell): go build -o whatsapp.exe
  5. run
    1. Linux & MacOS: ./whatsapp rest (for REST API mode)
      1. run ./whatsapp --help for more detail flags
    2. Windows: .\whatsapp.exe rest (for REST API mode)
      1. run .\whatsapp.exe --help for more detail flags
  6. open http://localhost:3000 in browser

Admin API (Multi-Instance Management)

For managing multiple WhatsApp instances:

  1. Using Dev Container (easiest):

    ./.devcontainer/dev.sh start-admin
./.devcontainer/dev.sh create 3001

  2. Manual setup:

    • Install and configure supervisord
    • Set required environment variables (see .src/.env.dev)
    • Run: go run . admin --port 8088
    • See Admin API Guide for details

Note: The Admin API supports all environment variables listed above. Use GOWA_* prefixed versions to configure defaults for instances (e.g., GOWA_DEBUG=true, GOWA_WEBHOOK=https://webhook.site/xxx). All instances created through the Admin API will inherit these settings and support the full feature set of standalone GOWA instances.

MCP Server (Model Context Protocol)

This application can also run as an MCP server, allowing AI agents and tools to interact with WhatsApp through a standardized protocol.

  1. Clone this repo git clone https://github.com/chatwoot-br/go-whatsapp-web-multidevice
  2. Open the folder that was cloned via cmd/terminal.
  3. run cd src
  4. run go run . mcp or build the binary and run ./whatsapp mcp
  5. The MCP server will start on http://localhost:8080 by default

MCP Server Options

  • --host localhost - Set the host for MCP server (default: localhost)
  • --port 8080 - Set the port for MCP server (default: 8080)

Available MCP Tools

The WhatsApp MCP server provides comprehensive tools for AI agents to interact with WhatsApp through a standardized protocol. Below is the complete list of available tools:

📱 Connection Management
  • whatsapp_connection_status - Check whether the WhatsApp client is connected and logged in
  • whatsapp_login_qr - Initiate QR code based login flow with image output
  • whatsapp_login_with_code - Generate pairing code for multi-device login using phone number
  • whatsapp_logout - Sign out the current WhatsApp session
  • whatsapp_reconnect - Attempt to reconnect to WhatsApp using stored session
💬 Messaging & Communication
  • whatsapp_send_text - Send text messages with reply and forwarding support
  • whatsapp_send_contact - Send contact cards with name and phone number
  • whatsapp_send_link - Send links with custom captions
  • whatsapp_send_location - Send location coordinates (latitude/longitude)
  • whatsapp_send_image - Send images with captions, compression, and view-once options
  • whatsapp_send_sticker - Send stickers with automatic WebP conversion (supports JPG/PNG/GIF)
📋 Chat & Contact Management
  • whatsapp_list_contacts - Retrieve all contacts in your WhatsApp account
  • whatsapp_list_chats - Get recent chats with pagination and search filters
  • whatsapp_get_chat_messages - Fetch messages from specific chats with time/media filtering
  • whatsapp_download_message_media - Download images/videos from messages
👥 Group Management
  • whatsapp_group_create - Create new groups with optional initial participants
  • whatsapp_group_join_via_link - Join groups using invite links
  • whatsapp_group_leave - Leave groups by group ID
  • whatsapp_group_participants - List all participants in a group
  • whatsapp_group_manage_participants - Add, remove, promote, or demote group members
  • whatsapp_group_invite_link - Get or reset group invite links
  • whatsapp_group_info - Get detailed group information
  • whatsapp_group_set_name - Update group display name
  • whatsapp_group_set_topic - Update group description/topic
  • whatsapp_group_set_locked - Toggle admin-only group info editing
  • whatsapp_group_set_announce - Toggle announcement-only mode
  • whatsapp_group_join_requests - List pending join requests
  • whatsapp_group_manage_join_requests - Approve or reject join requests

MCP Endpoints

  • SSE endpoint: http://localhost:8080/sse
  • Message endpoint: http://localhost:8080/message

MCP Configuration

Make sure you have the MCP server running: ./whatsapp mcp

For AI tools that support MCP with SSE (like Cursor), add this configuration:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Production Mode REST (docker)

Using Docker Hub:

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages ghcr.io/chatwoot-br/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

Using GitHub Container Registry:

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages ghcr.io/chatwoot-br/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

Production Mode REST (docker compose)

create docker-compose.yml file with the following configuration:

Using Docker Hub:

services:
  whatsapp:
    image: ghcr.io/chatwoot-br/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

Using GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/chatwoot-br/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

or with env file (Docker Hub):

services:
  whatsapp:
    image: ghcr.io/chatwoot-br/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

or with env file (GitHub Container Registry):

services:
  whatsapp:
    image: ghcr.io/chatwoot-br/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

Production Mode (binary)

You can fork or edit this source code !

Current API

MCP (Model Context Protocol) API

  • MCP server provides standardized tools for AI agents to interact with WhatsApp
  • Supports Server-Sent Events (SSE) transport
  • Available tools: whatsapp_send_text, whatsapp_send_contact, whatsapp_send_link, whatsapp_send_location
  • Compatible with MCP-enabled AI tools and agents

HTTP REST API

Feature Menu Method URL
✅ Login with Scan QR GET /app/login
✅ Login With Pair Code GET /app/login-with-code
✅ Logout GET /app/logout
✅ Reconnect GET /app/reconnect
✅ Devices GET /app/devices
✅ User Info GET /user/info
✅ User Avatar GET /user/avatar
✅ User Change Avatar POST /user/avatar
✅ User Change PushName POST /user/pushname
✅ User My Groups GET /user/my/groups
✅ User My Newsletter GET /user/my/newsletters
✅ User My Privacy Setting GET /user/my/privacy
✅ User My Contacts GET /user/my/contacts
✅ User Check GET /user/check
✅ User Business Profile GET /user/business-profile
✅ Send Message POST /send/message
✅ Send Image POST /send/image
✅ Send Audio POST /send/audio
✅ Send File POST /send/file
✅ Send Video POST /send/video
✅ Send Sticker POST /send/sticker
✅ Send Contact POST /send/contact
✅ Send Link POST /send/link
✅ Send Location POST /send/location
✅ Send Poll / Vote POST /send/poll
✅ Send Presence POST /send/presence
✅ Send Chat Presence (Typing Indicator) POST /send/chat-presence
✅ Revoke Message POST /message/:message_id/revoke
✅ React Message POST /message/:message_id/reaction
✅ Delete Message POST /message/:message_id/delete
✅ Edit Message POST /message/:message_id/update
✅ Read Message (DM) POST /message/:message_id/read
✅ Star Message POST /message/:message_id/star
✅ Unstar Message POST /message/:message_id/unstar
✅ Join Group With Link POST /group/join-with-link
✅ Group Info From Link GET /group/info-from-link
✅ Group Info GET /group/info
✅ Leave Group POST /group/leave
✅ Create Group POST /group
✅ List Participants in Group GET /group/participants
✅ Add Participants in Group POST /group/participants
✅ Remove Participant in Group POST /group/participants/remove
✅ Promote Participant in Group POST /group/participants/promote
✅ Demote Participant in Group POST /group/participants/demote
✅ Export Group Participants (CSV) GET /group/participants/export
✅ List Requested Participants in Group GET /group/participant-requests
✅ Approve Requested Participant in Group POST /group/participant-requests/approve
✅ Reject Requested Participant in Group POST /group/participant-requests/reject
✅ Set Group Photo POST /group/photo
✅ Set Group Name POST /group/name
✅ Set Group Locked POST /group/locked
✅ Set Group Announce POST /group/announce
✅ Set Group Topic POST /group/topic
✅ Get Group Invite Link GET /group/invite-link
✅ Unfollow Newsletter POST /newsletter/unfollow
✅ Get Chat List GET /chats
✅ Get Chat Messages GET /chat/:chat_jid/messages
✅ Label Chat POST /chat/:chat_jid/label
✅ Pin Chat POST /chat/:chat_jid/pin
✅ Set Disappearing Messages POST /chat/:chat_jid/disappearing 
✅ = Available
❌ = Not Available Yet

User Interface

MCP UI

  • Setup MCP (tested in cursor) Setup MCP
  • Test MCP Test MCP
  • Successfully setup MCP Success MCP

HTTP REST API UI

Description Image
Homepage Homepage
Login Login
Login With Code Login With Code
Send Message Send Message
Send Image Send Image
Send File Send File
Send Video Send Video
Send Sticker Send Sticker
Send Contact Send Contact
Send Location Send Location
Send Audio Send Audio
Send Poll Send Poll
Send Presence Send Presence
Send Link Send Link
My Group My Group
Group Info From Link Group Info From Link
Create Group Create Group
Join Group with Link Join Group with Link
Manage Participant Manage Participant
My Newsletter My Newsletter
My Contacts My Contacts
Business Profile Business Profile

Mac OS NOTE

  • Please do this if you have an error (invalid flag in pkg-config --cflags: -Xpreprocessor) export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Admin API & Swagger UI

The application includes an Admin API for managing multiple GOWA instances with built-in Swagger UI documentation.

Admin API Features

  • Create, list, update, and delete GOWA instances
  • Health and readiness endpoints
  • Supervisor-based instance management
  • Authentication via bearer token

Swagger UI Integration

  • Interactive API documentation at /swagger endpoint
  • Real-time testing of Admin API endpoints
  • Automatic OpenAPI specification serving
  • CORS-enabled for browser access

Kubernetes/Helm Deployment

# Deploy with Swagger UI enabled
helm install my-release charts/gowa --set swaggerUI.enabled=true

# Access Swagger UI (after port forwarding)
kubectl port-forward svc/my-release-gowa 8080:8080
open http://localhost:8080/swagger

For more details, see:

📚 Documentation

Complete documentation is available in the docs/ directory. Here's where to find what you need:

Quick Start

How-To Guides

API Reference

For Developers

Operations

Postmortems

Start here: docs/README.md - Comprehensive documentation index with persona-based navigation

Important

  • This project is unofficial and not affiliated with WhatsApp.
  • Please use official WhatsApp API to avoid any issues.
  • We only able to run MCP or REST API, this is limitation from whatsmeow library. independent MCP will be available in the future.

About

API for Whatsapp Web Multi Device Version, Support UI & Webhook

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 13

gowa-7.11.2 Latest
Dec 19, 2025
+ 12 releases

Packages

 
 
 

Languages

  • Go 68.8%
  • JavaScript 26.3%
  • Shell 1.9%
  • HTML 1.5%
  • CSS 1.0%
  • Dockerfile 0.3%
  • Smarty 0.2%