Appearance
Configuration
Set these as environment variables or in .env. See .env.example for the full list.
Required
| Variable | Notes |
|---|---|
DATABASE_URL | PostgreSQL connection string. Tables are created on first boot. |
ADMIN_EMAILS | Comma-separated addresses allowed to sign in to the dashboard. |
RESEND_API_KEY, RESEND_FROM_EMAIL | Send sign-in codes. Required in production. Without them, outside production, codes are printed to the log. |
KEY_ENCRYPTION_SECRET | Random, 16+ characters. Encrypts stored API keys and WhatsApp sessions. Required in production. |
Server
| Variable | Default | Notes |
|---|---|---|
PORT | 3000 | |
NODE_ENV | production turns on startup checks. | |
TRUST_PROXY | Set 1 behind nginx, Caddy or a load balancer. | |
ADMIN_API_KEY | Optional x-admin-key for scripts. 16+ characters in production. Unset disables it. | |
AUTOSTART_CLIENTS | 1 | 0 starts the server without booting WhatsApp clients. |
RATE_LIMIT_PER_MINUTE | 30 | Default send limit per app. |
WhatsApp sessions
| Variable | Default | Notes |
|---|---|---|
SESSION_STORE | postgres | local keeps sessions on disk only. |
SESSIONS_DIR | data/sessions | Working copy of browser profiles. |
SESSION_BACKUP_MINUTES | 10 | How often a running session is saved to the database. |
SESSION_INACTIVE_DAYS | 7 | Delete stored sessions of apps offline this long. 0 never deletes. |
PUPPETEER_EXECUTABLE_PATH | auto | Chrome or Chromium to use. |
PUPPETEER_PROXY_SERVER | Route the browser through an egress proxy. | |
PUPPETEER_IGNORE_HTTPS_ERRORS | Development only, never in production. | |
SEND_CONFIRM_WAIT_MS | 5000 | How long to wait for a sent message id. |
CLIENT_INIT_TIMEOUT_MS | 180000 | A client still starting after this long is restarted. |
RECONNECT_BASE_MS, RECONNECT_MAX_MS | 5000, 300000 | Reconnect backoff. |
Webhooks and retention
| Variable | Default |
|---|---|
WEBHOOK_TIMEOUT_MS | 8000 |
WEBHOOK_MAX_ATTEMPTS | 10 |
WEBHOOK_RETRY_BASE_MS | 30000 |
WEBHOOK_MAX_DELAY_MS | 3600000 |
WEBHOOK_CONCURRENCY | 5 |
WEBHOOK_RETENTION_DAYS | 7 |
MESSAGE_RETENTION_DAYS | 7 |
Provisioning
| Variable | Default |
|---|---|
PROVISION_MAX_APPS | 100 |
PROVISION_CREATES_PER_HOUR | 30 |
Database notes
Run the gateway in the same region as the database, since every API request does a key lookup. Use a separate database for development. To move from the old SQLite version, run node scripts/migrate-sqlite-to-postgres.js --dry-run and then without --dry-run. WhatsApp logins are not migrated, so each app shows a QR once.