GOWA

Requirements

System Requirements

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

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.

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: - Linux and macOS: go build -o whatsapp - Windows (Command Prompt or PowerShell): go build -o whatsapp.exe 5. Start the server: - Linux and macOS: ./whatsapp rest - Windows: .\whatsapp.exe rest 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
   

1. 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: - If you built ARMv6: ./whatsapp-armv6 rest - If you built ARMv7: ./whatsapp-armv7 rest

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.

How to use

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.

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).

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 <base-path>/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