Skip to main content
Version: v0.31.0

Configure OpenWA with environment variables

Set up OpenWA's database, storage, cache, and WhatsApp engine, then point it at the backends you actually run. Every setting is an environment variable: the defaults run with zero configuration (SQLite + local filesystem + no cache), so you change only what you need.

Prerequisites
  • OpenWA installed and able to start — see Installation.
  • Shell access to the machine (or container) running OpenWA, to edit .env or pass env vars.

How configuration is loaded​

OpenWA reads configuration from environment variables, with .env.example as the single source of truth for the full list. Copy it and edit your copy:

cp .env.example .env

The server validates the file at boot and refuses to start on an invalid value (for example, an unknown ENGINE_TYPE, or empty credentials a selected backend requires). Since v0.28.0, boot and the migration CLI also stop immediately (naming the file and OS error) when .env or data/.env.generated exists on disk, a dangling symlink included, and cannot be read, rather than continuing with defaults or generating a replacement admin key. Changing a value takes effect on the next restart — there is no hot reload, and adapters cannot be swapped without a restart.

In Docker, the same variables are passed through docker-compose.yml. Names and meanings are identical; only the delivery mechanism differs. Both bundled Compose files forward an explicit list of keys and carry no env_file, so a variable that is not on that list never reaches the container, however your .env is written. Both files forward every variable in the tables below except QUEUE_ENABLED, POSTGRES_BUILTIN, REDIS_BUILTIN, MINIO_BUILTIN, WEBHOOK_SSRF_PROTECT and STORAGE_LIST_MAX_FILES (neither file forwards them; the last was removed in v0.26.0), DOCKER_HOST (docker-compose.yml fixes it to its socket proxy and docker-compose.dev.yml does not set it), ALLOW_DEV_API_KEY (only docker-compose.dev.yml forwards it) and PORT (fixed at 2785 inside the container). API_PORT, BIND_HOST, OPENWA_MEM_LIMIT and OPENWA_PIDS_LIMIT configure Compose itself and never reach the app.

Numeric variables that boot validation checks accept plain decimal digits only: an exponent or hex spelling (1e6, 0x100) fails boot instead of configuring a different value than you intended. For knobs whose 0 is a documented opt-out (for example MESSAGE_REAPER_INTERVAL_MS), a blank or whitespace-only value — such as a ${KEY:-} forward from a compose file — means "use the default"; an explicit 0 selects the opt-out.

Boolean feature flags, including REDIS_ENABLED, REDIS_TLS, QUEUE_ENABLED, DATABASE_SSL, CSP_UPGRADE_INSECURE_REQUESTS, and the media conversion and archive flags, accept only exact true or false; blank means unset. Values such as True, 1, or a padded true fail boot. MEDIA_DOWNLOAD_ENABLED is the exception and also accepts 1, 0, yes and no in any case; PUPPETEER_HEADLESS and MCP_READONLY are not validated at boot. NODE_ENV must be exactly production, development, or test when set. PORT must be an unpadded decimal integer from 1 to 65535, including no whitespace-only value. WEBHOOK_SHUTDOWN_DRAIN_MS must be a non-negative integer.

The Infrastructure settings API (PUT /api/infra/config) also rejects database or Redis ports outside 1-65535, negative, fractional or (since v0.31.0) unsafe-large database pool sizes (above 9007199254740991), and local storage paths it cannot create or write. Since v0.26.0 it also refuses, with the boot validation message and before anything is written, a configuration the next boot would reject (for example TLS or a named user beside the built-in Redis, or DATABASE_SSL=true beside the built-in PostgreSQL), and, with S3 selected, a save that changes S3_ENDPOINT or newly selects S3 with a value that is not an absolute http:// or https:// URL. A database or storage section may omit type, which keeps the stored type. For an external PostgreSQL, blank database host and username fields are stored as localhost and postgres. A save that cannot write data/.env.generated answers saved: false with that file name and the error code instead of the filesystem error, and the server log has the cause (v0.31.0+).

Select your pluggable adapters​

OpenWA's infrastructure backends are swappable by configuration alone — no code changes. Four boundaries are independently selectable:

BoundaryVariableOptionsDefault
DatabaseDATABASE_TYPEsqlite, postgressqlite
StorageSTORAGE_TYPElocal, s3local
CacheREDIS_ENABLEDtrue, falsefalse
WhatsApp engineENGINE_TYPEwhatsapp-web.js, baileyswhatsapp-web.js

The main database (API keys and audit logs) is always SQLite and is not configurable — only the data connection above is pluggable. Take a backup explains how the two databases are backed up.

Database — SQLite or PostgreSQL​

SQLite is the zero-config default, stored as a file under ./data. It suits a personal bot or a handful of sessions but has a single writer. For higher write concurrency or many sessions, switch to PostgreSQL:

DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=openwa
DATABASE_USERNAME=openwa
# A password of your own, for example the output of `openssl rand -hex 24`, pasted here.
# The production boot guard refuses an empty value and a short list of known placeholders,
# so a copied example password would be accepted
DATABASE_PASSWORD=<generated password>

For managed PostgreSQL (Supabase, Heroku, Render, Railway), enable TLS:

DATABASE_SSL=true
# Only if the provider uses a self-signed certificate:
# DATABASE_SSL_REJECT_UNAUTHORIZED=false

Both bundled Compose files forward DATABASE_SSL and DATABASE_SSL_REJECT_UNAUTHORIZED from .env (v0.23.7+; earlier releases forwarded neither). The TLS options saved in the dashboard under Infrastructure go to data/.env.generated, and a value from .env or the process environment wins over that file. A Compose install whose .env came from an old template may still carry an uncommented DATABASE_SSL=false or DATABASE_SSL_REJECT_UNAUTHORIZED=true, which now overrides the dashboard's setting: comment those lines out or delete them. The gateway logs a warning at boot when a value from the environment or .env differs from the one saved in the dashboard.

Warning

With DATABASE_TYPE=postgres, boot requires DATABASE_HOST, DATABASE_USERNAME and DATABASE_PASSWORD in every environment, and a production build (NODE_ENV=production) also refuses to start if DATABASE_PASSWORD is a known placeholder. Set a strong, unique value.

Since v0.23.6 the PostgreSQL data connection runs in UTC whatever zone the host or the server uses: every pooled connection issues SET TIME ZONE 'UTC', timestamps are bound and read back as UTC, and boot fails, naming the effective zone, when the session is not on UTC year round. A connection pooler that drops session state is what typically prevents the pin from holding; there, set the database default instead with ALTER DATABASE "openwa" SET TimeZone='UTC' (use your DATABASE_NAME). SQLite deployments are unaffected, and so is PostgreSQL data where both the gateway and the database server already ran in UTC. Where either did not, some timestamps written before v0.23.6 hold local time and now read as shifted by the offset: the columns the gateway writes itself hold the gateway process's zone (its TZ: the official image ran UTC whatever the host's zone unless TZ reached the process, through the container's own environment or a TZ line in data/.env.generated, which the gateway loads at startup, and up to v0.23.5 neither bundled Compose file forwarded TZ, so a TZ in .env left a Compose gateway on UTC; a gateway started directly on the host took its TZ from the shell, .env or data/.env.generated, or the host's zone without one), and the columns PostgreSQL fills with DEFAULT now() hold the server's. Fix them with every node stopped and before the first start on v0.23.6; where the gateway ran outside UTC, that includes clearing, not converting, the session lease columns. PostgreSQL deployments that ran outside UTC names the affected columns and the conversion for each case.

Storage — local filesystem or S3/MinIO​

Media files default to the local filesystem under ./data/media. To use S3 — or any S3-compatible service such as MinIO — set:

STORAGE_TYPE=s3
S3_ENDPOINT=http://localhost:9000 # set only for MinIO or another S3-compatible store
S3_BUCKET=openwa
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key

S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY are the canonical names — what the app reads first and what the dashboard writes. The older S3_ACCESS_KEY / S3_SECRET_KEY spellings are still accepted as a fallback for existing setups, and are read only when the canonical names are unset. Both bundled Compose files forward them; docker-compose.dev.yml did not before v0.26.0, so a .env that still used the older names lost its storage credentials there.

MinIO is not a separate type — it is the s3 backend. Path-style addressing is enabled only when S3_ENDPOINT is set, which is what MinIO and other S3-compatible stores need. Leave S3_ENDPOINT unset for AWS S3 and the client derives the regional endpoint and uses virtual-hosted addressing. As with PostgreSQL, a production build refuses to start with empty or placeholder S3 credentials. A set S3_ENDPOINT must be an absolute http:// or https:// URL (v0.26.0+); minio:9000 without the scheme still starts the gateway, but it logs an error at boot and keeps media on the local directory.

Everywhere that refusal does not apply, STORAGE_TYPE=s3 without credentials builds no S3 client at all and quietly writes every file to the local directory instead. Since v0.23.4 that degradation is announced at startup, naming the half of the pair that is unset rather than declaring both absent, since arriving here with one of them set is a typo in the other:

STORAGE_TYPE=s3 but S3_SECRET_ACCESS_KEY is not set; media is being written to the local dir
'./data/media' instead of the bucket. The built-in MinIO uses minioadmin/minioadmin.

MINIO_BUILTIN=true does not supply those credentials. Saving storage settings from the dashboard writes them for you when you pick the built-in MinIO; setting the flag by hand only starts the bundled container, so a hand-edited .env still needs both keys. Neither bundled Compose file forwards MINIO_BUILTIN, so a flag in a host .env never reaches the container there: start the bundled MinIO with docker compose --profile minio up -d, or save the storage settings in the dashboard, which writes the flag to data/.env.generated.

Cache — Redis (optional)​

Caching is off by default, and there is no in-process cache: "no cache configured" means no cache. The cache layer fails open — when Redis is disabled or unreachable, the cache connection check reports it unavailable and the app keeps serving from its source of truth (the database and engine). Caching is a pure optimization, never the source of truth. At v0.26.0 no request path reads or writes cached data: with Redis enabled the cache client is created on the first Infrastructure status check, but nothing reads from it, and what Redis changes in practice is where the rate-limit counters live and how WebSocket events reach other replicas. It does not enable the queue, which needs QUEUE_ENABLED=true.

Enable Redis with:

REDIS_ENABLED=true
REDIS_HOST=localhost
REDIS_PORT=6379
# REDIS_PASSWORD=your-redis-password

Engine — whatsapp-web.js or Baileys​

OpenWA ships two WhatsApp engines. whatsapp-web.js (the default) drives a headless Chromium and is heavier (hundreds of MB per session). baileys is browser-free and far lighter. Both link by QR or by phone-number pairing code; the engines differ in per-route capability rather than in how you connect them. Pin one explicitly:

ENGINE_TYPE=baileys

If ENGINE_TYPE is left unset, the active engine is chosen in the dashboard (Infrastructure → Engine), defaulting to whatsapp-web.js. A value set in the environment always wins over the dashboard selection.

Note

Switching the engine does not migrate an existing authenticated session: each engine keeps its own credentials on disk, so a session that has never run under the target engine has to be linked again, by QR or pairing code. Starting a session does not remove the other engine's credentials, so one that ran under the target engine before can re-link on its own when you switch back; deleting the session removes both. Connect a session in Connect a session.

Key environment variables​

These names are taken verbatim from .env.example, and every setting that file names has a row. Variables the terminal, the platform and Node define, such as NO_COLOR, FORCE_COLOR, PATH and NODE_EXTRA_CA_CERTS, are not OpenWA settings and are not listed.

Core​

VariableDefaultDescription
NODE_ENVproductionRuntime mode; production enforces the security checks noted above. The default holds in the image, docker-compose.yml and .env.example; docker-compose.dev.yml defaults to development, and a bare run with no variable has it unset. Compose reads .env before a file's own default, so copying .env.example to .env turns the quick-start docker-compose.dev.yml stack into a production one: Swagger UI answers 404 unless ENABLE_SWAGGER=true, and a wildcard CORS_ORIGINS is refused. Left unset, the gateway boots with development defaults (no default-secret guard, wildcard CORS allowed, Swagger UI served, validation error detail exposed) and logs a warning
PORT2785Port the app binds to. The only port variable a bare-metal run or a plain docker run reads
API_PORT2785Docker Compose only: the host-side port mapped to the container's fixed 2785. Both bundled Compose files honour it (the quick-start docker-compose.dev.yml since v0.23.7; before that it published 2785 whatever this said). The app itself never reads it
BIND_HOST127.0.0.1Docker Compose only, and only docker-compose.dev.yml: the host interface the API port is published on. Set 0.0.0.0 to reach the quick-start stack from another machine, and put a TLS reverse proxy in front of anything internet-facing, since the API key travels in cleartext over plain HTTP. docker-compose.yml always publishes on 127.0.0.1. The app never reads it
OPENWA_MEM_LIMIT2gDocker Compose only: the memory ceiling of the openwa-api container (mem_limit in both bundled files). whatsapp-web.js runs a full Chromium per session, so raise it for multi-session deployments, for example 4g; Baileys is far lighter. The app never reads it
OPENWA_PIDS_LIMIT2048Docker Compose only: the process ceiling of the openwa-api container (pids_limit in both bundled files), a fork-bomb guard rather than an allocation. Each whatsapp-web.js session runs a multi-process Chromium, so raise it for larger fleets; do not set -1, which drops the guard. The app never reads it
SERVE_DASHBOARDtrueServe the bundled dashboard from the API process. Only the exact string false turns it off — startup then logs Dashboard: serving disabled (SERVE_DASHBOARD=false); API only and the process serves the API alone. Validated as a strict boolean at boot: a blank value counts as unset and any other value fails startup with SERVE_DASHBOARD must be "true" or "false". The bundled docker-compose.yml already forwards this key, so setting it in .env is enough on that path. Listed in .env.example since v0.17.0
LOG_LEVELinfoOne of error, warn, info, debug, verbose, matched after trimming and lowercasing, so DEBUG and a space-padded warn are accepted; unset or empty means info. Any other value fails startup with LOG_LEVEL must be one of "error", "warn", "info", "debug", "verbose" (got "…"), so a spelling borrowed from a neighbouring vocabulary (log, trace, warning) now refuses to boot where it used to be ignored and leave the level at info (v0.23.5+, breaking)
LOG_FORMATjson in production, else prettyConsole log format, json or pretty, matched after trimming and lowercasing; any other value is ignored and the default applies. The default is json under NODE_ENV=production and pretty otherwise
AUTO_START_SESSIONSfalseAuto-start previously authenticated sessions on boot. Since v0.24.0 an explicit stop or force-kill stays stopped across restarts and takeover until an explicit start. The app-level default stays false, but the quick-start docker-compose.dev.yml sets it to true (v0.10.0+), so on that path authenticated sessions come back by themselves after a container restart. Boot starts only linked sessions left disconnected: one that ended failed stays down until an explicit start. With the flag off, since v0.30.3 the log says how many linked sessions were left disconnected and how to start them (action=auto_start_disabled), at boot and when the takeover sweep marks a session that a vanished node left behind as disconnected
STATUS_SEED_ON_READYfalseBackfill active statuses that predate a connection as soon as a session reaches READY. Off by default since v0.14.0: the eager status@broadcast read could make WhatsApp revoke some freshly paired whatsapp-web.js companions at their first scheduled Web reload. Live status events are unaffected either way; flip to true to restore the pre-0.14.0 backfill (v0.14.0+, breaking)
MAX_CONCURRENT_SESSIONS0Cap on the sessions one node runs at once; 0 is unlimited. It counts sessions that hold an engine, an initialization slot or a pending relaunch after a failed reconnect; a FAILED session holds none. A start at the cap answers 400 (Maximum concurrent sessions reached (N)) and launches nothing, and auto-start stops when it reaches the cap. A non-negative integer; anything else fails boot
CORS_ORIGINS*Comma-separated allowed origins; the * wildcard is refused in production
CSP_UPGRADE_INSECURE_REQUESTSunsetWhether the dashboard's Content-Security-Policy carries upgrade-insecure-requests, which makes a browser fetch the page's own scripts over HTTPS. Unset means on under NODE_ENV=production and off otherwise. Only the exact strings true and false are accepted: a blank value counts as unset, and any other value fails boot (v0.24.0+). The production default is right behind a TLS-terminating reverse proxy. For a deployment reached over plain HTTP, such as a direct host:port or a trusted private network, set false: the gateway's boot warning for a production dashboard with the directive on says "If this instance is reached over plain HTTP, the browser will upgrade the UI's scripts to https:// and the dashboard will render blank."
BASE_URLhttp://localhost:<PORT>Public base URL of the API. It is used in the startup banner, as the apiBaseUrl the settings API reports, and to build the ingress URLs of plugin instances, which are relative paths when it is unset; a trailing slash is trimmed from those
DASHBOARD_URLthe value of BASE_URLPublic URL of the dashboard, shown in the startup banner. The bundled dashboard is served on the API's origin, so the default is the API base URL
SHUTDOWN_DELAY_MS3000 (0 in development/test)Delay between marking readiness unavailable and teardown, capped at 30000 ms. Default deployment grace is 75 s; increase it by any excess over 3000 ms here and over 5000 ms in WEBHOOK_SHUTDOWN_DRAIN_MS
REQUEST_TIMEOUT_MS300000HTTP server request timeout in milliseconds. Raise it when a reverse proxy in front holds connections longer
HEADERS_TIMEOUT_MS65000HTTP headers timeout in milliseconds
KEEPALIVE_TIMEOUT_MS5000HTTP keep-alive timeout in milliseconds
TZunset (the image runs UTC; both bundled Compose files forward ${TZ:-UTC})Process time zone. Stored timestamps are UTC on both databases whatever it says (on PostgreSQL since v0.23.6; up to v0.23.5 the columns the gateway writes itself there took the process's zone), so it only sets the zone log stamps are shown in and the local day the dashboard's today counts cover. Under LOG_FORMAT=json every entry keeps an ISO UTC timestamp, framework lines such as [RoutesResolver] at startup and the [ExceptionsHandler] error line included (they go through the OpenWA logger since v0.24.0), while every pretty line is stamped in this zone. Listed in .env.example and forwarded by both bundled Compose files since v0.23.6

Adapters​

VariableDefaultDescription
ENGINE_TYPEunset (falls back to whatsapp-web.js)whatsapp-web.js or baileys; dashboard chooses when unset
SESSION_DATA_PATH./data/sessionsWhere whatsapp-web.js session auth data is stored
BAILEYS_AUTH_DIR./data/baileysWhere Baileys session auth data is stored
BAILEYS_BROWSER_NAMEUbuntuBaileys linked-device name, also sent in a phone-number pairing request. Since v0.25.0 the default is a standard OS name because some accounts reject OpenWA. Existing pairings keep their name; set OpenWA explicitly to preserve the old name for new pairings. Read once at boot, so restart the gateway after changing it
RESOLVE_LID_TO_PHONEfalseWhen a sender is identified only by a privacy id (@lid), attach a best-effort senderPhone (phone digits, or null when nothing maps it) to the message.received webhook and WebSocket payload, on both engines. Off by default because it adds a cached lookup per sender. GET /api/sessions/{sessionId}/contacts/{contactId}/phone answers whether or not it is set. On Baileys a lookup reads the stored mapping, then Baileys' key store (v0.24.0+), and an id the engine cannot map is looked up again at most once a minute per sender (v0.24.0+). Exact true or false; anything else fails boot
STORE_EPHEMERAL_MESSAGEStrueWhether incoming WhatsApp disappearing messages (ephemeralDuration above 0) are persisted and dispatched. false skips them, history backfill included; a message the account sends is still dispatched, only its storage is skipped. On Baileys, since v0.31.0, false also keeps no copy of a received disappearing message in the engine's own message store (baileys_stored_messages, which a backup carries) and downloads none of its media. Without the copy, an operation that needs the message (reply, forward, react, edit, star, pin, unpin, delete by id, click-button, or a send that quotes it) answers 404, a group read receipt that names it leaves it out, an encrypted edit, reaction or poll vote aimed at it is not delivered once it has been processed, an RSVP to an event it carries is not reported, and while it is a chat's newest message the chat lists an empty lastMessage; a plain edit or reaction of it is still announced. A message the account sent or typed on its phone, and a status, keep the engine's copy, and a copy stored before the flag was turned off stays until BAILEYS_MESSAGE_STORE_LIMIT evicts it. whatsapp-web.js keeps no store of its own, so its history read and the chat list's lastMessage still return a disappearing message, which WhatsApp Web holds until it expires. Exact true or false; anything else fails boot
SIMULATE_TYPINGtrueHumanise single text sends: show a typing indicator and pause before each send so messages do not look instantaneous. false turns it off. Bulk sends are not affected, they have their own delayBetweenMessages throttle. Exact true or false; anything else fails boot
SIMULATE_TYPING_MAX_MS5000Cap, in milliseconds, on the planned pause. The planned pause is 500 ms plus 45 ms per character of the text, up to this cap, and the pause taken is that value scaled by a random factor between 0.85 and 1.15 and then held to the cap (v0.26.0+; before, it could run 15% past the cap). 0, a negative, a blank or a non-numeric value keeps the default (a negative value cut the pause to about 1 ms before v0.26.0)
LID_MAPPING_CACHE_MAX5000LRU cap on the in-memory @lid→phone mirror used for synchronous resolution on the dispatch hot path; a miss falls back to engine re-resolution. Since v0.23.6 the store also remembers, under the same cap, lids the table has no row for, so an unmapped lid is not looked up in the table again on every dispatch. 0 restores the legacy unbounded behavior and keeps no such record: every lookup of an unmapped lid reads the table, as it did at any cap before v0.23.6. Since v0.31.0 the same cap also bounds the marks of lids whose phone failed to reach the table: past it the oldest mark is forgotten, and that lid, with a small share of the others (0.5 percent after 5000 are forgotten), answers no phone while it has no cache entry, until it is reported again, the mapping reloads or the gateway restarts, and a warning names the bound. Lids reported again after their mark was forgotten are bounded by the same cap: past it the oldest, once it has no cache entry, answers no phone again in the same way. With 0 these records are unbounded as well
BAILEYS_SESSION_STORE_MAX_ENTRIES5000Per-map LRU cap on the Baileys session store's in-memory maps (contacts, chats, last messages, the newest message each chat received, lid mappings and disappearing-message timers, all fed by peer traffic), and since v0.28.0 the cap on how many chats are seeded from stored messages when a Baileys session starts after a restart (ordered by newest stored message of the linked account, with timestamp, lastMessage and lastMessageType populated and unreadCount set to 0). A lid-mapping miss falls back to the persisted table or a re-resolution, and a disappearing-message timer miss only to the timer on the chat record, which WhatsApp often leaves out; any other evicted entry stays gone until new traffic for that chat or contact adds it back. The next message in a chat, including one sent through the API, lists the chat again, though a group then shows the bare user part of its id as its name until its subject is fetched again, at the next reconnect or when the subject next changes, and its last message comes back with the next message received in that chat, sent from the phone or another linked device, or sent through the API (v0.23.7+); for a group the account is in, the next reconnect also restores its chat entry with its subject, and since v0.28.0 a start after a restart seeds stored messages for groups as well. Until then an evicted chat is missing from GET /api/sessions/{sessionId}/chats, an evicted peer contact answers 404 on GET /api/sessions/{sessionId}/contacts/{contactId} and a name lookup for it falls back to the bare user part of its id, a chat whose last message was evicted and has no stored row answers success: false to archive, unread, clear and delete, a read without message ids answers success: false until a message is received in that chat (a message the account sends does not restore the entry it uses), and a send into a disappearing chat whose timer was evicted may go out without the timer. 0 = unbounded. In the contacts map it bounds the peers only: a contact with a name saved on the phone is never evicted, so that side is bounded by the account's own address book and lowering this knob does not shrink it (v0.23.6+). Before v0.23.6 saved contacts shared the cap with peers seen once in a group or a broadcast, and a busy session listed fewer and fewer of them
BAILEYS_CHAT_STATE_CACHE_MAX5000Global LRU cap on the in-memory Baileys chat mute/archive/pin mirror, shared by every session; raise it for many sessions or large chat lists. An evicted row stays persisted: a write reads it back before merging, so a single-field update never wipes the fields it omits, and a read that misses returns the defaults once while the entry warms for the next lookup. 0 = unbounded. Listed in .env.example and forwarded by both bundled Compose files since v0.23.5
BAILEYS_MESSAGE_STORE_LIMIT5000Per-session cap on Baileys message rows kept in the database: the newest N survive and older rows are pruned after each write. A non-positive or non-numeric value fails boot (v0.24.0+). Baileys reports poll.vote (v0.30.2+) only while the poll's creation message is still in this store: a vote on a poll the cap has evicted, or cast before the store held the poll, is not reported
BAILEYS_GROUP_METADATA_CACHE_TTL_MS300000How long, in milliseconds, a Baileys session reuses a group's cached participant list instead of querying WhatsApp (5 minutes; before v0.26.0 every group send queried it). Since v0.28.0 the same cached list also backs the roster check on the first receipt of an own group message (used to advance aggregate message.ack to delivered and read) and the admin check when a group member deletes another member's message. A membership or settings event for the group, a refresh of the group listing, a reconnect and a write to the group each drop the cached list early. 0 queries for every send, for the first receipt of every own group message, and for a delete of a settled message that is not provably the sender's own. A non-negative integer; anything else fails boot. Read when a session starts. Baileys engine only. Both bundled Compose files forward it (v0.26.0+)
BAILEYS_MARK_ONLINE_ON_CONNECTtrueWhether a Baileys session marks the account online when it connects. Set false to keep phone push notifications alive while a gateway is connected (v0.13.0+). The default preserves prior behavior
BAILEYS_SYNC_FULL_HISTORYfalseRequest the full message-history archive when the device is linked, which is large. Set it before linking: an already-linked session must be re-linked to receive it. Off, the engine still enables the initial sync: WhatsApp sends the recent message window and the full contact and app-state snapshot, so contacts, chats, recent messages and lid mappings arrive, but not the entire history. Exact true or false; anything else fails boot. Baileys engine only
BAILEYS_LOG_LEVELsilentSurfaces the Baileys library's own logs: trace, debug, info, warn or error, matched case-insensitively; unset or any other value keeps it silent. Lines go to stdout as JSON with the context baileys-wire, independent of LOG_LEVEL, and trace dumps the decoded WhatsApp wire frames, so use it only while debugging. Baileys engine only
BAILEYS_WA_VERSIONunsetPins the WhatsApp Web protocol version the Baileys engine links with, skipping every remote tier of the version resolver (v0.22.0+). Unset, the resolver tries the two library endpoints (web.whatsapp.com's service worker, then the upstream repository), then the last known-good version cached on disk in the auth dir, then a built-in default; each remote tier is timeout-bounded, rides the session proxy, and a stale answer is neither cached nor used
PUPPETEER_HEADLESStrueRun the whatsapp-web.js browser headless. Only the exact string false turns it off; any other value leaves it on. Not validated at boot. whatsapp-web.js engine only
PUPPETEER_ARGS(four flags)Chromium launch flags for the whatsapp-web.js engine, --no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu by default, separated by commas or spaces (a comma splits only before the next flag, so a value such as --window-size=1280,720 survives). Setting it REPLACES the default list, so repeat the flags you still need: dropping --no-sandbox stops Chromium launching in a container. --lang=en-US is appended unless one of your flags starts with --lang
PUPPETEER_EXECUTABLE_PATHunsetPath to a system Chromium or Chrome binary; the image and both Compose files set /usr/local/bin/puppeteer-chrome. Unset uses Puppeteer's bundled browser; set it only on a host without a usable bundled browser, such as Alpine or ARM. whatsapp-web.js engine only
PUPPETEER_PROTOCOL_TIMEOUT_MSunset (Puppeteer's own budget, 180000 today)How long a single browser command may run before it is abandoned, in milliseconds. whatsapp-web.js engine only, and leaving it unset changes nothing. Raise it when a large account (thousands of chats) fails a read with Runtime.callFunctionOn timed out: the renderer is still working, the command budget just ran out. Since v0.23.6 the same expiry on the group read, the invite preview and join, the chats-by-label read, the single-contact read, or a chat action (read, unread, archive, clear, delete, and the chat lookup that mute and pin run first) answers a retryable 503 whose message starts WhatsApp Web did not answer, and a write such as archiving a chat or accepting an invite may still have been applied; before, it read as a 404, a 400 or success: false. Since v0.24.0 the chat, group and contact list reads, the mute, unmute, pin and unpin writes themselves, and PUT /api/sessions/{sessionId}/presence answer the same 503 instead of a 500. Must be a positive integer no greater than 2147483647, and the gateway refuses to boot on anything else. 0 arms no timer at all, so a wedged browser would hold the request forever; a larger value overflows Node's timer and fires after 1 ms, so the browser never finishes launching (v0.23.4+)
WWEBJS_ONBOARDING_CONTINUE_LABELS(empty)Extra comma-separated labels for the whatsapp-web.js onboarding-modal auto-dismiss: a deployment whose modal is localized (not English) adds its Continue-button label(s) here, and the watcher matches them without the English heading check (v0.12.1+). The browser is launched with --lang=en-US unless PUPPETEER_ARGS carries its own --lang, but WhatsApp Web can still render the modal in the account's language, so a label here is what covers it; restart OpenWA after adding one, since restarting only the session does not pick it up. Since v0.23.6 such a label is clicked only on a button inside a [role="dialog"] or [aria-modal="true"] container. Before, any visible button with that exact text anywhere on the page was clicked, and each click counts toward the limit that moves a ready session to action_required
WWEBJS_AUTH_TIMEOUT_MS30000How long the whatsapp-web.js engine waits for WhatsApp Web to finish loading before QR generation, in milliseconds. Raise it (for example 120000) on slow first boots such as WSL2 or low-resource containers. Plain digits only; unset or a value that is not a positive integer keeps the default. The session start deadline is the larger of 60 seconds and this value plus 30 seconds, so a value above 30000 raises that deadline. Since v0.31.0 (whatsapp-web.js 1.34.8) the same budget also bounds the wait for the page's connection to WhatsApp to open, which had no limit of its own before, so a start on a host where that connection is slow now fails instead of waiting: raise this value there and start the session again. A start that uses both waits can run into the start deadline first, which answers the generic 504 and leaves the session disconnected; the library's own timeout answers the auth-timeout 504 and leaves it failed, which boot auto-start does not retry
WWEBJS_WEB_VERSIONunset (same as auto)Pins the WhatsApp Web build the whatsapp-web.js engine loads. Unset, auto or latest resolves the current build from the third-party wppconnect-team/wa-version registry and pins it; since v0.29.0, if the newest build's HTML in the registry is WhatsApp Web's logged-out landing page (<html id="whatsapp-web-logged-out">, quoted or unquoted since v0.29.1), the resolver rejects it (logging web_version_html_rejected), checks up to 3 builds from newest to oldest, and pins the newest settled build (stepping through the ranked list from that same registry read without a second registry fetch since v0.29.1). off pins nothing and leaves the choice to whatsapp-web.js; any other value is an exact build number, pinned without a registry lookup or logged-out page check. The pinned build's HTML is downloaded from WWEBJS_WEB_VERSION_REMOTE_PATH and executed inside the web.whatsapp.com origin with no integrity check, so point that variable at a mirror you control if you do not want to trust the public registry. whatsapp-web.js engine only
WWEBJS_WEB_VERSION_REMOTE_PATHhttps://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/{version}.htmlURL template the pinned WhatsApp Web build's HTML is fetched from, with {version} as the placeholder. Point it at an operator-controlled mirror instead of the public third-party registry. A pin is not guaranteed to hold, and it can miss in two ways. When this URL does not serve a usable pinned HTML (a network error, a non-2xx answer, or under auto/latest all 3 newest registry candidates serving the logged-out landing page, v0.29.0+), the pin is dropped and the session loads WhatsApp's live build: the startup line Pinning WhatsApp Web version <build> is not logged, and the gateway logs a warning Could not load the pinned WhatsApp Web build; continuing WITHOUT a pin with action web_version_html_unavailable (v0.24.0+). And WhatsApp Web's service worker can answer the page load from its own cached build without the request reaching the pin at all (unless the session uses a credentialed http/https proxy, where v0.29.0+ bypasses the service worker); the startup line still names the pin then. Since v0.23.6 a session that reaches ready logs the build its page actually runs (action web_version_running); when a pin was requested and that build is not the pinned one, it logs a warning naming both builds instead (action web_version_pin_not_applied). A page that does not report its build logs neither. After switching to a mirror, check the log for web_version_html_unavailable first, then for web_version_pin_not_applied; if the mirror does serve the pinned HTML, the service worker can still cause the latter, and a later restart may load the pin. See Troubleshooting. whatsapp-web.js engine only
DATABASE_TYPEsqlitesqlite or postgres
POSTGRES_BUILTINfalseStart the bundled PostgreSQL container through the Docker daemon (DOCKER_HOST) at boot. Since v0.26.0 it starts only while DATABASE_TYPE=postgres and the environment or the project .env does not pin DATABASE_HOST to another server; before, the flag alone started it. A container OpenWA creates is initialised with the DATABASE_PASSWORD the next boot will use, or openwa when none is set (v0.26.0+), so a custom password saved with the built-in database no longer fails the next boot; a data volume that already exists keeps the role password it was created with. In a production build the flag also exempts the bundled container from the placeholder check on DATABASE_PASSWORD, but only while DATABASE_HOST is unset or names the container: postgres, or since v0.26.0 also openwa-postgres, in any letter case and with a trailing dot. See DATABASE_SSL for the TLS refusal. Exact true or false; anything else fails boot. Neither bundled Compose file forwards it: use the postgres profile, or save the database settings in the dashboard, which writes the flag to data/.env.generated
DATABASE_HOST(none)PostgreSQL host (ignored for SQLite). Required when DATABASE_TYPE=postgres: a blank value refuses boot in every environment, naming the key
DATABASE_PORT5432PostgreSQL port
DATABASE_NAMEopenwaPostgreSQL database name
DATABASE_USERNAME(none)PostgreSQL user (ignored for SQLite). Required when DATABASE_TYPE=postgres: a blank value refuses boot in every environment, naming the key
DATABASE_PASSWORD(empty)Required for PostgreSQL in every environment; no default shipped. A production build also refuses a known placeholder
DATABASE_SSLfalseEnable TLS for managed PostgreSQL. The built-in PostgreSQL container runs without TLS, so DATABASE_SSL=true beside DATABASE_TYPE=postgres, POSTGRES_BUILTIN=true and a DATABASE_HOST that names the container (postgres or openwa-postgres) is refused at boot (v0.26.0+); set DATABASE_SSL=false, or use an external PostgreSQL
DATABASE_SSL_REJECT_UNAUTHORIZEDtrueVerify the PostgreSQL server certificate when DATABASE_SSL=true. Only the exact string false turns verification off, to accept a self-signed certificate; any value other than true or false fails boot. Forwarded by both Compose files (v0.23.7+)
DATABASE_POOL_SIZE10PostgreSQL connection pool size (ignored for SQLite)
DATABASE_STATEMENT_TIMEOUT_MS30000PostgreSQL only: aborts a single runtime query that runs longer, enforced by the server. The boot migrations are not subject to it, so a long migration during an upgrade is not cancelled at 30 seconds. 0 disables it. A non-negative integer no greater than 2147483647; anything else fails boot
DATABASE_IDLE_TIMEOUT_MS30000PostgreSQL only: closes an idle pooled connection after this long, in milliseconds. 0 disables it. A non-negative integer no greater than 2147483647; anything else fails boot
DATABASE_CONNECTION_TIMEOUT_MS10000PostgreSQL only: fails a new connection that cannot be acquired in this time, in milliseconds. 0 disables it. Each new connection sets statement_timeout, TimeZone (UTC), and any non-default search_path by statements after connect instead of in the startup packet, so PgBouncer in session mode needs no ignore_startup_parameters (v0.27.0+), and each statement is held to the same deadline (10000 ms when this is 0), so a database that accepts the connection and then stalls fails it instead of hanging the boot (v0.26.0+). A non-negative integer no greater than 2147483647; anything else fails boot
POSTGRES_SCHEMApublicPostgreSQL schema that holds OpenWA's tables and migration ledger (ignored for SQLite). It must already exist: the postgres Compose profile creates it when its data volume is first initialized, and on external or managed PostgreSQL you create it once (CREATE SCHEMA openwa;). Lower case only: a lower-case letter or underscore, then lower-case letters, digits and underscores, at most 63 characters, and no pg_ prefix. Since v0.23.6 (breaking) a mixed-case value is refused at boot, by that init script, by the migration CLI and on the dashboard's Infrastructure page, naming the rule; before, a mixed-case name was accepted and split the tables across two schemas. The same release also refuses a value with surrounding whitespace at boot, in the migration CLI and on that page, as the init script already did; before, boot checked only a trimmed copy and the gateway passed the padded value to PostgreSQL, so the connection failed
MAIN_DATABASE_NAME./data/main.sqliteSQLite file backing the main (auth and audit) connection, which is always SQLite. Must not resolve to the same file as DATABASE_NAME
MAIN_DATABASE_SYNCHRONIZEfalseMain database migrations run at every boot (v0.24.0+), adopting existing rows in place. true additionally synchronizes; leave it off for production. A newer migration ledger or missing recorded column stops boot
DATABASE_SYNCHRONIZEfalseData database (docker-compose.dev.yml defaults it to true): true makes TypeORM synchronize the schema from the entities at boot instead of running the migrations, for zero-config SQLite development; leave it false in production. Only the exact string true enables it. With DATABASE_TYPE=postgres a true value fails boot, because synchronize would drop the body_ts full-text column that /search depends on. The main database has its own switch, MAIN_DATABASE_SYNCHRONIZE
DATABASE_LOGGINGfalsetrue makes TypeORM log every query of both databases with its bound parameters, and those parameters carry message bodies, phone numbers and webhook payloads. Debugging only, on a local data set: never enable it in production or hand the logs to a wider audience than the database itself. Exact true or false; anything else fails boot
STORAGE_TYPElocallocal or s3
MINIO_BUILTINfalseStart the bundled MinIO container through the Docker daemon (DOCKER_HOST) at boot. Since v0.26.0 it starts only while STORAGE_TYPE=s3 and the environment or the project .env does not pin S3_ENDPOINT to another server; before, the flag alone started it. In a production build it also exempts the bundled container's fixed credentials from the placeholder check, but only while S3_ENDPOINT points at the host minio, or since v0.26.0 also openwa-minio, in any letter case and with a trailing dot. It does not write the S3 credentials (see the Storage section above). Exact true or false; anything else fails boot. Neither bundled Compose file forwards it: use the minio profile, or save the storage settings in the dashboard, which writes the flag to data/.env.generated
STORAGE_LOCAL_PATH./data/mediaLocal media directory. Since v0.31.0 it is owner-only: the gateway sets it 0700 at every boot, whatever STORAGE_TYPE is (with s3 it still holds the files stored before the move to s3 and any fallback written while the bucket was unreachable or the S3 settings were unusable, see the Storage section above), and writes new directories and files 0700 and 0600. Files written earlier keep their mode but sit under the 0700 root. A directory the gateway does not own keeps its mode, and boot logs a warning when that mode is open to other users. A process that reads this directory or the storage export archives as another user, such as a static file server or a backup job under another uid, loses access: run it as the gateway's user (the image runs the gateway as openwa)
STORAGE_LIST_MAX_FILESremovedRemoved in v0.26.0: a leftover value is ignored instead of validated at boot, and neither bundled Compose file forwards it. Before v0.26.0 it was the cap on how many files one local-storage listing call enumerates (default 100000), so a large media directory cannot be walked into memory in a single request. A non-positive or non-numeric value fails boot (v0.24.0+); streaming reads are unaffected — only the listing call is truncated
S3_ENDPOINTunsetS3-compatible endpoint (MinIO, R2). Leave it unset for AWS S3, which derives its endpoint from the region; setting it also switches the client to path-style addressing. A set value must be an absolute http:// or https:// URL (v0.26.0+): with STORAGE_TYPE=s3, a value without the scheme, such as minio:9000, still starts the gateway but logs an error at boot and keeps media on the local directory, and the Infrastructure page refuses to save such an endpoint when the save changes it or newly selects S3, and only while S3 is the selected storage type
S3_BUCKETopenwaS3 / MinIO bucket
S3_REGIONus-east-1S3 region
S3_KEY_PREFIXmedia/Relative object-key root (v0.24.0+). Separate deployments sharing a bucket need non-overlapping prefixes; empty segments, . and .., and absolute prefixes fail boot. Changing it does not move existing objects
S3_ACCESS_KEY_ID(empty)S3 / MinIO access key; required for s3. S3_ACCESS_KEY is a legacy alias, read only when this is unset
S3_SECRET_ACCESS_KEY(empty)S3 / MinIO secret key; required for s3. S3_SECRET_KEY is a legacy alias, read only when this is unset
S3_REPROBE_INTERVAL_MS60000Re-probe cadence for an S3 bucket that was unreachable at boot (media storage falls back to the local dir until it recovers). Recovery is one-way — local→S3 only, so a transient flake cannot drop a healthy deployment to local; while S3 is active, listings and totals also cover the local fallback dir, and deletes go to both backends
STORAGE_IMPORT_MAX_BYTES209715200Per-file extracted import cap (200 MiB); each file may take about twice its size in memory
STORAGE_IMPORT_MAX_ENTRIES100000Maximum files extracted by one storage import
STORAGE_IMPORT_MAX_TOTAL_BYTES10737418240Total extracted-byte cap (10 GiB, v0.25.0+). An aborted import keeps files already written; raise the named cap before retrying
STORAGE_EXPORT_TTL_MS3600000How long a storage export archive is kept before it is deleted, in milliseconds (1 hour). A positive integer no greater than 2147483647; anything else fails boot (1h included). The archive is written 0600 in data/exports, a 0700 directory (v0.31.0+); the next boot also closes a data/exports that an earlier version left open
STORAGE_EXPORT_SWEEP_MAX_AGE_MS86400000Boot sweep deletes orphaned storage-export-* archives older than this (24 hours)
EXPORT_INLINE_MEDIA_BUDGET_BYTES8388608How much inline base64 media one GET /api/infra/export-data may carry, in encoded bytes (8 MiB). Past it a message payload is exported as the omitted marker and a bulk-batch entry loses its base64, because an unbounded export produces a backup the import refuses with 413 (the import rides BODY_SIZE_LIMIT). It is spent newest-first within each table, and an http or https payload is a pointer, never counted or dropped. 0 omits every payload. A non-negative integer; anything else fails boot
REDIS_ENABLEDfalseUse Redis for the rate-limit store, the cache connection and cross-replica WebSocket event fan-out (Socket.IO Redis adapter). It does not enable the queue: that needs QUEUE_ENABLED=true, which neither bundled Compose file forwards, so under Compose turn it on in the dashboard under Infrastructure. Multi-replica deployments need this so a WS client on one replica receives events raised on another; single-node can leave it off (WS fan-out added in v0.14.0+)
REDIS_BUILTINfalseStart the bundled Redis container through the Docker daemon (DOCKER_HOST) at boot. Since v0.26.0 it starts only while Redis is in use (REDIS_ENABLED, QUEUE_ENABLED or CACHE_ENABLED is true) and the environment or the project .env does not pin REDIS_HOST to another server; before, the flag alone started it. Exact true or false; anything else fails boot. Neither bundled Compose file forwards it: use the redis profile, or save the Redis settings in the dashboard, which writes the flag to data/.env.generated
QUEUE_ENABLEDfalseProcess webhook deliveries and plugin ingress events through the BullMQ queue instead of dispatching inline. It needs a reachable Redis (REDIS_HOST, REDIS_PORT) and is independent of REDIS_ENABLED. Exact true or false; anything else fails boot. Neither bundled Compose file forwards it, so a value in .env does nothing there: switch it on with the Enable BullMQ Queue System switch in the Redis card of Dashboard → Infrastructure (it appears once Redis is enabled), which saves it to data/.env.generated, or forward it in a docker-compose.override.yml. Before turning it off, let webhook-queue and ingress-queue drain (no waiting, delayed or active jobs): with it off, the reconcilers replay pending rows inline whatever Redis still holds, so a job left in either queue runs again when the queue is turned back on, a second delivery of the same event
QUEUE_PREFIXbullRedis key prefix of the BullMQ queues (webhook and ingress deliveries), used while QUEUE_ENABLED=true (v0.26.0+). Deployments that share one Redis must each set their own, or one's workers take the other's webhook jobs and complete them without delivering. Replicas of one deployment share a value. Changing it on a live deployment leaves the jobs queued under the old prefix unprocessed. Up to 64 letters, digits, dots, underscores or hyphens, starting with a letter or digit; a blank value counts as unset and anything else fails boot. It covers the queues only: with REDIS_ENABLED=true the rate-limit counters and the WebSocket fan-out are shared too, and events reach the clients of every deployment on that Redis, so such deployments need a Redis each. Both bundled Compose files forward it
CACHE_ENABLEDfalseTurns the Redis cache on without REDIS_ENABLED: the cache is on when either is true, and false does not turn it off while REDIS_ENABLED=true. No request path reads the cache at v0.26.0 (see the Cache section). Exact true or false; anything else fails boot
REDIS_HOSTlocalhostRedis host
REDIS_PORT6379Redis port
REDIS_USERNAME(none)Redis ACL username, used by the cache, the rate-limit store, the queue and the WebSocket fan-out. Leave it unset for a Redis without ACL users. The built-in Redis has only its default user, so any other name is refused at boot under the conditions given for REDIS_TLS (v0.26.0+)
REDIS_PASSWORD(none)Redis password, used by the same connections. A production build refuses to start on a known placeholder value; an empty or unset password is allowed, since a passwordless Redis on a private network is supported
REDIS_CACHE_DB1Redis logical database for the cache; the queue uses the default database. A non-negative integer; anything else fails boot
REDIS_CONNECT_TIMEOUT_MS5000How long a Redis connection attempt may take before it fails, in milliseconds. Queue calls made before Redis has ever connected wait at most this long from the first call, then take the same fallback as an unreachable Redis until it connects. 0 disables the socket connection timeout; that queue wait then still uses 5000. A non-negative integer; anything else fails boot
REDIS_TLSfalseTLS for cache, rate limiting, queues, and WebSocket fan-out (v0.24.0+). Set a private CA through NODE_EXTRA_CA_CERTS in the launching environment, not .env. The built-in Redis serves plain TCP only, so REDIS_TLS=true is refused at boot when Redis is in use (REDIS_ENABLED, QUEUE_ENABLED or CACHE_ENABLED is true), REDIS_BUILTIN=true and REDIS_HOST names the container (redis or openwa-redis) (v0.26.0+); set REDIS_TLS=false and clear the username, or use an external Redis. Saving the built-in Redis from the Infrastructure page sets it to false and clears REDIS_USERNAME, unless the environment or the project .env pins REDIS_HOST to another server
NODE_IDhostnameIdentifies the process owning a session's engine in a multi-process deployment. Defaults to the hostname and must be stable across restarts so a returning process reclaims its sessions. A single-process deployment needs none of the multi-node vars (v0.14.0+)
NODE_URL(empty)Where THIS node answers HTTP for its peers, e.g. http://10.0.0.5:2785. Set on EVERY node to enable forwarding of session-scoped requests to the owning node. Empty disables forwarding, which is the single-node default (v0.14.0+). Must be an absolute http(s) URL without credentials, or boot fails. A path in it is kept and put in front of every forwarded /api/... path (v0.23.7+; before, the path was discarded), so give one only for a reverse-proxy prefix: a value ending in /api forwards to /api/api/...
SESSION_PROXY_TIMEOUT_MS60000Ceiling for one request forwarded to the owning node when NODE_URL routing is on, in milliseconds. Since v0.28.0 it covers the response headers and up to the first 4 MiB of the response body, while larger responses (such as media downloads or chat history with inline media) stream to the caller as they arrive. A forward that passes it answers 504. A positive integer no greater than 2147483647; anything else fails boot
SESSION_LEASE_TTL_MS60000How long a node's claim on a session survives unrenewed (60 seconds); also the worst-case failover delay after an unclean exit (v0.14.0+)
SESSION_LEASE_HEARTBEAT_MS20000Lease renewal cadence (20 seconds). Must be strictly less than half SESSION_LEASE_TTL_MS, so one late or failed renewal still lands inside the lease — boot fails otherwise (v0.14.0+)
SESSION_TAKEOVER_SWEEP_MS30000How often a node sweeps for sessions whose holder's lease lapsed, whether a crashed peer or this node's previous container identity (v0.14.0+). Adopting them follows AUTO_START_SESSIONS, but the sweep itself runs on every node whatever that flag says, because it also corrects the status a vanished node left behind: a ready, initializing, authenticating or action_required row (and a qr_ready one only while it has no phone) is marked disconnected once its lease has been expired for more than twice SESSION_LEASE_TTL_MS (v0.23.5+)

Security, webhooks, and rate limiting​

VariableDefaultDescription
API_MASTER_KEY(empty)Seeds the first admin key, read only while no API key exists; see API key authentication. Since v0.28.0 its value is never printed in the startup banner (which logs Master key from API_MASTER_KEY environment variable (not shown in logs)), and its keyPrefix in GET /api/auth/api-keys is (master key). Set later, it creates no key and replaces none, and the seeded key keeps working: rotate by creating a new ADMIN key and revoking the old one. In production a known placeholder refuses every boot. A set key shorter than 32 characters refuses every boot too — unset stays allowed (v0.19.0+, breaking)
ALLOW_DEV_API_KEYfalseLocal development only: on the first boot (no API key yet) true seeds the well-known, insecure dev-admin-key as the admin key instead of a random one. Ignored when API_MASTER_KEY is set, and a production build refuses to start with it true. Exact true or false; anything else fails boot. Only docker-compose.dev.yml forwards it
BOOTSTRAP_KEY_FILE./data/.api-keyWhere the admin key created on first boot, generated or supplied through API_MASTER_KEY, is written, and read back from on later boots. Override it when the data directory is read-only, or when the key must land on a mounted secret path
API_KEY_PEPPERunsetServer-side pepper for HMAC key hashing; recommended in production. Set it before the first boot: enabling or changing it on an install that already has keys makes every key, the admin key included, answer 401
METRICS_TOKENunsetEnables the Prometheus scrape endpoint GET /api/metrics by naming its bearer token. Unset, the endpoint answers 404; set, a scraper sends Authorization: Bearer <token>, a missing or wrong token answers 401, and a client that keeps failing gets 429. A production boot refuses the .env.example placeholder (change-me-to-a-long-random-string) and the known weak values the other secrets are checked against, such as test, change-me and password, compared after trimming and ignoring case (v0.26.0+, breaking); set a long random token, or leave it unset to keep the endpoint disabled
TRUSTED_PROXIES(empty)Comma-separated IPv4 or IPv6 addresses and CIDRs (for example 172.18.0.0/16 or fd00::/8) of reverse proxies whose X-Forwarded-For header is trusted when resolving the client IP. Empty ignores X-Forwarded-For and uses the direct socket address, which prevents spoofing. The resolved IP feeds the per-key allowedIps check, the rate limiters and the in-flight body budget, so set it behind a reverse proxy or tunnel. An entry that is neither an address nor a CIDR is ignored with a boot warning
AUDIT_RETENTION_DAYS90Days of audit log kept; older rows are pruned once at startup and every 24 hours after. 0 or any negative value disables pruning entirely and keeps every row. Validated at boot as a plain integer of ANY sign — signed rather than positive precisely because 0 and negatives are documented off switches. 30d, 90.5, +90, and a non-numeric word such as ninety now refuse to boot with AUDIT_RETENTION_DAYS must be an integer (got "…"), where before they started and silently became 30, 90, 90, and the 90-day default. The failure is a boot refusal, not a fallback to the default (v0.17.0+, breaking)
ALLOW_UNSIGNED_INGRESSfalseRequired opt-in to load plugin ingress routes declaring signature.scheme: 'none' — such a route is an unauthenticated public endpoint, so the loader rejects it without this flag
DOCKER_HOSTunset (/var/run/docker.sock)Docker daemon endpoint used to manage the built-in datastore containers (POSTGRES_BUILTIN, REDIS_BUILTIN, MINIO_BUILTIN). OpenWA itself recognises only the exact tcp://host:port form; every other value is handed to the Docker client, which parses DOCKER_HOST again on its own — unix:// and npipe:// land back on the local socket, but any host-shaped value (https://host:2376, ssh://user@host, tcp://host:2375/path) still connects to THAT host. The bundled docker-compose.yml hard-codes its own socket proxy and forwards no value from .env, so setting this affects a non-compose run only
WEBHOOK_TIMEOUT10000Webhook delivery timeout in milliseconds
WEBHOOK_RETRY_DELAY5000Delay before the first webhook retry, in milliseconds; each later retry waits twice as long as the one before, on the queue and without it
WEBHOOK_DISPATCH_CONCURRENCY16Maximum inline webhook POSTs in flight per process when the queue is off; a delivery waiting out a retry backoff does not hold one. A positive integer; anything else fails boot. Both Compose files forward 16 by default. A quarter of it is the share that the opt-in event message.receipt may run at once (see WEBHOOK_DISPATCH_MAX_QUEUED)
WEBHOOK_DISPATCH_MAX_QUEUED1000Inline deliveries that may sit parked or asleep in a retry backoff on top of WEBHOOK_DISPATCH_CONCURRENCY; more are shed to the outbox. One session's failing receivers park at most a quarter of it. Each inline delivery holds its event's inline media, up to 4/3 × WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64, which is about 1.3 GiB per process at the defaults; QUEUE_ENABLED=true keeps it in Redis instead. A non-negative integer; anything else fails boot. Both Compose files forward 1000 by default. The opt-in event message.receipt, which a * subscription never includes, is bounded per receiving webhook instead (v0.26.0+): a quarter of WEBHOOK_DISPATCH_CONCURRENCY deliveries run at once, divided among the session's webhooks that name the event, and three quarters of this many events wait; further ones are dropped, not replayed, and counted in openwa_webhook_delivery_failures_total. A receiver that never answers holds its places for a WEBHOOK_TIMEOUT, and one session runs at most a quarter of the pool at once however many of its webhooks name the event (four at the defaults), so beyond four such webhooks one that hangs can delay its siblings
WEBHOOK_MAX_PER_SESSION16Max webhooks registered per session; registrations at or over the cap get 400 (existing ones are grandfathered). 0 = unlimited
AUTOMATION_MAX_PER_SESSION32Max autoreply rules per session; new rules at or over the cap get 400 (existing ones are grandfathered). 0 = unlimited. Every inbound message is evaluated against every rule of its session (v0.14.0+)
WEBHOOK_MAX_PAYLOAD_BYTES1048576Max serialized webhook body (1 MiB); over-cap payloads shed inline media first, then are recorded undelivered. Positive only — 0 fails boot
WEBHOOK_MEDIA_INLINE_MAX_BYTES1048576Decoded-byte cap for inline base64 media in webhook payloads and (since v0.21.0) in the message.received / message.sent Socket.IO broadcasts; larger media arrives as the { omitted: true, sizeBytes } marker. WEBHOOK_MAX_PAYLOAD_BYTES is then checked on the whole JSON body, where base64 adds a third, so at the defaults webhook media over roughly 768 KiB is shed to the marker anyway; raise the payload cap to at least 4/3 of this one plus room for the envelope. The Socket.IO broadcasts apply only this cap. 0 = never inline media
WEBHOOK_SHUTDOWN_DRAIN_MS5000How long shutdown waits for in-flight webhook deliveries, outbox replay, and operator redrive. Raising it above 5000 ms requires the same increase in deployment shutdown grace; a startup WARN fires when it is shorter than WEBHOOK_TIMEOUT
WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS0Hours terminal webhook failures retain event data for ADMIN redrive (v0.25.0+). 0 retains no payload and permits no redrive; after expiry the row remains but its payload is cleared. Message contents may be retained in the database and queue jobs
WEBHOOK_WORKER_CONCURRENCY10Queued webhook-delivery workers (only when QUEUE_ENABLED=true)
WEBHOOK_DEGRADED_SESSION_CONCURRENCYunsetPer-session cap, per node, on deliveries to failing webhook receivers (v0.24.0+), a quarter of the pool (at least 1) when unset. Once a webhook's attempt has failed, that session's later deliveries to it take a per-session slot, at most this many at a time, until the first 2xx lifts the limit; a delivery already running when the failure lands is not counted. With the queue on, the rest return to the delayed set without spending an attempt: the first wait is WEBHOOK_RETRY_DELAY (at least 1 s) and doubles with each return up to 64 times that, and every wait carries a random extra of up to its own length; with it off they park inline, and a backlog past a quarter of WEBHOOK_DISPATCH_MAX_QUEUED is recorded as a failure with attempts: 0 and replayed by the outbox. The default is a quarter of WEBHOOK_WORKER_CONCURRENCY with the queue on and of WEBHOOK_DISPATCH_CONCURRENCY with it off. Keep WEBHOOK_WORKER_CONCURRENCY above this value times the number of sessions whose receivers may fail at once, or those sessions fill the pool and every other webhook waits behind them. A positive integer; anything else fails boot
WEBHOOK_FAILURE_RETENTION_DAYS90Days to keep the delivery-failure rows behind GET /api/webhooks/delivery-failures; pruned once at startup and daily thereafter. 0 or less disables the prune and keeps every row
WEBHOOK_OUTBOX_RETENTION_DAYS7Days to keep the settled outbound-delivery records that make a webhook delivery survive a hard crash; pruned once at startup and daily thereafter. A record that can still be replayed is never pruned on age, and a non-positive value falls back to 7 rather than letting the table grow without bound (v0.23.0+)
WEBHOOK_RECONCILE_INTERVAL_MS60000Sweep cadence of the outbound-webhook reconciler, which replays deliveries a hard crash left stranded, reusing the stored idempotency key so a receiver can dedupe the retry. The sweep claims no row, so two nodes on one database can both replay a delivery. 0 disables it and a blank value keeps the default; a negative or unparseable value, or one above 2147483647, fails boot
WEBHOOK_RECONCILE_GRACE_MS60000Age a pending delivery record must pass before it counts as stranded, in milliseconds; 0 acts on a record as soon as it is seen. A non-negative integer no greater than 36500 days in milliseconds; anything else fails boot
WEBHOOK_RECONCILE_BATCH_SIZE50Stranded records replayed per sweep, oldest first. An integer of at least 1; any other value keeps the default
WEBHOOK_RECONCILE_MAX_ATTEMPTS5Replays before a record goes terminal. An integer of at least 1; any other value keeps the default
WEBHOOK_SSRF_PROTECTtrueBlock webhook deliveries to internal/reserved addresses. Since v0.20.0 the opt-out (false) no longer follows redirects: see WEBHOOK_SSRF_REDIRECTS (breaking). Not forwarded by either bundled Compose file, so the opt-out needs a docker-compose.override.yml on the Docker path; the guard stays on there whatever .env says
WEBHOOK_SSRF_REDIRECTSfalseRedirect handling when WEBHOOK_SSRF_PROTECT=false: a receiver answering 3xx fails the delivery loudly; set true only for a receiver that legitimately redirects. Before v0.20.0 the opt-out followed redirects (v0.20.0+, breaking)
WEBHOOK_CONTACT_DETAILSfalseExpose the full sender contact field set (id, number, short name, business flags, isBlocked, labels and more) on message.received (webhook and WebSocket) and on chat history, instead of the minimal { name, pushName }. Opt in only if the consumer needs it; every field comes from the already-cached contact, with no extra WhatsApp call. whatsapp-web.js only: the Baileys path never reads it. Exact true or false; anything else fails boot
SSRF_ALLOWED_HOSTS(empty)Comma-separated hostnames and IP literals, matched case-insensitively against the URL host (IPv6 brackets are stripped), that skip the SSRF block for both webhook deliveries and server-side media fetches. It is the escape hatch for trusted internal targets such as a local media store or a receiver on the Compose network. A listed name is still resolved, at webhook registration too since v0.20.0, and each delivery pins its connection to the addresses it resolved to. An internal plugin catalog or release host must be listed here as well. An entry that can never match is ignored, and since v0.26.0 the gateway warns about it at boot by position and reason: a scheme, credentials, a port, a path, a wildcard, a value the URL parser rejects, or a spelling the URL parser rewrites (for an IP address, 127.0.0.1, not 127.1). The warning lists at most 20 entries and counts the rest. Since v0.31.0 the block also covers the documentation and benchmarking ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32, 3fff::/20 and 2001:2::/48, an IPv4 range also when written as an IPv4-mapped, 6to4 or NAT64 address) and the 6a44 relay anycast address 192.88.99.2, as it already covered 198.18.0.0/15: a webhook, media or plugin URL that points into one is refused, and a receiver on such an address needs an entry here. An entry here does not lift the refusal of a redirect: a media url that answers 3xx is refused with Destination address is not allowed (400 on a single-request route, SEND_BLOCKED on a bulk item), so send the address the redirect leads to
SSRF_DNS_TIMEOUT_MS10000DNS resolution deadline in milliseconds inside the SSRF guard
INGRESS_MAX_ATTEMPTS3Queued ingress delivery attempts before an event is dead-lettered (min 1)
INGRESS_RETRY_DELAY_MS5000Base for exponential backoff between queued ingress attempts, in milliseconds
INGRESS_WORKER_CONCURRENCY10Queued ingress workers (only when QUEUE_ENABLED=true)
INGRESS_RECONCILE_INTERVAL_MS60000Sweep cadence for replaying persisted ingress deliveries stuck mid-delivery; a delivery is retired to the DLQ after INGRESS_RECONCILE_MAX_ATTEMPTS attempts. Since v0.31.0 that includes a delivery whose queued job Redis lost (a restore from an earlier snapshot, a failover to a replica that was behind, a restart without persistence): the event row keeps its payload until the worker settles it, so the sweep replays the delivery from the row, a job that is still live is left alone, and one that already completed settles the row without a second delivery. With the queue on, the sweep replays nothing inline while Redis cannot be asked. 0 disables
INGRESS_RECONCILE_GRACE_MS60000Age in milliseconds a pending ingress event must pass before the reconciler looks at it (with the queue on, a row stays pending until its worker settles it), and the pause between two replays of the same event; 0 acts on an event as soon as it is seen. A non-negative integer no greater than 36500 days in milliseconds; anything else fails boot
INGRESS_RECONCILE_BATCH_SIZE50Stale ingress events the reconciler examines per sweep, oldest first. A value that is not an integer of at least 1 falls back to 50
INGRESS_RECONCILE_MAX_ATTEMPTS5Dispatch attempts per ingress event before the reconciler marks it failed and dead-letters it; with the queue on, each replay of a job Redis lost counts as one, so a job that keeps vanishing ends in a dead letter (v0.31.0+). A value that is not an integer of at least 1 falls back to 5
INGRESS_DEDUP_RETENTION_DAYS7Days to keep settled ingress dedup rows; aged pending payloads are handed to the dead-letter table before pruning (v0.25.0+). Check for prior delivery before redrive. <=0 falls back to 7
INGRESS_RETENTION_DAYS90Days to keep ingress DLQ rows; <=0 disables that prune
INGRESS_TIMESTAMP_TOLERANCE_SEC300Host-wide replay-tolerance fallback for ingress routes that declare timestampHeader without a per-route toleranceSec
INGRESS_INSTANCE_LIMIT120Per-instance fairness cap on the plugin ingress route POST /api/ingress/{pluginId}/{instanceId}/*: requests per window, keyed on plugin and instance rather than IP so a noisy tenant cannot spend its neighbours' budget when a provider delivers every tenant from one egress IP. Counted only for deliveries that pass signature verification; a route declaring signature.scheme: 'none' (ALLOW_UNSIGNED_INGRESS=true) passes every request. The global RATE_LIMIT_* tiers skip this route. A positive integer; anything else fails boot
INGRESS_INSTANCE_TTL60000Window of that cap, in milliseconds. A positive integer no greater than 2147483647; anything else fails boot
INGRESS_IP_LIMIT1200Second bucket on the same window, keyed on the client IP and checked before anything else, so it is the only bound on requests that fail verification. Every ingress request counts against it, including one the per-instance bucket then sheds, so a tenant that pushes a shared provider IP past it sheds its neighbours on that IP too. Ten times the per-instance default; raise it for a high-volume provider that delivers many tenants from one egress IP. A positive integer; anything else fails boot
RATE_LIMIT_MEDIUM_LIMIT100Max requests per window. One of three tiers the global throttler enforces together, with RATE_LIMIT_SHORT_LIMIT (10 per RATE_LIMIT_SHORT_TTL, 1000 ms) and RATE_LIMIT_LONG_LIMIT (1000 per RATE_LIMIT_LONG_TTL, 3600000 ms); exceeding any tier answers 429, so raising this one alone does not lift the ceiling. The tiers count per client IP and per route (each endpoint keeps its own buckets, so the limits are not a total across the API), with the IP resolved through TRUSTED_PROXIES; since v0.23.6 an IPv6 client is counted on its /64, so several clients reaching the gateway from one IPv6 network share every bucket and may need higher limits. Since v0.23.6 each such 429 also carries a plain Retry-After in seconds next to the tier-suffixed Retry-After-short, -medium or -long; before, only the suffixed header was sent, and HTTP clients do not read it. A client that honours Retry-After therefore now waits instead of retrying at once, up to an hour at the defaults when the long tier shed the request
RATE_LIMIT_MEDIUM_TTL60000Rate-limit window in milliseconds
RATE_LIMIT_SHORT_LIMIT10Max requests per RATE_LIMIT_SHORT_TTL window in the short tier; see RATE_LIMIT_MEDIUM_LIMIT for how the three tiers combine. A positive integer; 0 or anything else fails boot
RATE_LIMIT_SHORT_TTL1000Window of the short tier, in milliseconds. A positive integer no greater than 2147483647; anything else fails boot
RATE_LIMIT_LONG_LIMIT1000Max requests per RATE_LIMIT_LONG_TTL window in the long tier. A positive integer; 0 or anything else fails boot
RATE_LIMIT_LONG_TTL3600000Window of the long tier, in milliseconds (1 hour). A positive integer no greater than 2147483647; anything else fails boot
WS_RATE_LIMIT_FRAME_PER_SECOND60Sustained client frames per second (subscribe, unsubscribe, ping) per API key on the /events Socket.IO channel. The gateway enforces the WebSocket limits in-process, per process, because WebSocket frames bypass the HTTP guard pipeline. A positive integer; unset or blank takes the default and anything else fails boot
WS_RATE_LIMIT_FRAME_BURST120Burst capacity of that per-key frame bucket. Same parsing
WS_RATE_LIMIT_HANDSHAKE_MAX10Maximum new handshakes per client IP per window, checked before the key is validated so an unauthenticated handshake flood cannot force a database lookup on every attempt. Same parsing
WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS60000Window of the handshake limit, in milliseconds. Same parsing
WS_MAX_SOCKETS_PER_KEY16Maximum simultaneous sockets per API key, which covers multi-tab dashboards and SDK clients sharing one key. Same parsing
SEND_PACING_ENABLEDfalseOpt-in outbound send pacing (anti-ban). When on, a session may send at most its warm-up allowance per UTC day, and a run of consecutive send failures that reached WhatsApp pauses it. Refusals are HTTP 429 with code: 'SEND_PACING_LIMITED' and retryAfterSeconds, which is what tells them apart from the global rate limiter's own 429 (v0.14.0+)
SEND_PACING_WARMUP_SCHEDULE20,40,80,160,320,640,1000Per-day send allowance by session age in days: the first entry is the session's first day, the last applies to every day after. Starts small because a brand-new account that sends at volume is the pattern that gets numbers banned. A malformed entry falls the whole schedule back to the default rather than sending more than you asked for. Counts come from the messages table, so they survive a restart
SEND_PACING_COLD_DAILY_CAP5,10,20,40,60,80,100Bounds COLD REACHOUTS specifically: the first message to a chat this account has no history with in either direction. Starting conversations with strangers is what WhatsApp actually punishes, while replies to someone who wrote first are never counted. Same by-age shape as the schedule; a single number is a flat cap; 0 or off disables the rule (v0.24.0+). A blank value in a container environment, such as a ${KEY:-} forward from Compose, is dropped at boot and leaves the default ramp in force
SEND_PACING_BREAKER_THRESHOLD5Consecutive send failures that reached WhatsApp which trip the pacing breaker, pausing sends on the session for SEND_PACING_BREAKER_COOLDOWN_MS. Client-fault and engine-state errors raised inside the send call do not accumulate, so a client sending bad requests cannot 429 a healthy session
SEND_PACING_BREAKER_COOLDOWN_MS900000How long the pacing breaker pauses sends after SEND_PACING_BREAKER_THRESHOLD consecutive failures reached WhatsApp. 15 minutes
ENABLE_SWAGGERunsetServe the API docs and Swagger UI at /api/docs. .env.example ships this line commented out since v0.16.0, so the effective default is the unset behaviour: on outside production, off under NODE_ENV=production. Only the exact strings true and false are accepted: a blank value counts as unset, and any other value fails boot (v0.24.0+) — set ENABLE_SWAGGER=true to serve it in production, or false to force it off everywhere (v0.16.0+)
VALIDATION_ERROR_DETAILunsetReturn field-level messages on a 400 instead of a generic one. Same exact-string contract as ENABLE_SWAGGER: true forces it on, false forces it off, and when unset it is on outside production and off under NODE_ENV=production, so a rejected request there does not reflect the DTO shape back to the caller. Set it to true to debug an SDK or integration against a production instance without flipping NODE_ENV
BODY_SIZE_LIMIT25mbMax request body size (base64 media rides in the JSON body). A body over it answers 413, and malformed JSON answers 400; before v0.26.0, while the bundled dashboard was served, both answered 404 Cannot POST on /api and /mcp
INFLIGHT_BODY_BUDGET_BYTES4 × BODY_SIZE_LIMITAggregate cap on request-body bytes buffered across all connections, a positive integer in bytes. Keep it at least 2 × BODY_SIZE_LIMIT: a key holds at most half of it, so below that a full-size body sent with a key gets 413. Since v0.28.0 a request's reservation ends as soon as its body has been read into memory rather than staying held while the handler waits on the engine or database. Since v0.24.0 a request is charged in one of two tiers. A request that carries an active, unexpired API key, used from an address its allowedIps admit, is charged to that key: half the aggregate by default, however many addresses use the key. Every other request (no key, an unknown, expired or address-refused key, and ingress deliveries from outside providers) shares an unkeyed pool of a quarter of the aggregate, never less than two BODY_SIZE_LIMIT bodies, and each client IP holds at most half of that pool or one BODY_SIZE_LIMIT body if that is larger (a per-IP share since v0.21.0). The IP is resolved through TRUSTED_PROXIES, so behind a reverse proxy with none set every unkeyed caller shares the proxy address's single share, and since v0.23.6 an IPv6 client is counted on its /64. From v0.21.0 to v0.23.7 every request, keyed or not, was charged to its client IP against half the aggregate. Over-budget requests get a transient 503 with Retry-After; a request whose declared size the aggregate, its share or the pool could never admit gets 413 without Retry-After (v0.24.0+); a headers-then-silent sender is dropped after 15 seconds
TEMPLATE_RENDER_MAX_CHARS65536Cap on the rendered text of a send-template request after variable substitution; over-cap renders are rejected with 400, never silently truncated. Since v0.26.0 the length is measured before the text is built. The same cap also bounds the rendered text and caption of each send-bulk item, which fails when it is over
MEDIA_DOWNLOAD_ENABLEDtruefalse skips downloading inbound media entirely: nothing is decrypted, allocated or stored. The media field is not removed, it arrives as the { mimetype, filename?, omitted: true, sizeBytes } marker an oversized payload gets, and hasMedia still mirrors the engine's own flag. Accepts true, false, 1, 0, yes or no, case-insensitively after trimming; anything else fails boot, because an unrecognised value would silently mean enabled
MEDIA_DOWNLOAD_MAX_BYTES52428800Cap (50 MiB) on remote-URL sends, inbound media, and outbound base64 sends. Oversized inbound media is dropped and the message kept with its omitted marker; an oversized base64 send is rejected with 413, and since v0.23.6 so is a media url whose download runs past the cap (before, it answered 500, or 400 on the convert endpoints). A send by url holds the whole body in memory, at least twice its size at the peak and, on whatsapp-web.js, more while the page call that carries it is in flight, until the engine has taken it, so size the container memory for the number of large sends you run in parallel
MEDIA_DOWNLOAD_TIMEOUT_MS30000Abort a slow media download after this long, in milliseconds. Since v0.23.6 a media url that times out, answers non-2xx or cannot be reached is refused with 400 (503 when it fails through the session proxy before any response) instead of 500, and does not count toward the send-pacing breaker; the convert endpoints already answered 400
MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES8388608Aggregate inline-media budget (8 MiB of encoded base64) for one GET /sessions/{sessionId}/messages response. Spent newest-first; past it a payload becomes the { omitted, sizeBytes } marker and stays fetchable from the per-message media route. The newest payload is always sent whatever its size, so the real bound is max(this, one payload). 0 omits every payload, and inlineMedia=false on the request has the same effect for that call. The MCP MessageList tool draws on this budget only for a call that sets inlineMedia: true (v0.31.0+); without it the tool lists every payload as the marker
CHAT_HISTORY_MEDIA_BUDGET_BYTES26214400Aggregate inline-media budget (25 MiB) for one getChatHistory(includeMedia=true) call; media past the budget returns the omitted marker
INBOUND_MEDIA_CONCURRENCY4Per-session inbound media download cap; each payload can hold up to MEDIA_DOWNLOAD_MAX_BYTES, plus base64 overhead. On PostgreSQL, messages wait in chat arrival order and waiting media is omitted only after it has waited 2 x MEDIA_DOWNLOAD_TIMEOUT_MS with no slot released in that time (v0.25.0+)
INBOUND_MEDIA_GLOBAL_CONCURRENCY0Process-wide inbound media download ceiling across sessions, on both engines (v0.24.0+). 0 leaves only the per-session cap. Media waiting longer than MEDIA_DOWNLOAD_TIMEOUT_MS for a global slot arrives omitted
MESSAGE_RETENTION_DAYS0Delete older stored messages and finished bulk batches at startup and daily (v0.24.0+). 0 keeps them forever; values above 36500 fail boot. Back up before enabling this destructive retention policy. External search plugins receive no per-row deletion event, so their indexes keep copies until separately cleaned
SESSION_PROXY_URL_FETCHtrueFetch a caller-supplied URL through the egress proxy of the session the request names, so the destination sees the same address as the rest of that session's traffic: a media url on a send, status, profile-picture or group-picture route (either engine) or on POST /api/sessions/:sessionId/media/convert/voice and .../video, and the Baileys link preview of a text send (including customLinkPreview.thumbnailUrl in v0.27.0+). Before v0.23.6 these fetches always left from the gateway's own address. Set false when the proxy is a WhatsApp-only route that cannot reach arbitrary media hosts; sessions without a proxy are unaffected either way. Through an http/https proxy the proxy resolves the host itself, so the SSRF guard's DNS-rebind pinning does not apply there; a SOCKS proxy or false keeps it. A media fetch that fails through the proxy before any response answers 503, since a proxy outage cannot be told apart from an unreachable URL. Only the exact strings true and false are accepted; a blank or whitespace-only value keeps the default, and anything else fails boot. Forwarded by both bundled Compose files (v0.23.6+)
STATUS_MEDIA_MAX_BYTES10485760Per-file cap (10 MiB) on status (Story) media; oversized media is stored omitted (mediaOmitted=true), not rejected
STATUS_ORPHAN_SWEEP_INTERVAL_MS3600000How often the sweep re-lists status media files to find ones no row references (crash leftovers, and the status media of a deleted session, which the delete leaves in place), in milliseconds (1 hour). A positive integer no greater than 2147483647; anything else fails boot
STATUS_ORPHAN_GRACE_MS3600000How long a status media file must be seen unreferenced before the sweep deletes it (1 hour), so a file mid-ingest is never reaped. A positive integer; anything else fails boot
MEDIA_CONVERSION_ENABLEDfalseOpt-in server-side media conversion via ffmpeg through POST /api/sessions/:sessionId/media/convert/voice and .../video. Transcodes caller-supplied media into what WhatsApp clients actually play (audio to Ogg/Opus, video to MP4); nothing is converted implicitly. Since v0.23.6 ffmpeg reads only single-file media containers (MP4/MOV/3GP, WebM/Matroska, Ogg, MP3, WAV, AAC, AC-3, FLAC, AMR, AVI, MPEG-PS and MPEG-TS, ASF, FLV, CAF, AIFF, GIF, raw H.264/HEVC and a few more audio formats), so any other input, such as a playlist or a concat script, is refused with 400; before, such an input could make ffmpeg open the local files it named. The official Docker image ships ffmpeg, a source install needs the binary on PATH or the endpoints answer 503 (v0.14.0+)
FFMPEG_PATHffmpegPath to ffmpeg for conversion, Baileys voice-note waveforms, and (since v0.28.0) the 32-pixel first-frame inline preview on Baileys send-video. The official image ships it. Since v0.25.0 child processes receive only path, library-path, home, temp, locale, and SystemRoot variables; a wrapper must set other variables itself. Without ffmpeg (or past the video preview's 10 s deadline) Baileys voice notes use flat waveform bars and videos go out without a preview
MEDIA_CONVERSION_TIMEOUT_MS60000Kill one conversion after this long. 60 seconds. A non-positive value fails boot
MEDIA_CONVERSION_MAX_OUTPUT_BYTES52428800Cap on the CONVERTED bytes (50 MiB); an oversized output is rejected. A non-positive value fails boot
MEDIA_CONVERSION_CONCURRENCY2Max concurrent ffmpeg processes; a short queue absorbs bursts, beyond it the endpoint answers 503 instead of stacking processes
CHAT_MEDIA_ARCHIVE_ENABLEDfalseOpt-in chat-media archiving. When on, each message's media is also written to the file store (local or S3) and served by GET /sessions/:id/messages/:chatId/:messageId/media, so it stays retrievable after delivery. Available since v0.14.0. The inline base64 copy is kept by default; MESSAGE_INLINE_MEDIA=archive can remove it after a verified archive write (v0.25.0+). Since v0.16.0 the retention purge and orphan sweep run even while this is false; files left unreferenced after archiving is switched off are swept after the grace window below
MESSAGE_INLINE_MEDIAinlinearchive replaces a message row's inline media with an archived: true omitted marker after writing and reading back its archive (v0.25.0+). Requires CHAT_MEDIA_ARCHIVE_ENABLED=true or boot fails. Failures and over-cap files keep inline media; existing rows are not rewritten. TTL expiry removes the only copy. This saves storage, not burst memory
CHAT_MEDIA_ARCHIVE_OUTBOUNDfalseSub-flag of CHAT_MEDIA_ARCHIVE_ENABLED. When on, media sent by this account gets the same durable file copy, S3 portability, and TTL retention that inbound media already has. Off by default because outbound media was never archived before. Requires CHAT_MEDIA_ARCHIVE_ENABLED=true to take effect (v0.15.0+)
CHAT_MEDIA_ARCHIVE_MAX_BYTES26214400Per-file cap on archived chat media (25 MiB). Media above it is simply not archived; the message row and its inline copy are unaffected
CHAT_MEDIA_ARCHIVE_TTL_DAYS0How long archived files are kept, in days. 0 = forever. Expiry clears the FILE and the row's media columns (including removing the archived: true marker on outbound-archived rows, v0.27.0+); the message row itself is never deleted by this. The retention purge is scheduled regardless of CHAT_MEDIA_ARCHIVE_ENABLED, but stays a no-op while this is 0
CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS3600000How often the orphan sweep re-lists files under the chat-media/ prefix to find ones no message row references — crash leftovers, files left behind by archiving that was later switched off, or the archived media of a deleted session, which the delete leaves in place (1 hour)
CHAT_MEDIA_ORPHAN_GRACE_MS3600000How long such a file must have been seen unreferenced before the sweep deletes it (1 hour). First-seen timestamps live in memory only, so a restart restarts the clock and the first pass after boot deletes nothing; the sweep is scoped strictly to the chat-media/ prefix and never touches status media
BULK_MAX_CONCURRENT_BATCHES50Cap on concurrently running bulk-send batches. 0 = unlimited
MESSAGE_REAPER_INTERVAL_MS600000Sweep cadence (10 minutes) of the reaper that marks outbound rows stuck PENDING after a crash as FAILED with a reapedAt marker. 0 disables
MESSAGE_REAPER_GRACE_MS3600000Only PENDING rows older than this (1 hour) are reaped
MESSAGE_REAPER_BATCH_SIZE50Max rows reaped per sweep
STATS_CACHE_TTL_MS30000In-process memoization TTL for dashboard stats aggregates — stats can lag by up to this. 0 disables the memo
PLUGINS_DIR./data/pluginsWhere installed plugin packages live; both Compose files set /app/data/plugins. Keep it inside the data directory, because the plugin registry and every plugin's persisted storage are there: code kept elsewhere, for example in a container layer, is lost while its config and secrets survive, leaving registry entries that point at code that no longer exists
PLUGIN_STATE_DIR./dataRoot for the plugin registry and per-plugin storage, the one piece of state with no path knob before v0.23.0, so a test run rewrote the developer's own registry. It moves plugin state only: the databases, sessions, media and auth dirs each carry their own knob and none of them follow this one (distinct from PLUGINS_DIR, where plugin packages are installed). Moving it does not carry existing state across: copy registry.json and every <plugin id>/key-*.json from the old root's plugins/ into the new one's, or plugins come back enabled with their persisted ctx.storage gone (v0.23.0+)
PLUGIN_DOWNLOAD_MAX_BYTES5242880Cap (5 MiB) on a plugin .zip fetched by install-from-URL
PLUGIN_DOWNLOAD_ALLOW_INSECURE_REDIRECTSfalseAllow an https plugin-download URL to redirect to a plain-http hop. Refused by default, because the package is executable code and an http hop exposes it to on-path substitution. Only a hop that downgrades after an https hop is refused: a chain that starts on plain http is not itself a downgrade, though an http, https, http chain is still refused. Enable it only if a vendor or release host genuinely downgrades. Exact true or false; anything else fails boot. Both Compose files forward false by default
PLUGIN_INSTALL_REQUIRE_PINunsetRequire a #sha256=<64 hex> integrity pin on every plugin install from a URL. Unset means production-only (NODE_ENV=production); true forces it everywhere, false lifts it. A plain-http: URL needs the pin in every environment regardless (v0.20.0+, breaking for production installs without a pin)
PLUGIN_CAP_TIMEOUT_MS30000Timeout for one sandboxed plugin capability call; a wedged call is failed and its in-flight slot freed
PLUGIN_STORAGE_MAX_BYTES52428800Per-plugin storage quota (50 MiB); ctx.storage writes beyond it are rejected. Since v0.28.0 a storage key over 184 UTF-8 bytes is also rejected
PLUGIN_CATALOG_URLhttps://raw.githubusercontent.com/rmyndharis/OpenWA-plugins/main/plugins.jsonCatalog the plugin browser reads its list of installable packages from. Point it at your own published catalog to install from a private index. The fetch goes through the SSRF guard, so an internal host must also be named in SSRF_ALLOWED_HOSTS or the request is refused — a private index on a non-public address does not work on this key alone. Since v0.26.0 every entry needs a non-empty text id, name and version, and its other text fields must be text and keywords must be a list of text (a null counts as absent); a catalog holding any other entry is refused with 400, so a private catalog has to correct it. A URL that carries a user name or password is refused with 400 too (Failed to fetch plugin catalog: URL must not contain credentials (userinfo)); since v0.31.0 that text repeats nothing of the URL, where it used to repeat it with the credentials
UPDATE_CHECK_ENABLEDtrueLets the dashboard sidebar tell admins when a newer OpenWA release exists. When an admin opens the dashboard, GET /api/infra/update-check asks api.github.com for the latest published release through the SSRF guard, directly rather than through HTTP(S)_PROXY, and caches the answer for six hours (fifteen minutes after a failure); a failed check raises no error and keeps the last answer, so an instance that has never reached GitHub shows no notice. false makes no request at all, for deployments where that egress is not wanted. Only the exact strings true and false are accepted; a blank or whitespace-only value keeps the default, and anything else fails boot. Forwarded by both bundled Compose files (v0.23.6+)
The media knobs take raw numbers, BODY_SIZE_LIMIT takes a unit string

BODY_SIZE_LIMIT is written 25mb, and the neighbouring size knobs are not. MEDIA_DOWNLOAD_MAX_BYTES, MEDIA_DOWNLOAD_TIMEOUT_MS, INBOUND_MEDIA_CONCURRENCY and CHAT_HISTORY_MEDIA_BUDGET_BYTES each take a bare integer, and since v0.23.4 a unit-suffixed value refuses the boot by name. Before that it parsed as its leading digits with nothing said: MEDIA_DOWNLOAD_MAX_BYTES=50mb became a 50-byte cap and MEDIA_DOWNLOAD_TIMEOUT_MS=30s a 30-millisecond timeout, so every media download failed and no log line named the cause. A zero or negative value is refused the same way. If you are on an older release, check these four before you upgrade.

Check your own .env for ENABLE_SWAGGER

Up to v0.15.0, .env.example shipped ENABLE_SWAGGER=true uncommented alongside NODE_ENV=production, so cp .env.example .env pinned the opt-in that the production default exists to withhold. The /api/docs mount sits outside the API-key guard, so that served the OpenAPI schema and the exact running version to anyone who could reach the port. v0.16.0 commented the line out in the template, but that fix is not retroactive — a .env already on disk still carries the line. Bare-metal operators who copied the template at v0.15.0 or earlier should comment the line out (production then defaults to off) or set ENABLE_SWAGGER=false to force it off everywhere. Helm deployments are unaffected: the chart's default env map carries only NODE_ENV and LOG_LEVEL, neither of which touches Swagger, so they resolve to the production default. Both bundled Compose files do forward the key (- ENABLE_SWAGGER=${ENABLE_SWAGGER:-}), so a .env still carrying the v0.15.0 line switches Swagger on there too.

VariableDefaultDescription
SEARCH_ENABLEDtrueMount the global message-search module and its /search route. false omits the module entirely, so the route answers 404
SEARCH_PROVIDERautoWhich provider backs /search: auto selects the built-in database full-text provider (PostgreSQL tsvector/GIN, SQLite FTS5) at runtime, builtin-fts pins that provider explicitly, and none keeps the module and route mounted but registers no provider, so /search answers 501. Under auto an enabled plugin that declares search:provide takes the route over, and only then can /search itself fail with 502 (the provider returned an invalid result shape) or 503 (it did not answer); the built-in provider returns neither. Enum-validated at boot against exactly those three values on the raw string — a stray space (auto ) is rejected with SEARCH_PROVIDER must be one of: auto, builtin-fts, none
SEARCH_CONTAINS_ENABLEDfalseBuild and maintain the trigram index that backs match=contains on GET /api/search (messages_trgm FTS5 trigram table on SQLite ~3x message text, pg_trgm + unaccent GIN index idx_messages_body_trgm on PostgreSQL). Built in the background after the HTTP listener is up so the startup probe is not held; while false, while the index is still building, or when PostgreSQL lacks pg_trgm/unaccent or SQLite is older than 3.45, match=contains answers 501 on the built-in provider while match=word keeps working. Plugin search providers receive match regardless of this flag. Exact true or false; a blank value keeps false and anything else fails boot. Forwarded by both bundled Compose files (v0.27.0+)
SEARCH_LIMIT_MAX100Hard cap on the limit query parameter of /search. The offset parameter has a fixed ceiling of 100000 that no variable changes; since v0.23.6 a larger value answers 400, where before it was clamped and returned the page at the ceiling again

Search queries are limited to 1000 characters and 32 words (v0.25.0+), cannot contain NUL characters (\u0000), and under match=contains require at least one term of 3+ characters (on PostgreSQL, 3+ letters or digits in a row) and at most 64 non-space characters across all terms (v0.27.0+); punctuation separates words under match=word and standalone symbols or emoji count as words. Repeated whitespace-separated words count once. Exceeding any limit answers 400. Chat-restricted keys can use built-in search within their allowlist, but cannot use plugin search. On SQLite their match=word results omit score while retaining relevance order (match=contains includes score for every key, computed and highlighted on the first 4,096 UTF-16 code units of each candidate message since v0.27.1). Under match=word, score is SQLite FTS5's negative bm25 (lower means more relevant) on SQLite and ts_rank (higher means more relevant) on PostgreSQL; PostgreSQL's early stop on match=contains uses a materialized CTE and requires PostgreSQL 13+.

MCP​

The MCP server is off by default; MCP Integration covers connecting a client.

VariableDefaultDescription
MCP_ENABLEDfalseMount the stateless Streamable-HTTP MCP server at POST /mcp on the same port, for agent and AI-assistant tool access. Exact true or false; anything else fails boot
MCP_READONLYtrueMount read-only tools only, with no sends and no mutations. Only the exact string false mounts the write tools; any other value, a typo included, keeps the server read-only
MCP_RATE_LIMIT_MAX60Maximum tool calls per API key per window. A blank, non-positive or non-numeric value falls back to the default instead of failing boot
MCP_RATE_LIMIT_WINDOW_MS60000Window of the per-key limit, in milliseconds. Same fallback
MCP_IP_RATE_LIMIT_MAX120Pre-auth limit per client IP, which gates invalid-key requests before the key is validated because the raw mounts bypass the global throttler: JSON-RPC messages on /mcp and HTTP requests on /api/admin/queues, each mount counted separately. Same fallback
MCP_IP_RATE_LIMIT_WINDOW_MS60000Window of the per-IP limit, in milliseconds. Same fallback
MCP_MAX_RESULT_BYTES0Cap, in UTF-8 bytes, on one tool result, for a client that puts the whole result in the model's context and fails past a size. 0 or unset means no cap: a result over 32 KiB comes back as an embedded base64 resource. With a positive value every result, an error answer included, is a single text item, cut at that many bytes (with a note of its full size after the cut) when it is longer, and none is offloaded as a resource. Unlike the limits above it is validated at boot: a non-negative integer of plain decimal digits, a blank value counts as unset, and anything else fails boot. Read once when the server mounts. Both bundled Compose files forward it (v0.31.0+)

Verify your configuration​

After editing .env, restart OpenWA and confirm the API is up. The base URL in local development is http://localhost:2785/api (the /api global prefix; in production it sits behind your domain and TLS).

Start with GET /api/health. This endpoint is public — it needs no API key, so you can run it before you have located your key:

curl http://localhost:2785/api/health

A healthy instance returns 200 OK with three fields — though the version field is disclosed only to requests carrying a valid API key (v0.19.0+):

{
"status": "ok",
"timestamp": "2026-06-26T12:00:00.000Z",
"version": "0.31.0"
}

Once that succeeds, confirm your API key works against an authenticated endpoint. GET /api/sessions lists your sessions and requires the X-API-Key header:

curl http://localhost:2785/api/sessions \
-H "X-API-Key: YOUR_API_KEY"

Replace YOUR_API_KEY with the key OpenWA printed in its startup banner (or the one you set via API_MASTER_KEY before the first boot). A 200 OK confirms the key is accepted; a 401 Unauthorized means it is missing or wrong. A key restricted to chats with allowedChats (v0.23.6+) gets 403 Forbidden here instead, because the session list is not open to a chat-scoped key; check such a key with GET /api/sessions/{sessionId}, which it may read. See API key authentication below.

API key authentication​

Every authenticated API route requires a key, sent either in the X-API-Key header or as Authorization: Bearer <key>. Keys carry a role — admin, operator, or viewer — and can be scoped to specific sessions, specific chats (allowedChats, v0.23.6+), or IP ranges.

On first boot, OpenWA generates a random admin key and prints it in the startup banner (it is also written to data/.api-key). To supply your own for the first boot instead, set:

API_MASTER_KEY=your-long-random-secret

API_MASTER_KEY is read only while no API key exists. Setting it on an install that already has keys authenticates nothing (the value answers 401) and leaves the existing admin key in force; rotate by creating a new ADMIN key and revoking the old one.

A key you supply is written to data/.api-key (BOOTSTRAP_KEY_FILE) like a generated one, so it reaches every backup archive taken while the file exists (see Deployment); since v0.28.0 the startup banner never prints an API_MASTER_KEY value in the logs, and GET /api/auth/api-keys shows (master key) as its keyPrefix instead of the first 12 characters of the secret.

For production, also set API_KEY_PEPPER to switch key hashing from SHA-256 to HMAC-SHA256. Set it before the first boot: enabling or changing it on an install that already has keys makes every key, the admin key included, answer 401, and none is left to re-issue the others (see Recover a lost admin key).

See Authentication for roles, scoping, and key lifecycle.

Webhooks​

OpenWA delivers session and message events to your endpoints as HTTP POSTs, optionally signed with an HMAC secret so you can verify authenticity. Tune delivery with WEBHOOK_TIMEOUT and WEBHOOK_RETRY_DELAY. The number of delivery attempts is not an environment variable: retryCount is a field on each webhook record that counts total attempts, including the first (default 3, range 0-5, where 0 and 1 both mean a single attempt), settable when you create or update the webhook, so two webhooks on the same instance can make a different number of attempts. Outbound SSRF protection is on by default (WEBHOOK_SSRF_PROTECT): webhook URLs that resolve to loopback, private, link-local, or other reserved ranges are refused at registration and at delivery (since v0.31.0 that includes the documentation ranges such as 203.0.113.0/24: a receiver there needs SSRF_ALLOWED_HOSTS). Since v0.20.0 a name in SSRF_ALLOWED_HOSTS also resolves at registration, so a host that cannot resolve yet fails the create/update with a 400, and each delivery pins its connection to the addresses the name resolves to for that delivery, closing the window where a name re-resolves to a different address between the check and the connect. With the guard off, deliveries no longer follow redirects (WEBHOOK_SSRF_REDIRECTS).

See Webhooks for the event catalog, payload shapes, and signature verification.

Troubleshooting​

ProblemCauseFix
Server exits at boot naming .env or data/.env.generated (v0.28.0+)The file exists on disk (or is a dangling symlink) and the process cannot read itFix the file's ownership or permissions (or remove the broken symlink) so the OpenWA process user can read it
Server exits at boot with a credentials errorDATABASE_TYPE=postgres with a blank DATABASE_HOST, DATABASE_USERNAME or DATABASE_PASSWORD (any environment); under NODE_ENV=production, a placeholder DATABASE_PASSWORD, an empty or placeholder S3 access key or secret key with STORAGE_TYPE=s3, (v0.19.0+) an API_MASTER_KEY shorter than 32 characters, or (v0.26.0+) a METRICS_TOKEN that is a placeholder or a known weak valueSet the missing database values, a strong, unique DATABASE_PASSWORD or S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY, a master key of at least 32 characters and a long random METRICS_TOKEN (or unset it); since v0.23.7 the S3 error names the canonical variable that is empty or a placeholder, whichever spelling you set
Server exits at boot naming REDIS_TLS, REDIS_USERNAME or DATABASE_SSL (v0.26.0+)TLS, or a named Redis user, is set beside the built-in Redis, or DATABASE_SSL=true beside the built-in PostgreSQL. The bundled containers serve plain connections and Redis only its default userSet REDIS_TLS=false and clear REDIS_USERNAME, or DATABASE_SSL=false, where the value is set (the environment, .env or data/.env.generated), or use an external server
Log line S3_ENDPOINT must be an absolute http(s) URL, and media lands in the local directory (v0.26.0+)STORAGE_TYPE=s3 with an S3_ENDPOINT that has no http:// or https://, such as minio:9000. The gateway starts and keeps media on the local directoryAdd the scheme, for example http://minio:9000, and restart
Server rejects ENGINE_TYPE at bootValue is not whatsapp-web.js or baileysUse one of the two valid values, or leave it unset to choose from the dashboard
Server exits at boot naming AUDIT_RETENTION_DAYS (v0.17.0+)The value is not a plain integer — 30d, 90.5, +90, or a word such as ninety. Earlier versions accepted these and silently used 30, 90, 90, or the defaultSet a plain integer such as 90, or 0 to disable pruning; or leave the knob unset
Server exits at boot with PostgreSQL data connection is not on UTC (v0.23.6+)The data connection's SET TIME ZONE 'UTC' did not hold, typically behind a pooler that drops session state, so the session runs in the server's default zone; one that reads +00 for only part of the year, such as Europe/London, fails tooSet the database default with ALTER DATABASE "openwa" SET TimeZone='UTC' (use your DATABASE_NAME), or let the statement through the pooler
Server exits at boot naming POSTGRES_SCHEMAThe schema name starts with a digit, is longer than 63 characters, has a pg_ prefix or characters outside letters, digits and underscores, or (v0.23.6+) has upper-case letters or surrounding spacesUse a lower-case letter or underscore followed by lower-case letters, digits and underscores, at most 63 characters and without the pg_ prefix, e.g. openwa
Browser blocks requests from a dashboard or app hosted on another origin in productionCORS_ORIGINS=* (the default) is refused in production, so cross-origin browser requests are blockedSet explicit origins, e.g. CORS_ORIGINS=https://dashboard.yourdomain.com. The bundled dashboard is served by the API on the same origin and is not affected
Cache appears to do nothingAt v0.26.0 no request path reads the cache, so enabling Redis speeds nothing up; with Redis disabled or unreachable the cache layer is skippedNothing to fix: caching is optional and fails open, and reads come from the source of truth. Enable Redis for the rate-limit store or multi-replica WebSocket fan-out, not for speed
401 Unauthorized on every requestMissing or wrong X-API-KeySend the key from the startup banner, or the one you set via API_MASTER_KEY before the first boot
403 API key is restricted to selected chats on most routes (v0.23.6+)The key carries an allowedChats allowlist, and either the route is not open to a chat-scoped key (the session list is among those; built-in /search is chat-scoped in v0.25.0) or the body carries a quotedMessageId on a route other than POST /api/sessions/{sessionId}/messages/replyUse a key without allowedChats for those routes, send quotes through the reply route, or stay on the routes listed in Scope a key to chats
Config change had no effectValues load only at bootRestart OpenWA; adapters cannot be hot-swapped

Next steps​