readme.md

August 9, 2026 · View on GitHub

Golang WhatsApp - Built with Go for efficient memory use

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!

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
  - Update: as of v9, MCP is no longer a separate mode — it's served by the REST server at /mcp (no standalone mcp subcommand). See MCP Server (Model Context Protocol) for details and migration notes.
v7
- Starting version 7.x we are using goreleaser to build the binary, so you can download the binary from release
v8
- Multi-device support: You can now connect and manage multiple WhatsApp accounts simultaneously in a single server instance
- New Device Management API: New endpoints under /devices for managing multiple devices
- Device scoping required: All device-scoped REST API calls now require either:
  - X-Device-Id header, or
  - device_id query parameter
  - If only one device is registered, it will be used as the default
- WebSocket device scoping: Connect to /ws?device_id=<id> to scope WebSocket to a specific device
- Remote UI support: CORS allows the Authorization and X-Device-Id headers, so a standalone web UI (e.g. gowa-ui) hosted on another origin can call the API directly. GET /app/info exposes version and media size limits. Since browsers cannot set headers on WebSocket connections, pass /ws?device_id=<id>&authorization=<base64(user:pass)> when basic auth is enabled (use TLS — the credential is visible in the URL)
- Webhook payload changes: All webhook payloads now include a top-level device_id field identifying which device received the event:
```
```json
  {
    "event": "message",
    "device_id": "628123456789@s.whatsapp.net",
    "payload": { ... }
  }
```
```
v9
- UI moved to a separate repository: The web dashboard is no longer bundled in this repo. It now lives at aldinokemal/gowa-ui and ships as a single self-contained gowa-ui.html. This server is now a pure API backend that downloads the latest dashboard release at startup, verifies its sha256 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.

Feature

Send WhatsApp message via http API, docs/openapi.yaml for more details
MCP (Model Context Protocol) Server Support - Integrate with AI agents and tools using standardized protocol
Mention someone
- @phoneNumber
- example: Hello @628974812XXXX, @628974812XXXX
Ghost Mentions (Mention All) - Mention group participants without showing @phone in message text
- Pass phone numbers in mentions field to mention users without visible @ in message
- Use special keyword @everyone to automatically mention ALL group participants
- UI checkbox available in Send Message modal for groups
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
- Animated WebP stickers are supported but must meet WhatsApp requirements:
  - Must be exactly 512x512 pixels
  - Must be under 500KB file size
  - Maximum 10 seconds duration
  - If your animated sticker doesn't meet these requirements, please resize it before uploading using tools like ezgif.com
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)
Auto 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 as online (suppresses phone notifications)
- unavailable — register pushname without going online (default, preserves phone notifications)
- none — skip presence entirely (pushname won't be registered, contacts may see "-" as 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
Webhook for received message
- --webhook="http://yourwebhook.site/handler", or you can simplify
- -w="http://yourwebhook.site/handler"
- for more detail, see Webhook Payload Documentation
Per-Device Webhook - Each device can have its own webhook URL
- 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 to empty string "" via PATCH to clear and use global webhook
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 Payload Documentation For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation

Webhook Event Filtering You can filter which events are forwarded to your webhook using:

--webhook-events="message,message.ack" (comma-separated list)
Or environment variable: WHATSAPP_WEBHOOK_EVENTS=message,message.ack

Available Webhook Events:

Event	Description
`message`	Text, media, contact, location messages
`message.reaction`	Emoji reactions to messages
`message.revoked`	Deleted/revoked messages
`message.edited`	Edited messages
`message.ack`	Delivery and read receipts
`message.deleted`	Messages deleted for the user
`chat_presence`	Typing and recording indicators from contacts
`group.participants`	Group member join/leave/promote/demote events
`group.joined`	You were added to a group
`label.edit`	WhatsApp label metadata changed
`label.association`	Label applied to or removed from a chat
`newsletter.joined`	You subscribed to a newsletter/channel
`newsletter.left`	You unsubscribed from a newsletter
`newsletter.message`	New message(s) posted in a newsletter
`newsletter.mute`	Newsletter mute setting changed
`call.offer`	Incoming call received

If not configured (empty), all events will be forwarded.

Webhook JID Filtering

You can skip events for specific chats or senders (e.g. mute all groups) before they are forwarded:
- --webhook-ignore-jids="@g.us,628123456789@s.whatsapp.net" (comma-separated list)
- Or environment variable: WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us
- Supports the @g.us / @s.whatsapp.net / @lid wildcards (match a whole address space) and exact JIDs.
- This filters by conversation/sender and is independent of --webhook-events (which filters by event type). The Chatwoot integration keeps its own CHATWOOT_IGNORE_JIDS.
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):

Command-line flags (highest priority)
Environment variables
.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):

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

To use environment variables:

Copy .env.example to .env in your project root (cp src/.env.example src/.env)
Modify the values in .env according to your needs
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_HOST`	Host address to bind the server	`0.0.0.0`	`APP_HOST=127.0.0.1`
`APP_DEBUG`	Enable debug logging	`false`	`APP_DEBUG=true`
`APP_OS`	OS name (device name in WhatsApp)	`GOWA`	`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`
`APP_CORS_ALLOWED_ORIGINS`	Allowed CORS origins (any origin when empty)	-	`APP_CORS_ALLOWED_ORIGINS=https://ui.example.com`
`DB_URI`	Database connection URI	`file:storages/whatsapp.db`	`DB_URI=postgres://user:pass@host/db`
`DB_KEYS_URI`	Optional database URI for encryption/session key cache. Leave blank to use `DB_URI`; avoid in-memory storage in production because restarts can lose WhatsApp session state.	-	`DB_KEYS_URI=file:storages/whatsapp-keys.db?_foreign_keys=on`
`CHAT_STORAGE_MAX_OPEN_CONNS`	Max concurrent SQLite connections for chat storage	`5`	`CHAT_STORAGE_MAX_OPEN_CONNS=10`
`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_AUTO_REJECT_CALL`	Auto-reject incoming WhatsApp calls	`false`	`WHATSAPP_AUTO_REJECT_CALL=true`
`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_WEBHOOK_EVENTS`	Whitelist of events to forward (comma-separated, empty = all)	-	`WHATSAPP_WEBHOOK_EVENTS=message,message.ack`
`WHATSAPP_WEBHOOK_IGNORE_JIDS`	JIDs/wildcards to skip when forwarding (comma-separated)	-	`WHATSAPP_WEBHOOK_IGNORE_JIDS=@g.us`
`WHATSAPP_ACCOUNT_VALIDATION`	Enable account validation	`true`	`WHATSAPP_ACCOUNT_VALIDATION=false`
`WHATSAPP_PRESENCE_ON_CONNECT`	Presence on connect: `available`, `unavailable`, or `none`	`unavailable`	`WHATSAPP_PRESENCE_ON_CONNECT=unavailable`
`WHATSAPP_PROXY`	Outbound proxy for the WhatsApp WebSocket (socks5/http/https)	-	`WHATSAPP_PROXY=socks5://user:pass@host:1080`
`WHATSAPP_PRESENCE_PULSE_ENABLED`	Enable daily available/unavailable presence pulse	`true`	`WHATSAPP_PRESENCE_PULSE_ENABLED=false`
`WHATSAPP_PRESENCE_PULSE_INTERVAL`	Interval between presence pulses	`24h`	`WHATSAPP_PRESENCE_PULSE_INTERVAL=24h`
`WHATSAPP_PRESENCE_PULSE_DURATION`	Duration to stay available during each pulse	`5m`	`WHATSAPP_PRESENCE_PULSE_DURATION=5m`
`CHATWOOT_ENABLED`	Enable Chatwoot integration	`false`	`CHATWOOT_ENABLED=true`
`CHATWOOT_URL`	Chatwoot instance URL	-	`CHATWOOT_URL=https://app.chatwoot.com`
`CHATWOOT_API_TOKEN`	Chatwoot API access token	-	`CHATWOOT_API_TOKEN=your-api-token`
`CHATWOOT_ACCOUNT_ID`	Chatwoot account ID	-	`CHATWOOT_ACCOUNT_ID=12345`
`CHATWOOT_INBOX_ID`	Chatwoot inbox ID	-	`CHATWOOT_INBOX_ID=67890`
`CHATWOOT_DEVICE_ID`	WhatsApp device ID for Chatwoot (single-device / env fallback)	-	`CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net`
`CHATWOOT_ALLOWED_HOSTS`	Allowlist of Chatwoot hosts for per-device configs (SSRF guard)	-	`CHATWOOT_ALLOWED_HOSTS=app.chatwoot.com,chat.example.com`
`CHATWOOT_IMPORT_MESSAGES`	Enable message history sync to Chatwoot	`false`	`CHATWOOT_IMPORT_MESSAGES=true`
`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES`	Days of history to import	`3`	`CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7`
`CHATWOOT_IMPORT_DB_URI`	Direct Chatwoot PostgreSQL URI for history sync	-	`CHATWOOT_IMPORT_DB_URI=postgresql://user:pass@host:5432/chatwoot_production?sslmode=disable`
`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE`	Insert text placeholders for media rows during direct DB import	`true`	`CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE=true`
`CHATWOOT_IMPORT_MEDIA_WITH_REST`	Upload direct-DB import media rows through Chatwoot REST	`false`	`CHATWOOT_IMPORT_MEDIA_WITH_REST=true`
`CHATWOOT_AUTO_CREATE`	Auto-create or reuse the Chatwoot API inbox at startup	`false`	`CHATWOOT_AUTO_CREATE=true`
`CHATWOOT_INBOX_NAME`	Inbox name used when auto-create is enabled	`WhatsApp`	`CHATWOOT_INBOX_NAME=WhatsApp Support`
`CHATWOOT_WEBHOOK_URL`	Public GOWA Chatwoot reply webhook URL	-	`CHATWOOT_WEBHOOK_URL=https://api.example.com/chatwoot/webhook?secret=shared`
`CHATWOOT_WEBHOOK_SECRET`	Shared secret required for incoming Chatwoot webhooks	-	`CHATWOOT_WEBHOOK_SECRET=shared`
`CHATWOOT_REOPEN_CONVERSATION`	Reopen resolved Chatwoot conversations for returning contacts	`true`	`CHATWOOT_REOPEN_CONVERSATION=false`
`CHATWOOT_CONVERSATION_PENDING`	Create new Chatwoot conversations as pending	`false`	`CHATWOOT_CONVERSATION_PENDING=true`
`CHATWOOT_IGNORE_JIDS`	JIDs or wildcards to exclude from Chatwoot forwarding	-	`CHATWOOT_IGNORE_JIDS=@g.us,628123@s.whatsapp.net`
`CHATWOOT_SIGN_MSG`	Prefix Chatwoot agent replies with the agent name	`false`	`CHATWOOT_SIGN_MSG=true`
`CHATWOOT_SIGN_DELIMITER`	Delimiter between Chatwoot agent signature and message body	`\n\n`	`CHATWOOT_SIGN_DELIMITER=" - "`
`CHATWOOT_FORWARD_EDITS`	Mirror WhatsApp edits into Chatwoot threaded notes	`true`	`CHATWOOT_FORWARD_EDITS=false`
`CHATWOOT_FORWARD_DELETES`	Mirror WhatsApp delete-for-everyone events into Chatwoot notes	`true`	`CHATWOOT_FORWARD_DELETES=false`
`CHATWOOT_MESSAGE_READ`	Sync read state for linked WhatsApp/Chatwoot messages	`false`	`CHATWOOT_MESSAGE_READ=true`
`CHATWOOT_MESSAGE_DELETE`	Delete linked opposite-side messages when deletion is reported	`false`	`CHATWOOT_MESSAGE_DELETE=true`

Documentation:

For detailed webhook payload schemas, security implementation, and integration examples, see Webhook Payload Documentation
For comprehensive Chatwoot integration guide, see Chatwoot Integration Documentation

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.25.5 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 webp
- export CGO_CFLAGS_ALLOW="-Xpreprocessor"
Linux:
- sudo apt update
- sudo apt install ffmpeg webp
Windows (not recommended, prefer using WSL):
- Install ffmpeg: download here
- Install libwebp: download here (extract and add bin folder to PATH)
- Add both to environment variable

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

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

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

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

Build your own binary

Clone this repo git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
Open the folder that was cloned via cmd/terminal.
run cd src
run
1. Linux & MacOS: go build -o whatsapp
2. Windows (CMD / PowerShell): go build -o whatsapp.exe
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
open http://localhost:3000 in browser

Cross-Compile for Raspberry Pi (ARM)

If you want to build for Raspberry Pi or other ARM devices without needing a C toolchain (CGO), you can use the purego build tag. This will use a pure-Go SQLite implementation.

Clone this repo git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
Open the folder that was cloned via cmd/terminal.
run cd src

Build for Raspberry Pi Zero / 1 (ARMv6):

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

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

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

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://<host>:<port><base-path>/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 5 consolidated tools; agents pick behavior via a type/action argument instead of one tool per operation:

Tool	`type` / `action` values
`whatsapp_send`	`text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward`
`whatsapp_message`	`react`, `edit`, `revoke`, `delete`, `mark_read`, `star`, `unstar`, `download_media`
`whatsapp_chat`	`list_chats`, `list_contacts`, `get_messages`, `archive`
`whatsapp_group`	`create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests`
`whatsapp_app`	`status`, `login_qr`, `login_code`, `logout`, `reconnect`

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 (falls back to the default device if omitted, same as 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.

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 pick actions via the type/action field)

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 aldinokemal2104/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/aldinokemal/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: aldinokemal2104/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/aldinokemal/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: aldinokemal2104/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
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

or with env file (GitHub Container Registry):

services:
  whatsapp:
    image: ghcr.io/aldinokemal/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
      - WHATSAPP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

Production Mode (binary)

download binary from release

You can fork or edit this source code !

Current API

MCP (Model Context Protocol) API

Served at /mcp by the REST server (streamable HTTP transport) 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 SwaggerEditor to visualize the API.
Generate HTTP clients using openapi-generator.

Feature	Menu	Method	URL
✅	Health Check	GET	/health
✅	List Devices	GET	/devices
✅	Add Device	POST	/devices
✅	Get Device Info	GET	/devices/:device_id
✅	Remove Device	DELETE	/devices/:device_id
✅	Login Device (QR)	GET	/devices/:device_id/login
✅	Login Device (Code)	POST	/devices/:device_id/login/code
✅	Logout Device	POST	/devices/:device_id/logout
✅	Reconnect Device	POST	/devices/:device_id/reconnect
✅	Get Device Status	GET	/devices/:device_id/status
✅	Get Device Webhook	GET	/devices/:device_id/webhook
✅	Set Device Webhook	PATCH	/devices/:device_id/webhook
✅	Login with Scan QR	GET	/app/login
✅	Login With Pair Code	GET	/app/login-with-code
✅	Passkey Pairing Status	GET	/app/passkey
✅	Passkey Pairing Response	POST	/app/passkey/response
✅	Passkey Pairing Confirm	POST	/app/passkey/confirm
✅	Logout	GET	/app/logout
✅	Reconnect	GET	/app/reconnect
✅	Devices	GET	/app/devices
✅	Connection Status	GET	/app/status
✅	App Info (version, limits)	GET	/app/info
✅	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
✅	Download Message Media	GET	/message/:message_id/download
✅	Reject Call	POST	/call/reject
✅	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 Newsletter Messages	GET	/newsletter/messages
✅	Get Chat List	GET	/chats
✅	Get Chat Messages	GET	/chat/:chat_jid/messages
✅	Pin Chat	POST	/chat/:chat_jid/pin
✅	Archive Chat	POST	/chat/:chat_jid/archive
✅	Set Disappearing Messages	POST	/chat/:chat_jid/disappearing
✅	Chatwoot Sync History	POST	/chatwoot/sync
✅	Chatwoot Sync Status	GET	/chatwoot/sync/status
✅	Chatwoot Reply Webhook	POST	/chatwoot/webhook

✅ = Available
❌ = Not Available Yet
* = Has known limitations (see notes below)

Notes:

*User My Groups: Returns a maximum of 500 groups due to WhatsApp protocol limitation. This is enforced by WhatsApp servers, not this API. See 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

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

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, default 3h), verifies its sha256 digest, caches it under storages/ui/, and serves it at / behind basic auth.

Setting	Default	Purpose
`APP_UI_ENABLED`	`true`	Serve the dashboard at `/`; `false` returns a JSON banner (API-only)
`APP_UI_AUTO_UPDATE`	`true`	Download/refresh from GitHub; disable for air-gapped deployments
`APP_UI_REPO`	`aldinokemal/gowa-ui`	Repository the updater follows — always its latest release, not a version pin
`APP_UI_ASSET_NAME`	`gowa-ui.html`	Release asset filename to download
`APP_UI_UPDATE_INTERVAL`	`3h`	How often to check `releases/latest`
`APP_UI_GITHUB_TOKEN`	(empty)	Optional token to raise the GitHub API rate limit
`APP_UI_ASSET_SHA256`	(empty)	Supply-chain pin: refuse any dashboard whose sha256 differs

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

Mac OS NOTE

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

Important

This project is unofficial and not affiliated with WhatsApp.
Please use official WhatsApp API to avoid any issues.