> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Every GOWA environment variable and command-line flag, with defaults.

GOWA reads configuration from three places:

* **Command-line flags** on `whatsapp rest` (run `./whatsapp rest --help` for the full list).
* **Environment variables**.
* A **`.env` file** in the working directory (`src/.env` when running from source; copy `src/.env.example`).

The `.env` file only fills in variables that are not already set in the environment.

> [!WARNING]
>
> In the current code, environment variables (including `.env`) are applied **after** flags are parsed, so a variable that is set overrides the matching flag. MCP OAuth settings, `--allow-unauthenticated`, `--trusted-origins`, `--chatwoot-webhook-allow-unsigned`, and `--webhook-all-device-receipts` are exceptions whose explicit flags win. Set each option in one place only. For example, `WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true` overrides `--webhook-insecure-skip-verify=false`.

Booleans accept `true`/`false`. Durations use Go syntax (`30s`, `5m`, `3h`). List values are comma-separated.

## Commands

| Command | Description |
| - | - |
| `whatsapp rest` | Start the REST API, dashboard, WebSocket and MCP endpoint. Required since v6; a bare `whatsapp` does not start the server. |
| `whatsapp version` | Print the version and exit. |
| `whatsapp --help` | List commands and flags. |

## Server

| Variable | Flag | Default | Description |
| - | - | - | - |
| `APP_PORT` | `--port`, `-p` | `3000` | HTTP port. |
| `APP_HOST` | `--host`, `-H` | `0.0.0.0` | Bind address. |
| `APP_DEBUG` | `--debug`, `-d` | `false` | Verbose logging. |
| `APP_OS` | `--os` | `GOWA` | Device name shown in WhatsApp's **Linked devices** list. |
| `APP_BASIC_AUTH` | `--basic-auth`, `-b` | — | Complete `user:pass` pairs, comma-separated. Required for a non-loopback listener unless the explicit unauthenticated override is set. |
| `APP_ALLOW_UNAUTHENTICATED` | `--allow-unauthenticated` | `false` | Permit a non-loopback listener without Basic Auth. Use only behind an authenticating proxy with restricted direct access. |
| `APP_TRUSTED_ORIGINS` | `--trusted-origins` | — | Exact extra browser origins allowed to mutate state and open WebSockets. The request host and specific CORS origins are also trusted. |
| `APP_BASE_PATH` | `--base-path` | — | Serve under a sub-path, e.g. `/gowa`. `/health` stays at the root. |
| `APP_TRUSTED_PROXIES` | `--trusted-proxies` | — | Proxy IP ranges whose forwarded headers are trusted, e.g. `10.0.0.0/8`. |
| `APP_CORS_ALLOWED_ORIGINS` | `--cors-allowed-origins` | — (any origin) | CORS origins. Specific origins also pass browser origin checks. A wildcard does not authorize mutations or WebSockets. |

## Dashboard

| Variable | Flag | Default | Description |
| - | - | - | - |
| `APP_UI_ENABLED` | `--ui-enabled` | `true` | Serve the gowa-ui dashboard at `/`. |
| `APP_UI_AUTO_UPDATE` | `--ui-auto-update` | `true` | Download the latest dashboard release at startup and periodically. Disable for air-gapped hosts with a pre-seeded `storages/ui` cache. |
| `APP_UI_REPO` | `--ui-repo` | `aldinokemal/gowa-ui` | GitHub repository to download from. |
| `APP_UI_ASSET_NAME` | `--ui-asset-name` | `gowa-ui.html` | Release asset to download. |
| `APP_UI_UPDATE_INTERVAL` | `--ui-update-interval` | `3h` | Interval between update checks. |
| `APP_UI_GITHUB_TOKEN` | — | — | GitHub token for a higher API rate limit. |
| `APP_UI_ASSET_SHA256` | `--ui-asset-sha256` | — | Only serve a dashboard with this SHA-256. |

## MCP

| Variable | Flag | Default | Description |
| - | - | - | - |
| `MCP_ENABLED` | `--mcp-enabled` | `true` | Serve the MCP endpoint at `/mcp`. |
| `MCP_OAUTH_ENABLED` | `--mcp-oauth-enabled` | `false` | Enable OAuth 2.1 for `/mcp`. Requires `APP_BASIC_AUTH`. |
| `MCP_OAUTH_ISSUER_URL` | `--mcp-oauth-issuer-url` | — | Public HTTPS issuer URL. Required with OAuth. |
| `MCP_OAUTH_RESOURCE_URL` | `--mcp-oauth-resource-url` | issuer + base path + `/mcp` | Canonical public MCP URL. |
| `MCP_OAUTH_DB_URI` | `--mcp-oauth-db-uri` | `file:storages/oauth.db` | SQLite store for OAuth clients and token hashes. |

See [MCP server](https://gowa-docs.mintlify.site/integrations/mcp.md).

## Storage

| Variable | Flag | Default | Description |
| - | - | - | - |
| `DB_URI` | `--db-uri` | `file:storages/whatsapp.db` | Session store: SQLite (`file:...`) or PostgreSQL (`postgres://...`). |
| `DB_KEYS_URI` | `--db-keys-uri` | same as `DB_URI` | Optional separate store for the encryption key cache. Avoid in-memory stores in production. |
| `CHAT_STORAGE_MAX_OPEN_CONNS` | — | `5` | Max SQLite connections for chat storage. Raise if sends time out under heavy inbound load. |

Chat storage (chats, messages, schedules) always lives in `storages/chatstorage.db` and is not configurable.

SQLite databases for sessions, chat storage, and OAuth are created with `0600` permissions. Directories GOWA creates for these files use `0700`. Existing directories keep their permissions. Permission changes that are not supported by the filesystem are logged as warnings.

For PostgreSQL session and key stores, an omitted or blank `sslmode` defaults to `verify-full` for remote dial targets. `localhost`, loopback IPs, and Unix sockets default to `disable`. Explicit URI settings, `PGSSLMODE`, and service configuration remain effective. A `PGSERVICE` entry can override the URI host and TLS mode. For managed PostgreSQL, supply `sslmode=verify-full` and the required CA configuration explicitly.

## WhatsApp behavior

| Variable | Flag | Default | Description |
| - | - | - | - |
| `WHATSAPP_AUTO_REPLY` | `--autoreply` | — | Fixed reply sent to every incoming message. |
| `WHATSAPP_AUTO_MARK_READ` | `--auto-mark-read` | `false` | Mark incoming messages read. |
| `WHATSAPP_AUTO_DOWNLOAD_MEDIA` | `--auto-download-media` | `true` | Save incoming media to `statics/media`. |
| `WHATSAPP_IGNORE_STATUS_MEDIA` | `--ignore-status-media` | `false` | Skip downloading status media. |
| `WHATSAPP_AUTO_REJECT_CALL` | `--auto-reject-call` | `false` | Reject incoming calls. |
| `WHATSAPP_ACCOUNT_VALIDATION` | `--account-validation` | `true` | Check recipients are on WhatsApp before sending. |
| `WHATSAPP_PRESENCE_ON_CONNECT` | `--presence-on-connect` | `unavailable` | Presence sent on connect: `available`, `unavailable` or `none`. |
| `WHATSAPP_PRESENCE_PULSE_ENABLED` | `--presence-pulse-enabled` | `true` | Periodically go online briefly, then offline again. |
| `WHATSAPP_PRESENCE_PULSE_INTERVAL` | `--presence-pulse-interval` | `24h` | Time between pulses. |
| `WHATSAPP_PRESENCE_PULSE_DURATION` | `--presence-pulse-duration` | `5m` | How long each pulse stays online. |
| `WHATSAPP_PROXY` | `--whatsapp-proxy` | — | Proxy for the WhatsApp connection: `socks5://`, `http://` or `https://`. `HTTP_PROXY` does not apply to it. |

## Webhooks

| Variable | Flag | Default | Description |
| - | - | - | - |
| `WHATSAPP_WEBHOOK` | `--webhook`, `-w` | — | Webhook URL(s), comma-separated. |
| `WHATSAPP_WEBHOOK_SECRET` | `--webhook-secret` | random per process | HMAC key for `X-Hub-Signature-256`. Set a stable generated key. Empty, `secret`, `super-secret-key`, and `your-private-key` produce an ephemeral key instead. |
| `WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY` | `--webhook-insecure-skip-verify` | `false` | Skip TLS verification (development only). |
| `WHATSAPP_WEBHOOK_EVENTS` | `--webhook-events` | — (all) | Event allowlist, e.g. `message,message.ack`. |
| `WHATSAPP_WEBHOOK_IGNORE_JIDS` | `--webhook-ignore-jids` | — | JIDs or wildcards (`@g.us`, `@s.whatsapp.net`, `@lid`) not forwarded. |
| `WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL` | `--webhook-device-merge-global` | `false` | Send a device's events to the global URLs as well as its own webhook. |
| `WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS` | `--webhook-all-device-receipts` | `false` | Forward receipts from contacts' linked devices as well as their primary device. May produce multiple acknowledgments for one message. |

See [Webhooks](https://gowa-docs.mintlify.site/concepts/webhooks.md).

## Chatwoot

| Variable | Flag | Default |
| - | - | - |
| `CHATWOOT_ENABLED` | `--chatwoot-enabled` | `false` |
| `CHATWOOT_URL` | — | — |
| `CHATWOOT_API_TOKEN` | — | — |
| `CHATWOOT_ACCOUNT_ID` | — | — |
| `CHATWOOT_INBOX_ID` | — | — |
| `CHATWOOT_DEVICE_ID` | `--chatwoot-device-id` | — |
| `CHATWOOT_ALLOWED_HOSTS` | `--chatwoot-allowed-hosts` | — |
| `CHATWOOT_IMPORT_MESSAGES` | `--chatwoot-import-messages` | `false` |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `--chatwoot-days-limit-import-messages` | `3` |
| `CHATWOOT_IMPORT_DB_URI` | `--chatwoot-import-db-uri` | — |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `--chatwoot-import-placeholder-media-message` | `true` |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `--chatwoot-import-media-with-rest` | `false` |
| `CHATWOOT_AUTO_CREATE` | `--chatwoot-auto-create` | `false` |
| `CHATWOOT_INBOX_NAME` | `--chatwoot-inbox-name` | `WhatsApp` |
| `CHATWOOT_WEBHOOK_URL` | `--chatwoot-webhook-url` | — |
| `CHATWOOT_WEBHOOK_SECRET` | `--chatwoot-webhook-secret` | — |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `--chatwoot-webhook-allow-unsigned` | `false` |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `--chatwoot-webhook-signature-tolerance` | `5m` |
| `CHATWOOT_REOPEN_CONVERSATION` | `--chatwoot-reopen-conversation` | `true` |
| `CHATWOOT_CONVERSATION_PENDING` | `--chatwoot-conversation-pending` | `false` |
| `CHATWOOT_IGNORE_JIDS` | `--chatwoot-ignore-jids` | — |
| `CHATWOOT_SIGN_MSG` | `--chatwoot-sign-msg` | `false` |
| `CHATWOOT_SIGN_DELIMITER` | `--chatwoot-sign-delimiter` | `\n\n` |
| `CHATWOOT_FORWARD_EDITS` | `--chatwoot-forward-edits` | `true` |
| `CHATWOOT_FORWARD_DELETES` | `--chatwoot-forward-deletes` | `true` |
| `CHATWOOT_EVENTS` | `--chatwoot-events` | Follows `WHATSAPP_WEBHOOK_EVENTS` when empty |
| `CHATWOOT_MESSAGE_READ` | `--chatwoot-message-read` | `false` |
| `CHATWOOT_MESSAGE_DELETE` | `--chatwoot-message-delete` | `false` |
| `CHATWOOT_REVOKE_ON_DELETE` | `--chatwoot-revoke-on-delete` | `false` |

The event filter and one-way revoke option are available on GOWA `main` after v9.9.0. See [Chatwoot integration](https://gowa-docs.mintlify.site/integrations/chatwoot.md#configuration) for behavior and examples.

## Fixed limits

These are compiled in and cannot be changed by configuration:

| Limit | Value |
| - | - |
| Image upload | 20 MB |
| Document upload | 50 MB |
| Video upload and HTTP request body | 100 MB |
| Incoming media download | 500 MB |
| Request timeout | 45 s (`504 GATEWAY_TIMEOUT`) |
| Webhook delivery | 10 s per attempt, 5 attempts |

## Media URL downloads

Send requests that fetch media, documents, or link previews accept HTTP and HTTPS URLs. Public URL fetches reject loopback, private, link-local, metadata, multicast, and reserved destinations. Redirects and the address actually dialed are checked. These downloads connect directly and do not use `HTTP_PROXY` or `HTTPS_PROXY`.

GOWA can read its own `/statics` URLs from disk. Chatwoot attachment downloads can use the configured Chatwoot destination or allowed hosts, including an internal host when trusted through that integration. This exception does not apply to arbitrary URLs submitted to the send API. Use file uploads when the source is private.

## Not used

`src/.env.example` lists `WHATSAPP_WEBHOOK_INCLUDE_OUTGOING` and `WHATSAPP_CHAT_STORAGE`, but the current code does not read either. Setting them has no effect.

## Example

```bash .env theme={null}
APP_PORT=3000
APP_OS=MyCompany
APP_BASIC_AUTH=admin:a-long-random-password
APP_TRUSTED_PROXIES=10.0.0.0/8
DB_URI=postgres://gowa:replace-with-password@db.example.com:5432/gowa?sslmode=verify-full
WHATSAPP_WEBHOOK=https://example.com/wa-hook
WHATSAPP_WEBHOOK_SECRET=another-long-random-secret
WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_AUTO_MARK_READ=false
```

Equivalent flags:

```bash theme={null}
./whatsapp rest --port=3000 --os=MyCompany \
  --basic-auth=admin:a-long-random-password \
  --webhook=https://example.com/wa-hook \
  --webhook-secret=another-long-random-secret \
  --webhook-events=message,message.ack
```


## Related topics

- [Quickstart](https://gowa-docs.mintlify.site/quickstart.md)
- [Chatwoot Integration](https://gowa-docs.mintlify.site/integrations/chatwoot.md)
- [Get device webhook configuration](https://gowa-docs.mintlify.site/api-reference/device/get-device-webhook-configuration.md)
- [Set device webhook configuration](https://gowa-docs.mintlify.site/api-reference/device/set-device-webhook-configuration.md)
- [Sync message history to Chatwoot](https://gowa-docs.mintlify.site/api-reference/chatwoot/sync-message-history-to-chatwoot.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.