Installation

GOWA (Go WhatsApp Web Multi-Device API) can be installed in multiple ways depending on your environment and requirements.

System Requirements

Platform Support

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64 via WSL)

Dependencies

Docker (recommended) or
Go 1.24.0+ (for building from source)
FFmpeg (for media processing)

Docker is the recommended installation method as it includes all dependencies and works consistently across platforms.

Installation Methods

Docker (Recommended)
Docker Compose
Binary
Build from Source

Docker Installation

Docker is the simplest and most reliable way to run GOWA. All dependencies (FFmpeg, libwebp) are included.

Pull the image

Choose either Docker Hub or GitHub Container Registry:

docker pull aldinokemal2104/go-whatsapp-web-multidevice:latest

Create a volume for persistent storage

Create a Docker volume to store WhatsApp sessions and media:

docker volume create whatsapp

This volume persists your WhatsApp session across container restarts.

Run the container

docker run --detach \
  --publish=3000:3000 \
  --name=whatsapp \
  --restart=always \
  --volume=whatsapp:/app/storages \
  aldinokemal2104/go-whatsapp-web-multidevice rest

Verify it's running

Check container status:

docker ps

Test the API:

curl http://localhost:3000/app/devices

View logs:

docker logs whatsapp

Docker Management Commands

Stop the container

docker stop whatsapp

Start the container

docker start whatsapp

Restart the container

docker restart whatsapp

View logs

# Follow logs in real-time
docker logs -f whatsapp

# View last 100 lines
docker logs --tail=100 whatsapp

Remove container and start fresh

# Stop and remove container
docker stop whatsapp
docker rm whatsapp

# Optionally remove the volume (THIS DELETES YOUR SESSION)
docker volume rm whatsapp

# Start a new container
docker run --detach \
  --publish=3000:3000 \
  --name=whatsapp \
  --restart=always \
  --volume=$(docker volume create --name=whatsapp):/app/storages \
  aldinokemal2104/go-whatsapp-web-multidevice rest

Update to latest version

# Pull latest image
docker pull aldinokemal2104/go-whatsapp-web-multidevice:latest

# Stop and remove old container
docker stop whatsapp
docker rm whatsapp

# Start new container with same volume
docker run --detach \
  --publish=3000:3000 \
  --name=whatsapp \
  --restart=always \
  --volume=whatsapp:/app/storages \
  aldinokemal2104/go-whatsapp-web-multidevice rest

Docker Compose Installation

Docker Compose is ideal for production deployments with better configuration management.

Create docker-compose.yml

Create a docker-compose.yml file with your preferred configuration:

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:

Create .env file (optional)

For environment variable configuration, create a .env file:

.env

# Application Settings
APP_PORT=3000
APP_HOST=0.0.0.0
APP_DEBUG=false
APP_OS=Chrome
APP_BASIC_AUTH=admin:admin,user:pass123
APP_BASE_PATH=
APP_TRUSTED_PROXIES=0.0.0.0/0

# WhatsApp Settings
WHATSAPP_AUTO_REPLY=Thank you for your message. We'll get back to you soon.
WHATSAPP_AUTO_MARK_READ=false
WHATSAPP_AUTO_REJECT_CALL=false
WHATSAPP_AUTO_DOWNLOAD_MEDIA=true
WHATSAPP_WEBHOOK=https://yourwebhook.com/handler
WHATSAPP_WEBHOOK_SECRET=super-secret-key
WHATSAPP_WEBHOOK_EVENTS=message,message.ack,group.participants
WHATSAPP_ACCOUNT_VALIDATION=true
WHATSAPP_PRESENCE_ON_CONNECT=unavailable

# Chatwoot Integration (optional)
CHATWOOT_ENABLED=false
CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKEN=your_token_here
CHATWOOT_ACCOUNT_ID=12345
CHATWOOT_INBOX_ID=67890
CHATWOOT_DEVICE_ID=

Keep your .env file secure and never commit it to version control. Add it to .gitignore.

Start services

docker-compose up -d

View logs:

docker-compose logs -f

Verify it's running

# Check status
docker-compose ps

# Test API
curl http://localhost:3000/app/devices

Docker Compose Management

Start services

docker-compose up -d

Stop services

docker-compose down

Restart services

docker-compose restart

Update to latest version

# Pull latest image
docker-compose pull

# Restart with new image
docker-compose up -d

View logs

# All logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

Complete reset

# Stop and remove containers
docker-compose down

# Remove volumes (THIS DELETES YOUR SESSION)
docker-compose down -v

# Start fresh
docker-compose up -d

Binary Installation

Download pre-built binaries for your platform from GitHub releases.

Install dependencies

Before running the binary, install required dependencies:

sudo apt update
sudo apt install ffmpeg webp

Windows native is not recommended. Use WSL2 (Windows Subsystem for Linux) instead for best compatibility.

Download the binary

Visit the GitHub releases page or download via command line:

# Replace v8.3.0 with the latest version
wget https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/download/v8.3.0/whatsapp-linux-amd64
chmod +x whatsapp-linux-amd64
mv whatsapp-linux-amd64 whatsapp

Run the binary

./whatsapp rest

Run ./whatsapp --help to see all available options.

Access the API

Open http://localhost:3000 in your browser.

Running as a Service (Linux)

For production deployments, run GOWA as a systemd service:

Create systemd service

Create service file:

sudo nano /etc/systemd/system/whatsapp.service

Add configuration:

[Unit]
Description=GOWA WhatsApp API
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/whatsapp
ExecStart=/opt/whatsapp/whatsapp rest --port=3000 --basic-auth=admin:admin
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable whatsapp
sudo systemctl start whatsapp

Check status:

sudo systemctl status whatsapp

Build from Source

Build GOWA from source for custom modifications or latest development version.

Install prerequisites

# Install Go 1.24.0 or higher
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Install dependencies
sudo apt update
sudo apt install ffmpeg webp git

Verify Go installation:

go version  # Should show 1.24.0 or higher

Clone the repository

git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.git
cd go-whatsapp-web-multidevice/src

Build the binary

go build -o whatsapp

The -ldflags="-s -w" flag reduces binary size by stripping debug information.

Run the binary

./whatsapp rest

Access the API

Open http://localhost:3000 in your browser.

Development Mode

For development with hot-reload:

cd src
go run . rest

Run tests:

go test ./...

Format code:

go fmt ./...

Static analysis:

go vet ./...

Post-Installation

After installation, you’ll need to:

Connect your WhatsApp account

Visit http://localhost:3000/app/login and scan the QR code with WhatsApp on your phone.

Test the connection

curl http://localhost:3000/app/status

Send a test message

curl -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" \
  -d '{"phone": "628123456789", "message": "Test message"}'

Configuration Options

All installation methods support the same configuration options. See the Configuration Guide for detailed documentation.

Command-Line Flags

Basic Options

--port=3000              # Server port (default: 3000)
--host=0.0.0.0           # Host address (default: 0.0.0.0)
--debug=true             # Enable debug logging
--os="Chrome"            # Device name in WhatsApp
--basic-auth=user:pass   # Basic authentication

WhatsApp Options

--autoreply="Message"            # Auto-reply message
--auto-mark-read=true            # Mark incoming messages as read
--auto-reject-call=true          # Reject incoming calls
--auto-download-media=true       # Auto-download media files
--presence-on-connect=unavailable # Presence: available|unavailable|none

Webhook Options

--webhook="https://webhook.com/handler"  # Webhook URL(s)
--webhook-secret="secret"                # HMAC secret for webhooks
--webhook-events="message,message.ack"   # Event whitelist
--webhook-insecure-skip-verify=false     # Skip TLS verification

Advanced Options

--base-path="/gowa"              # Subpath deployment
--account-validation=false       # Disable account validation
--trusted-proxies="0.0.0.0/0"    # Trusted proxy IPs

Environment Variables

All command-line flags have corresponding environment variables. See the Environment Variables guide for the complete list. Example:

APP_PORT=3000
APP_DEBUG=true
WHATSAPP_AUTO_REPLY="Thank you for your message"
WHATSAPP_WEBHOOK=https://webhook.com/handler

Troubleshooting

Docker: Permission denied

If you get permission errors with Docker volumes:

# Fix volume permissions
docker run --rm -v whatsapp:/data alpine chown -R 1000:1000 /data

macOS: CGO compilation error

On macOS, if you get CGO errors:

export CGO_CFLAGS_ALLOW="-Xpreprocessor"

Add this to your ~/.zshrc or ~/.bash_profile to make it permanent.

Binary: FFmpeg not found

Ensure FFmpeg is installed and in your PATH:

# Check FFmpeg
ffmpeg -version

# Linux: Install FFmpeg
sudo apt install ffmpeg

# macOS: Install FFmpeg
brew install ffmpeg

Port already in use

Change the port using --port flag or APP_PORT environment variable:

./whatsapp rest --port=8080

Cannot connect to WhatsApp servers

Check your internet connection
Verify firewall settings allow outbound HTTPS (port 443)
Try reconnecting: curl http://localhost:3000/app/reconnect
Check logs for errors

Next Steps

Quick Start

Send your first message in 5 minutes

Configuration

Configure GOWA for your use case

Webhooks

Receive incoming messages

API Reference

Explore all API endpoints

Get Started

Core Concepts

Guides

Integrations

Deployment

System Requirements

Platform Support

Dependencies

Installation Methods

Docker Installation

Docker Management Commands

Docker Compose Installation

Docker Compose Management

Binary Installation

Running as a Service (Linux)

Build from Source

Development Mode

Post-Installation

Configuration Options

Command-Line Flags

Environment Variables

Troubleshooting

Next Steps

Quick Start

Configuration

Webhooks

API Reference

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Deployment

​System Requirements

Platform Support

Dependencies

​Installation Methods

​Docker Installation

​Docker Management Commands

​Docker Compose Installation

​Docker Compose Management

​Binary Installation

​Running as a Service (Linux)

​Build from Source

​Development Mode

​Post-Installation

​Configuration Options

​Command-Line Flags

​Environment Variables

​Troubleshooting

​Next Steps

Quick Start

Configuration

Webhooks

API Reference

​Additional Resources

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Docker Installation

Docker Management Commands

Docker Compose Installation

Docker Compose Management

Binary Installation

Running as a Service (Linux)

Build from Source

Development Mode

Post-Installation

Configuration Options

Command-Line Flags

Environment Variables

Troubleshooting

Next Steps

Additional Resources