
whatsapp rest.
Requirements
Supported platforms: Linux (amd64, arm64, armv7, 386), macOS (Intel, Apple Silicon), Windows (amd64, 386; WSL recommended).
Docker
Images are published to Docker Hub and GHCR:aldinokemal2104/go-whatsapp-web-multideviceghcr.io/aldinokemal/go-whatsapp-web-multidevice
/app/storagesholds the SQLite databases (sessions, chat history, schedules, OAuth). Losing it unpairs every device./app/staticsholds QR images, uploads and downloaded media.- The default command is
rest. Pass flags after it, for example... go-whatsapp-web-multidevice rest --autoreply="Away". - The entrypoint fixes volume ownership and drops privileges to
gowauser(UID 20001, GID 20000). - Container time is UTC (
TZ=UTC). OverrideTZif you need local log timestamps.
Docker Compose
docker-compose.yml
openssl rand -hex 32 and set WHATSAPP_WEBHOOK_SECRET in your shell or Compose .env before starting this example.
The repository’s own docker-compose.yml builds the image from docker/golang.Dockerfile and reads src/.env. Use it when you want to build locally: cp src/.env.example src/.env && docker compose up -d --build.
Release binary
Download an archive from GitHub Releases. Archives are namedwhatsapp_<version>_<os>_<arch>.zip, for example:
checksums.txt from the same release. ./whatsapp version prints the version; ./whatsapp --help lists every flag.
From source
export CGO_CFLAGS_ALLOW="-Xpreprocessor" before building.
ARM without a C toolchain
Thepurego build tag selects a pure-Go SQLite driver, so you can cross-compile with CGO disabled:
Storage
By default everything is SQLite understorages/:
DB_URI also accepts PostgreSQL, for example postgres://user:pass@host:5432/gowa?sslmode=verify-full. Remote PostgreSQL session stores default to certificate verification when no effective TLS mode is set. Explicit URI, environment, or PostgreSQL service TLS settings still apply. See storage configuration.
GOWA creates SQLite files with owner-only 0600 permissions and new parent directories with 0700. Existing directories keep their permissions. Back up storages/ (or PostgreSQL plus storages/) to keep paired devices across rebuilds. Treat these backups as credentials.
Behind a reverse proxy
Serve GOWA under a subpath withAPP_BASE_PATH, and trust the proxy’s forwarded headers with APP_TRUSTED_PROXIES:
/health stays at the root (/health, not /gowa/health) so probes work regardless of base path.
The browser origin guard needs the public host. Preserve Host as above, or send X-Forwarded-Host from a trusted proxy. A separately hosted dashboard needs its exact origin in APP_TRUSTED_ORIGINS or APP_CORS_ALLOWED_ORIGINS. A wildcard does not authorize mutations or WebSockets. Serve the dashboard over HTTP or HTTPS, because file:// pages have an untrusted null origin.
The default listener refuses to start without complete Basic Auth credentials. Only enable APP_ALLOW_UNAUTHENTICATED=true when the proxy authenticates callers and clients cannot bypass it. For local development without authentication, bind APP_HOST=127.0.0.1.
Verify
/health returns OK once storage is initialized. It does not report whether any WhatsApp account is connected; use GET /devices/{device_id}/status for that.
Upgrading
Back upstorages/, pull the new image or binary, and restart. Read the release notes for breaking changes first. Notable ones: v6 made the rest subcommand mandatory, v7 moved binaries to GoReleaser archives, v8 added multi-device (device-scoped calls need X-Device-Id once more than one device exists), and the standalone whatsapp mcp mode (:8080/sse) was replaced by the /mcp endpoint on the REST server.