Configuration

Overview

GOWA WhatsApp API can be configured using three methods with the following priority order:

Command-Line Flags

Highest priority. Overrides all other configuration sources.

./whatsapp rest --port=8080 --debug=true

Environment Variables

Medium priority. Overrides .env file.

export APP_PORT=8080
export APP_DEBUG=true

.env File

Lowest priority. Default configuration file.

APP_PORT=8080
APP_DEBUG=true

Setup

Using .env File

cd src
cp .env.example .env

The .env file should be placed in the src/ directory alongside the binary.

Using Environment Variables

Set variables in your shell or systemd service file:

export APP_PORT=3000
export APP_DEBUG=true
export WHATSAPP_WEBHOOK="https://yourapp.com/webhook"
./whatsapp rest

Using CLI Flags

Override any setting directly:

./whatsapp rest --port=8080 --debug=true --webhook="https://yourapp.com/webhook"

View all available flags:

./whatsapp rest --help

Application Settings

Server Configuration

APP_PORT

integer

default:"3000"

HTTP server port.CLI Flag: --port

export APP_PORT=8080
./whatsapp rest --port=8080

APP_HOST

string

default:"0.0.0.0"

Host address to bind the server. Use 0.0.0.0 for all interfaces or 127.0.0.1 for localhost only.CLI Flag: --host

export APP_HOST=127.0.0.1

APP_DEBUG

boolean

default:"false"

Enable debug logging for detailed request/response logs.CLI Flag: --debug

export APP_DEBUG=true
./whatsapp rest --debug=true

APP_OS

string

default:"Chrome"

Device name displayed in WhatsApp’s “Linked Devices” section.CLI Flag: --os

export APP_OS="MyApp Server"
./whatsapp rest --os="MyApp Server"

Authentication

APP_BASIC_AUTH

string

Basic authentication credentials (comma-separated for multiple users).Format: username:password,username2:password2CLI Flag: --basic-auth or -b

export APP_BASIC_AUTH="admin:secret,user:password123"
./whatsapp rest -b="admin:secret,user:password123"

Basic Auth transmits credentials in base64 encoding (not encrypted). Always use HTTPS in production.

Deployment

APP_BASE_PATH

string

Base path for subpath deployment (e.g., /gowa).CLI Flag: --base-path

export APP_BASE_PATH="/gowa"
# Access at: http://localhost:3000/gowa/

APP_TRUSTED_PROXIES

string

default:""

Trusted proxy IP ranges for reverse proxy deployments (CIDR notation).

export APP_TRUSTED_PROXIES="0.0.0.0/0"
# For Cloudflare:
export APP_TRUSTED_PROXIES="173.245.48.0/20,103.21.244.0/22"

Database Settings

DB_URI

string

default:"file:storages/whatsapp.db?_foreign_keys=on"

Database connection URI. Supports SQLite (file) and PostgreSQL.SQLite (default):

export DB_URI="file:storages/whatsapp.db?_foreign_keys=on"

PostgreSQL:

export DB_URI="postgres://user:password@localhost:5432/whatsapp?sslmode=disable"

DB_KEYS_URI

string

default:"file::memory:?cache=shared&_foreign_keys=on"

Database URI for encryption keys storage (in-memory by default).

export DB_KEYS_URI="file::memory:?cache=shared&_foreign_keys=on"

WhatsApp Settings

Auto-Reply & Auto-Read

WHATSAPP_AUTO_REPLY

string

Automatically reply to all incoming messages with this text.CLI Flag: --autoreply

export WHATSAPP_AUTO_REPLY="Thank you for your message. We'll respond soon."
./whatsapp rest --autoreply="Thank you for your message."

WHATSAPP_AUTO_MARK_READ

boolean

default:"false"

Automatically mark incoming messages as read.CLI Flag: --auto-mark-read

export WHATSAPP_AUTO_MARK_READ=true
./whatsapp rest --auto-mark-read=true

WHATSAPP_AUTO_DOWNLOAD_MEDIA

boolean

default:"true"

Automatically download media from incoming messages to statics/media/.CLI Flag: --auto-download-media

export WHATSAPP_AUTO_DOWNLOAD_MEDIA=false

Call Handling

WHATSAPP_AUTO_REJECT_CALL

boolean

default:"false"

Automatically reject incoming WhatsApp calls.CLI Flag: --auto-reject-call

export WHATSAPP_AUTO_REJECT_CALL=true
./whatsapp rest --auto-reject-call=true

Call rejection events are still sent to webhooks with auto_rejected: true flag.

Presence Settings

WHATSAPP_PRESENCE_ON_CONNECT

string

default:"unavailable"

Presence status to set when connecting to WhatsApp.Options:

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)

CLI Flag: --presence-on-connect

export WHATSAPP_PRESENCE_ON_CONNECT=unavailable

Account Validation

WHATSAPP_ACCOUNT_VALIDATION

boolean

default:"true"

Validate recipient phone numbers are registered on WhatsApp before sending.

export WHATSAPP_ACCOUNT_VALIDATION=false

Chat Storage

WHATSAPP_CHAT_STORAGE

boolean

default:"true"

Enable local chat and message storage for reply functionality.

export WHATSAPP_CHAT_STORAGE=true

Webhook Configuration

WHATSAPP_WEBHOOK

string

Webhook URL(s) for receiving events (comma-separated for multiple webhooks).CLI Flag: --webhook or -w

# Single webhook
export WHATSAPP_WEBHOOK="https://yourapp.com/webhook"

# Multiple webhooks
export WHATSAPP_WEBHOOK="https://app1.com/webhook,https://app2.com/webhook"

./whatsapp rest -w="https://yourapp.com/webhook"

WHATSAPP_WEBHOOK_SECRET

string

default:"secret"

Secret key for HMAC signature verification.CLI Flag: --webhook-secret

export WHATSAPP_WEBHOOK_SECRET="your-super-secret-key"

WHATSAPP_WEBHOOK_EVENTS

string

Comma-separated list of events to forward. If empty, all events are forwarded.CLI Flag: --webhook-eventsAvailable events: message, message.reaction, message.revoked, message.edited, message.ack, message.deleted, group.participants, group.joined, newsletter.joined, newsletter.left, newsletter.message, newsletter.mute, call.offer

# Only receive messages and receipts
export WHATSAPP_WEBHOOK_EVENTS="message,message.ack"

# Only group events
export WHATSAPP_WEBHOOK_EVENTS="group.participants,group.joined"

WHATSAPP_WEBHOOK_INCLUDE_OUTGOING

boolean

default:"false"

Include outgoing messages (sent by you) in webhook events.

export WHATSAPP_WEBHOOK_INCLUDE_OUTGOING=false

WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY

boolean

default:"false"

Skip TLS certificate verification for webhooks (insecure).CLI Flag: --webhook-insecure-skip-verify

export WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true

Only use WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true in development or with Cloudflare tunnels. Never in production with self-signed certificates exposed to the internet.

Chatwoot Integration

CHATWOOT_ENABLED

boolean

default:"false"

Enable Chatwoot CRM integration.

export CHATWOOT_ENABLED=true

CHATWOOT_URL

string

Chatwoot instance URL.

export CHATWOOT_URL="https://app.chatwoot.com"

CHATWOOT_API_TOKEN

string

Chatwoot API access token.

export CHATWOOT_API_TOKEN="your-api-token"

CHATWOOT_ACCOUNT_ID

integer

Chatwoot account ID.

export CHATWOOT_ACCOUNT_ID=12345

CHATWOOT_INBOX_ID

integer

Chatwoot inbox ID for WhatsApp channel.

export CHATWOOT_INBOX_ID=67890

CHATWOOT_DEVICE_ID

string

WhatsApp device ID for multi-device Chatwoot setup.

export CHATWOOT_DEVICE_ID="[email protected]"

CHATWOOT_IMPORT_MESSAGES

boolean

default:"false"

Enable message history sync to Chatwoot.

export CHATWOOT_IMPORT_MESSAGES=true

CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES

integer

default:"3"

Number of days of message history to import.

export CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7

For complete Chatwoot integration guide, see Chatwoot Integration Documentation.

Docker Configuration

Docker Compose Example

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
      - --webhook=https://yourapp.com/webhook

volumes:
  whatsapp:

Docker Run Example

docker run -d \
  --name whatsapp \
  --restart always \
  -p 3000:3000 \
  -v whatsapp:/app/storages \
  -e APP_DEBUG=true \
  -e WHATSAPP_WEBHOOK="https://yourapp.com/webhook" \
  aldinokemal2104/go-whatsapp-web-multidevice \
  rest --basic-auth=admin:admin

Complete Configuration Example

# Application
export APP_PORT=3000
export APP_HOST=0.0.0.0
export APP_DEBUG=false
export APP_OS="Production Server"
export APP_BASIC_AUTH="admin:secret123"
export APP_BASE_PATH=""
export APP_TRUSTED_PROXIES="0.0.0.0/0"

# Database
export DB_URI="file:storages/whatsapp.db?_foreign_keys=on"
export DB_KEYS_URI="file::memory:?cache=shared&_foreign_keys=on"

# WhatsApp Features
export WHATSAPP_AUTO_REPLY=""
export WHATSAPP_AUTO_MARK_READ=false
export WHATSAPP_AUTO_DOWNLOAD_MEDIA=true
export WHATSAPP_AUTO_REJECT_CALL=false
export WHATSAPP_PRESENCE_ON_CONNECT=unavailable
export WHATSAPP_ACCOUNT_VALIDATION=true
export WHATSAPP_CHAT_STORAGE=true

# Webhook
export WHATSAPP_WEBHOOK="https://yourapp.com/webhook"
export WHATSAPP_WEBHOOK_SECRET="your-super-secret-key"
export WHATSAPP_WEBHOOK_EVENTS="message,message.ack,group.participants"
export WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=false
export WHATSAPP_WEBHOOK_INCLUDE_OUTGOING=false

# Chatwoot (Optional)
export CHATWOOT_ENABLED=false
export CHATWOOT_URL=""
export CHATWOOT_API_TOKEN=""
export CHATWOOT_ACCOUNT_ID=""
export CHATWOOT_INBOX_ID=""
export CHATWOOT_DEVICE_ID=""
export CHATWOOT_IMPORT_MESSAGES=false
export CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=3

# Start server
./whatsapp rest

Configuration Best Practices

Use .env in Development

Keep configuration in .env file for easy local development.

Use Environment Variables in Production

Set environment variables in systemd service files or container orchestration.

Never Commit Secrets

Add .env to .gitignore. Use .env.example as template.

Use CLI Flags for Overrides

Override specific settings temporarily without changing configuration files.

Troubleshooting

Configuration Not Applied

Problem: Changes in .env file not taking effect.Solution:

Ensure .env file is in the src/ directory next to the binary
Restart the application after changing configuration
Check for environment variables overriding .env values
Enable --debug=true to see loaded configuration

Webhook Not Working

Problem: Webhook events not being received.Solution:

Verify WHATSAPP_WEBHOOK URL is publicly accessible
Check webhook endpoint returns HTTP 200
Enable debug mode: APP_DEBUG=true
Check webhook secret matches on both ends
Test with webhook.site first

Database Connection Failed

Problem: Cannot connect to database.Solution:

Ensure storages/ directory exists and is writable
For PostgreSQL, verify connection string format
Check database user has proper permissions
Enable debug logging to see full error

Get Started

Core Concepts

Guides

Integrations

Deployment

Overview

Setup

Using .env File

Using Environment Variables

Using CLI Flags

Application Settings

Server Configuration

Authentication

Deployment

Database Settings

WhatsApp Settings

Auto-Reply & Auto-Read

Call Handling

Presence Settings

Account Validation

Chat Storage

Webhook Configuration

Chatwoot Integration

Docker Configuration

Docker Compose Example

Docker Run Example

Complete Configuration Example

Configuration Best Practices

Use .env in Development

Use Environment Variables in Production

Never Commit Secrets

Use CLI Flags for Overrides

Troubleshooting

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Deployment

​Overview

​Setup

​Using .env File

​Using Environment Variables

​Using CLI Flags

​Application Settings

​Server Configuration

​Authentication

​Deployment

​Database Settings

​WhatsApp Settings

​Auto-Reply & Auto-Read

​Call Handling

​Presence Settings

​Account Validation

​Chat Storage

​Webhook Configuration

​Chatwoot Integration

​Docker Configuration

​Docker Compose Example

​Docker Run Example

​Complete Configuration Example

​Configuration Best Practices

Use .env in Development

Use Environment Variables in Production

Never Commit Secrets

Use CLI Flags for Overrides

​Troubleshooting

​See Also

Build docs developers (and LLMs) love

Overview

Setup

Using .env File

Using Environment Variables

Using CLI Flags

Application Settings

Server Configuration

Authentication

Deployment

Database Settings

WhatsApp Settings

Auto-Reply & Auto-Read

Call Handling

Presence Settings

Account Validation

Chat Storage

Webhook Configuration

Chatwoot Integration

Docker Configuration

Docker Compose Example

Docker Run Example

Complete Configuration Example

Configuration Best Practices

Troubleshooting

See Also