go-whatsapp-web-multidevice

If you're using this tool to generate income, consider supporting its development by becoming a Patreon member!

Your support helps ensure the project stays maintained and receives regular updates!

ARM, AMD64, and MCP Support

Download:

• Release
• Docker Hub
• GitHub Container Registry

n8n Community Node

• n8n package
• Go to Settings → Community Nodes, enter `@aldinokemal2104/n8n-nodes-gowa`, and select Install.

Breaking Changes

• `v6`
  • REST mode requires ` rest` instead of ``.
    • Example: `./whatsapp rest` instead of `./whatsapp`.
  • MCP mode required ` mcp`.
    • Example: `./whatsapp mcp`.
• `v7`
  • Starting with version 7.x, binaries are built with GoReleaser and can be downloaded from the

latest release.

• `v8`
  • Multi-device support: You can now connect and manage multiple WhatsApp accounts simultaneously in a single

server instance.

(for example, gowa-ui) hosted on another origin can call the API directly.

`GET /app/info` exposes the version and media size limits. Because browsers cannot set headers on WebSocket

connections, pass `/ws?device_id=&authorization=` when Basic Auth is enabled

(use TLS—the credential is visible in the URL).

device received the event:

{
      "event": "message",
      "device_id": "628123456789@s.whatsapp.net",
      "payload": { ... }
    }

• `v9`
  • MCP and API are unified under `rest`: MCP is no longer a separate mode or process. Run

`./whatsapp rest` to serve both the REST API and MCP; MCP is available at `/mcp` (no standalone `mcp`

subcommand). See MCP Server (Model Context Protocol) for migration

details.

aldinokemal/gowa-ui and ships as a single self-contained

`gowa-ui.html`. The server downloads the latest dashboard release at startup, verifies its SHA-256 digest,

caches it under `storages/ui/`, and serves it at `/`.

See Web dashboard (gowa-ui) for the `APP_UI_*` settings, supply-chain pinning,

and air-gapped deployment.

Features

• Send WhatsApp messages through the HTTP API. See docs/openapi.yaml for details.
• MCP (Model Context Protocol) server support — Integrate with AI agents and tools using a standardized protocol.
• Optional MCP OAuth 2.1 — Connect remote MCP clients that cannot supply a Basic Auth header. See

MCP OAuth.

• Mention users:
  • `@phoneNumber`
  • Example: `Hello @628974812XXXX, @628974812XXXX`
• Ghost mentions (mention all) — Mention group participants without showing `@phone` in the message text.
  • Pass phone numbers in the `mentions` field to mention users without a visible `@` in the message.
  • Use the special keyword `@everyone` to automatically mention all group participants.
• Post WhatsApp status updates.
• Mark incoming audio messages and voice notes as played.
• Send stickers — Automatically convert images to WebP sticker format.
  • Supports JPG, JPEG, PNG, WebP, and GIF formats.
  • Automatically resizes images to 512×512 pixels.
  • Preserves transparency in PNG images.
  • Animated WebP stickers are supported but must meet WhatsApp requirements:
    • Exactly 512×512 pixels.
    • Less than 500 KB.
    • No more than 10 seconds long.
    • If an animated sticker does not meet these requirements, resize it before uploading with a tool such as

ezgif.com.

• Compress images before sending.
• Compress videos before sending.
• Customize the OS name shown as the linked device name in WhatsApp:
  • `--os=Chrome` or `--os=MyApplication`
• Basic Auth with multiple credentials:
  • `--basic-auth=kemal:secret,toni:password,userName:secretPassword`
  • Short form: `-b=kemal:secret,toni:password,userName:secretPassword`
• Subpath deployment support:
  • `--base-path="/gowa"` allows deployment under a path such as `/gowa`.
• Customizable port and debug mode:
  • `--port 8000`
  • `--debug true`
• Automatic replies to incoming messages:
  • `--autoreply="Don't reply to this message"`
• Automatically mark incoming messages as read:
  • `--auto-mark-read=true`
• Automatically download media from incoming messages:
  • `--auto-download-media=false` disables automatic media downloads (default: `true`).
• Automatically reject incoming calls:
  • `--auto-reject-call=true` or `WHATSAPP_AUTO_REJECT_CALL=true` (see

Webhook Payload for call events).

• Configurable presence on connect:
  • `--presence-on-connect=unavailable` or `WHATSAPP_PRESENCE_ON_CONNECT=unavailable`
  • `available` — Mark the account as online (suppresses phone notifications).
  • `unavailable` — Register the push name without going online (default; preserves phone notifications).
  • `none` — Skip presence entirely (the push name is not registered, so contacts may see `-` as the name).
• Daily presence pulse:
  • `--presence-pulse-enabled=true` or `WHATSAPP_PRESENCE_PULSE_ENABLED=true` (default: `true`).
  • `--presence-pulse-interval=24h` controls how often each connected device is pulsed.
  • `--presence-pulse-duration=5m` controls how long the account stays `available` before returning to `unavailable`.
• Webhooks for received messages and other events:
  • `--webhook="http://yourwebhook.site/handler"`
  • Short form: `-w="http://yourwebhook.site/handler"`
  • See Webhook Payload Documentation for details.
• Per-device webhooks — Each device can have its own webhook URL and event filters.
  • Set via API: `PATCH /devices/:device_id/webhook` with `{"webhook_url": "https://device-webhook.site/handler"}`.
  • Get via API: `GET /devices/:device_id/webhook`.
  • When a device has a custom webhook, events for that device are sent to the device-specific URL.
  • When no device webhook is set, events fall back to the global webhook (`--webhook`).
  • Set `webhook_url` to an empty string with `PATCH` to clear it and use the global webhook.
• Webhook signatures — Webhook requests include an HMAC-SHA-256 signature in the `X-Hub-Signature-256`

header, generated with the default key `secret`.

Change the key with:

• Webhook payload documentation — For detailed schemas, security implementation, and integration examples,

see Webhook Payload Documentation.

• Webhook event filtering — Filter which events are forwarded to your webhook with:
  • `--webhook-events="message,message.ack"` (a comma-separated list), or
  • `WHATSAPP_WEBHOOK_EVENTS=message,message.ack`.

Available Webhook Events:

If this setting is empty, all events are forwarded.

• Webhook JID filtering

You can skip events for specific chats or senders (for example, mute all groups) before they are forwarded:

The Chatwoot integration has a separate `CHATWOOT_IGNORE_JIDS` setting.

• 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 with:

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

For production environments, use a valid TLS certificate (for example, from Let's Encrypt) instead of

disabling verification.

Configuration

Configuration is loaded in this order of priority:

1. Command-line flags (highest priority)

2. Environment variables

3. `.env` file (lowest priority)

Environment Variables

To use environment variables:

1. From the repository root, copy the example file: `cp src/.env.example src/.env`.

2. Update the values in `src/.env` as needed.

3. Alternatively, set the same variables in the process environment.

Available Environment Variables

Documentation:

• For detailed webhook payload schemas, security implementation, and integration examples, see

Webhook Payload Documentation.

• For the comprehensive Chatwoot integration guide, see

Chatwoot Integration Documentation.

• For OAuth deployment and security details, see MCP OAuth.

Run `./whatsapp --help` to see all command-line flags.

Requirements

System Requirements

• Go 1.26.0 or later (when building from source)
• FFmpeg (for media processing)

Supported Platforms

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

Dependencies (without Docker)

• macOS:
  • `brew install ffmpeg webp`
  • `export CGO_CFLAGS_ALLOW="-Xpreprocessor"`
• Linux:
  • `sudo apt update`
  • `sudo apt install ffmpeg webp`
• Windows (WSL is recommended; see Install WSL):
  • Install FFmpeg.
  • Install libwebp, then extract it and add its `bin` directory

to `PATH`.

> Note: The `webp` package provides `cwebp` (encoder), `dwebp` (decoder), and `webpmux` (frame extractor) tools.

> FFmpeg is required for media processing. The libwebp tools (`webpmux` + `dwebp`) are used for animated WebP sticker support.

How to use

Basic

1. Clone the repository: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`.

2. Open the cloned directory in a terminal.

3. Run `cd src`.

4. Run `go run . rest`.

5. Open `http://localhost:3000`.

Docker

Docker avoids the need to install Go, FFmpeg, and libwebp directly on the host.

1. Clone the repository: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`.

2. Open the cloned directory in a terminal.

3. Copy the environment file: `cp src/.env.example src/.env`.

4. Run `docker compose up -d --build`.

5. Open `http://localhost:3000`.

Build your own binary

1. Clone the repository: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`.

2. Open the cloned directory in a terminal.

3. Run `cd src`.

4. Build the binary:

5. Start the server:

6. Open `http://localhost:3000` in a browser.

Run `./whatsapp --help` (or `.\whatsapp.exe --help` on Windows) to see all flags.

Cross-compile for Raspberry Pi (ARM)

To build for a Raspberry Pi or another ARM device without a C toolchain (CGO), use the `purego` build tag. This

selects a pure-Go SQLite implementation.

1. Clone the repository: `git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice`.

2. Open the cloned directory in a terminal.

3. Run `cd src`.

4. Build for Raspberry Pi Zero / 1 (ARMv6):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6

5. Build for Raspberry Pi 2 / 3 / 4 (ARMv7 32-bit):

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7

6. Transfer the binary to your Pi, give it execution permission (`chmod +x`), and run it:

MCP Server (Model Context Protocol)

MCP is not a separate mode or process — it's served by the REST server itself. Whenever `./whatsapp rest` is

running, the MCP endpoint is available at `http://:/mcp` (default

`http://localhost:3000/mcp`) using the streamable HTTP transport. Disable it with `MCP_ENABLED=false` or

`--mcp-enabled=false` (default: enabled).

Available MCP Tools

There are five consolidated tools; agents choose behavior through a `type`/`action` argument instead of one tool per

operation:

Device selection

For multi-device deployments, the `X-Device-Id` header on the MCP client connection selects the device used by

every tool call on that connection. If omitted, it falls back to the default device, just like REST. Any individual

call can override it with an optional `device_id` argument.

MCP Configuration

Point your MCP client at the `/mcp` endpoint. It inherits the REST server's Basic Auth, so include the same

`Authorization` header your REST calls use:

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic dXNlcjpzZWNyZXQ=",
        "X-Device-Id": "628123456789"
      }
    }
  }
}

`headers` is optional: include `Authorization` only when Basic Auth is configured, and `X-Device-Id` only for

multi-device setups.

OAuth for remote MCP clients

OAuth 2.1 is available for remote clients that cannot attach a Basic Auth header. It is disabled by default. A minimal

configuration is:

APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com

When OAuth is enabled, `/mcp` accepts either a Bearer token or the configured Basic Auth credentials. OAuth does not

authenticate REST or UI routes. See MCP OAuth for client setup, reverse-proxy requirements,

subpath behavior, and the security model.

Migrating from the standalone MCP mode

• `./whatsapp mcp` → `./whatsapp rest` (MCP is now included automatically).
• `http://localhost:8080/sse` → `http://localhost:3000/mcp`.
• 40 granular tools → 5 consolidated tools (agents choose actions through the `type`/`action` field).

Production REST Server (Docker)

Using Docker Hub:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  aldinokemal2104/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Using GitHub Container Registry:

docker volume create whatsapp-storages
docker volume create whatsapp-statics
docker run --detach \
  --publish 3000:3000 \
  --name whatsapp \
  --restart always \
  --volume whatsapp-storages:/app/storages \
  --volume whatsapp-statics:/app/statics \
  ghcr.io/aldinokemal/go-whatsapp-web-multidevice \
  rest --autoreply="Don't reply to this message, please"

Production REST Server (Docker Compose)

Create a `docker-compose.yml` file with one of the following configurations.

Using Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using GitHub Container Registry:

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

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using environment variables with Docker Hub:

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Using environment variables with GitHub Container Registry:

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp_storages:/app/storages
      - whatsapp_statics:/app/statics
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp_storages:
  whatsapp_statics:

Start the selected stack with `docker compose up -d`.

Production Server (Binary)

Download a binary from the releases page, then

run it with the `rest` subcommand.

You may also fork or modify the source code.

Current API

MCP (Model Context Protocol) API

• Served at `/mcp` by the REST server using streamable HTTP whenever `MCP_ENABLED` is true. With `APP_BASE_PATH`

set, the route is `/mcp`.

• Available tools are listed in the "Available MCP Tools" section above.
• Compatible with MCP-enabled AI tools and agents.

HTTP REST API

• Check docs/openapi.yaml for detailed API specifications.
• Use Swagger Editor to visualize the API.
• Generate HTTP clients using openapi-generator.

`✅` = available. `*` = has known limitations; see the notes below.

Notes:

• `*List My Groups`: Returns a maximum of 500 groups because of a WhatsApp protocol limitation. WhatsApp's servers,

not this API, enforce the limit. See the whatsmeow source

for details.

• `/health` is public and always registered at the root path, even when `APP_BASE_PATH` is set.
• Chatwoot routes are registered only when `CHATWOOT_ENABLED=true`.

User Interface

MCP UI

• Set up MCP (tested in Cursor)

• Test MCP

• Successful MCP setup

Web dashboard (gowa-ui)

The dashboard lives in its own repository: aldinokemal/gowa-ui. Each

gowa-ui release publishes a single self-contained `gowa-ui.html`; the server downloads the latest release at

startup (and every `APP_UI_UPDATE_INTERVAL`, which defaults to 3h), verifies its SHA-256 digest, caches it under

`storages/ui/`, and serves it at `/` behind Basic Auth.

Trust model: the release digest proves the download matches what GitHub advertises, not who published it.

Operators who audit a specific build can pin it with `APP_UI_ASSET_SHA256` (each release ships a `.sha256`

asset—this is the only setting that pins an exact build), point `APP_UI_REPO` at a fork they control

(the updater still tracks that repo's latest release), or pre-seed the cache and disable auto-update entirely.

Air-gapped servers: place a downloaded `gowa-ui.html` at `storages/ui/index.html` and set

`APP_UI_AUTO_UPDATE=false`. The dashboard can also be self-hosted anywhere static and pointed at this

server's URL (see the gowa-ui README).

macOS Note

If you see `invalid flag in pkg-config --cflags: -Xpreprocessor`, run:

export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Important

• This project is unofficial and not affiliated with WhatsApp.
• Use the official WhatsApp Business Platform when you require a supported, production-grade integration.