Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
train 12d (#1815)
Yudhi Armyndharis2956fa996d86
diff --git a/.env.example b/.env.exampleindex 7b5b237d4..9004d9fc5 100644--- a/.env.example+++ b/.env.example@@ -450,7 +450,11 @@ WEBHOOK_RETRY_DELAY=5000 # Base delay between retries in ms (doubles# backoff are capped together at WEBHOOK_DISPATCH_CONCURRENCY# plus this; more are shed to the outbox.# Deliveries to one session's failing receivers park at most- # a quarter of it, so other sessions keep room to wait+ # a quarter of it, so other sessions keep room to wait.+ # Each inline delivery holds its event's inline media (up to+ # 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64), up to about+ # 1.3 GiB per process at the defaults; QUEUE_ENABLED=true keeps+ # it in Redis instead.# WEBHOOK_SHUTDOWN_DRAIN_MS=5000 # on shutdown, in-flight deliveries get this long to finish# before they are logged abandoned (parked ones are# dead-lettered). Startup warns when this is shorter than@@ -552,6 +556,14 @@ WEBHOOK_SSRF_PROTECT=true# at once). Each concurrent download holds memory up to MEDIA_DOWNLOAD_MAX_BYTES (held as base64 on# whatsapp-web.js, about a third larger), so the worst case is about sessions x N x MEDIA_DOWNLOAD_MAX_BYTES# (x ~1.33 on whatsapp-web.js). Unset takes the default; a value that is not a positive integer fails the boot.+# That covers downloads in progress. On whatsapp-web.js Chromium also holds each file being downloaded,+# encrypted and decrypted, and a download starts whenever the size the sender declares is within+# MEDIA_DOWNLOAD_MAX_BYTES, so a sender that understates it can make one download exceed that cap. On+# PostgreSQL each downloaded payload (received media, and the echo of every media send on+# whatsapp-web.js) then waits in memory as base64 (about 4/3 of its size, on both engines) until its row+# is stored, and how many wait is not bounded: a burst faster than the database writes adds messages+# waiting x 4/3 x size. Lowering this does not bound that; MEDIA_DOWNLOAD_MAX_BYTES caps each payload,+# MEDIA_DOWNLOAD_ENABLED=false holds none.# INBOUND_MEDIA_CONCURRENCY=4 # default 4# Process-wide ceiling on inbound media downloads across all sessions, on top of the per-session one.# 0 (default) is off. When on, media that waits longer than MEDIA_DOWNLOAD_TIMEOUT_MS for a slot is@@ -643,6 +655,10 @@ WEBHOOK_SSRF_PROTECT=true# file first and falls back to the inline base64 copy on the message row, so retrievability does not# require archiving. The inline copy is KEPT, so archiving roughly doubles storage for media under# the cap — hence off by default.+# It also costs memory during a media burst, on either database: each message is archived after its+# row is written, and until its upload finishes it holds its payload as base64 and decoded. Nothing+# limits how many archive at once, and slow storage (S3) makes more overlap. Media over+# CHAT_MEDIA_ARCHIVE_MAX_BYTES are not archived and cost nothing here.# CHAT_MEDIA_ARCHIVE_ENABLED=false # default false# Extend archiving to media this account SENT (needs CHAT_MEDIA_ARCHIVE_ENABLED=true). Doubles# storage again for the outbound half, and buys nothing for a URL-based send, whose row stores the@@ -663,6 +679,11 @@ WEBHOOK_SSRF_PROTECT=true# goes wrong keeps the inline copy. Needs CHAT_MEDIA_ARCHIVE_ENABLED=true (boot fails otherwise);# media over CHAT_MEDIA_ARCHIVE_MAX_BYTES is not archived and stays inline; with a TTL above, an# expired file takes the only copy with it. Rows stored before the switch keep their inline copy.+# It saves storage, but not the memory a burst holds: the row is first written with the inline+# copy, then archived. It adds to the archiving memory cost above: each message being archived+# also holds the file read back and the row's metadata while the row is rewritten.+# CHAT_MEDIA_ARCHIVE_MAX_BYTES bounds that cost per message (larger media are not archived), not+# how many archive at once.# MESSAGE_INLINE_MEDIA=inline # default inline# Orphaned chat-media reconciliation: how often the sweep re-lists chat-media files to find ones no# row references (crash leftovers), and how long a file must be seen unreferenced before deletion.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cfa9921d5..f2f2cd9ac 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -19,7 +19,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Add bounded webhook failure redrive with optional payload retention.- Expose caller-supplied send idempotency keys in all five SDKs.- Add optional 24-hour idempotency keys to twelve single-recipient send routes.-- Add opt-in archive-only chat media with dashboard previews.### Changed@@ -31,16 +30,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Probe the configured `PORT` in the Docker image healthcheck instead of a fixed 2785.- Cap the total bytes one storage import writes at `STORAGE_IMPORT_MAX_TOTAL_BYTES`.- Close the Baileys session proxy's fetch dispatcher when the session disconnects, logs out or is destroyed.-- Apply the Java SDK request timeout to the response body as well as the headers.+- Java SDK (next SDK release after 0.5.1): the request timeout also bounds the response body, so a stalled body raises `OpenWATimeoutError`.- Keep a new dashboard template draft when an earlier template save finishes.- Stop the dashboard Chats page from marking the open chat read on a newly selected session.- Refuse bulk batches once shutdown begins, and fail a batch saved during shutdown instead of sending it.- Disable plugins whose enable is still running at shutdown, and refuse new plugin enables during teardown.- Stop in-flight webhook replay, ingress replay and pending-message sweeps at shutdown.-- Close queue workers before plugins shut down, so jobs taken during shutdown no longer spend attempts or get dead-lettered.-- Answer new HTTP requests with `503` once shutdown teardown begins.+- Close queue workers, waiting up to 15 s for running jobs, before plugins shut down, so no new job is taken against stopped plugins.+- Answer new HTTP requests with `503` once teardown begins after SIGTERM, SIGINT or `POST /api/infra/restart`.- Refuse session starts with `503` once shutdown begins, and leave a start that shutdown interrupts for the next boot instead of marking it failed.-- Retire the pending webhook outbox record when a redrive delivers, so the sweep does not send the event again.- Stop dashboard multi-page loads and a pending chat mark-as-read from sending requests after logout.- Keep a new dashboard login signed in when a request sent with the previous API key fails afterwards.- Enforce the plugin package size limit before reading `manifest.json`, and reject archive entries whose path starts with `/`.@@ -85,7 +83,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Documentation-- The README and architecture docs describe the S3 storage backend as the live media store, not a backup target.+- Document the memory media messages and parked webhook deliveries hold during a media burst, and the settings that limit it.+- The README and architecture docs describe the Local/S3 storage backend as the live media store, not a backup target.- Document how to recover a lost admin API key without revoking the other keys.- The integration docs say `integration_delivery_failures` holds only failed inbound deliveries.- The webhook runbook documents the ADMIN delivery-failure redrive and no longer says failed deliveries retry on their own.@@ -96,6 +95,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Upgrade notes (behavior changes)+- Aged undispatched ingress events are dead-lettered instead of deleted; some may already have been delivered, so check before redriving them.+- Java SDK (next SDK release after 0.5.1): the request timeout (default 30 s) also bounds the response body; raise it for large media downloads.- A storage import stops at `STORAGE_IMPORT_MAX_TOTAL_BYTES` (default 10 GiB); raise it before importing a larger export.- Baileys answers `400` for an animated sticker with more than 500 frames.- `backup.sh` and `restore.sh` exit with status 2 when `./.env` or `.env.generated` sets a key in a form they cannot parse; fix the line or pass the key in the environment.diff --git a/README.md b/README.mdindex 6300e7d3f..9c13ecd2a 100644--- a/README.md+++ b/README.md@@ -161,15 +161,15 @@ For any deployment where ethical, legal, or regulatory compliance matters (healt### Infrastructure-| Feature | Status | Description |-| ---------------- | ------ | ------------------------------------------ |-| SQLite | ✅ | Zero-config embedded database |-| PostgreSQL | ✅ | Production-grade database |-| Redis Cache | ✅ | Optional performance caching |-| S3/MinIO Storage | ✅ | Live media store (statuses, archived chat) |-| Docker | ✅ | One-command deployment |-| Health Checks | ✅ | Kubernetes-ready probes |-| Data Migration | ✅ | Export/import between backends |+| Feature | Status | Description |+| ---------------- | ------ | ------------------------------------------------ |+| SQLite | ✅ | Zero-config embedded database |+| PostgreSQL | ✅ | Production-grade database |+| Redis Cache | ✅ | Optional performance caching |+| S3/MinIO Storage | ✅ | Live media store (statuses, archived chat media) |+| Docker | ✅ | One-command deployment |+| Health Checks | ✅ | Kubernetes-ready probes |+| Data Migration | ✅ | Export/import between backends |---diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex ed2736b7c..84ac25a0c 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -491,7 +491,9 @@ WEBHOOK_DISPATCH_MAX_QUEUED=1000# The failing state and the cap are held per process, not per cluster.# The first 2xx from the webhook lifts it. With the queue disabled, a session parks at most a# quarter of WEBHOOK_DISPATCH_MAX_QUEUED behind that limit and sheds the rest, so other sessions-# keep room.+# keep room. Each running, parked or backoff-waiting inline delivery holds its event's inline media+# (up to 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64), about 1.3 GiB per process at the defaults+# when every slot is taken; lower these caps or enable the queue to reduce it.# WEBHOOK_DEGRADED_SESSION_CONCURRENCY=# Delivery attempts (total, including the first) are set per webhook with the retryCount API field (default 3, range 0-5).diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex b6c9ce285..277fd7dc5 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -221,6 +221,23 @@ curl -H "X-API-Key: $API_KEY" \# Consider removing unused sessions+# C. If memory climbs during a media burst (received, or sent on whatsapp-web.js):+# on PostgreSQL each payload, received or the echo of a media send, waits in memory as base64+# (about 4/3 of the file size) until its row is stored, with no limit on how many wait; a slow+# message:received or message:sent plugin hook holds them the same way on either database.+# Lower MEDIA_DOWNLOAD_MAX_BYTES to cap each one (it also caps outbound media sends), or set+# MEDIA_DOWNLOAD_ENABLED=false to hold none. Lowering INBOUND_MEDIA_CONCURRENCY does not bound+# it. Archiving (CHAT_MEDIA_ARCHIVE_ENABLED=true) adds its own cost on either database: each+# message being archived holds its payload as base64 and decoded until the upload finishes (more+# under MESSAGE_INLINE_MEDIA=archive, which also reads the file back and rewrites the row), and+# nothing limits how many archive at once. Lowering CHAT_MEDIA_ARCHIVE_MAX_BYTES (25 MiB by+# default) bounds that cost per message, since larger media are not archived, but not how many+# archive at once; slow storage such as S3 makes more overlap. With QUEUE_ENABLED=false, webhook+# deliveries to receivers that stop answering also hold their inline media (up to+# 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES each as base64, for up to WEBHOOK_DISPATCH_CONCURRENCY+# + WEBHOOK_DISPATCH_MAX_QUEUED deliveries); lower those settings or enable the queue.+# Sizing: 12 - Troubleshooting & FAQ, "How many sessions can I run?"+# 5. Long-term fix:# Edit docker-compose.yml# Increase memory limit or reduce max sessionsdiff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex aafa770ec..5d4f7262d 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -1244,7 +1244,16 @@ docker exec openwa-api curl http://host.docker.internal:8080>> With `ENGINE_TYPE=baileys` (browser-free), RAM per session is significantly lower — you can run more sessions on the same hardware. Exact figures depend on message volume and group membership.>-> A media burst adds roughly `INBOUND_MEDIA_CONCURRENCY` x `MEDIA_DOWNLOAD_MAX_BYTES` per session on top of that (4 x 50 MiB by default; about a third more on whatsapp-web.js, which holds each payload as base64). Set `INBOUND_MEDIA_GLOBAL_CONCURRENCY` to cap concurrent inbound media downloads across all sessions. On whatsapp-web.js a download that times out keeps its slot until Puppeteer fails the call (`PUPPETEER_PROTOCOL_TIMEOUT_MS`, 180 s by default), since it cannot be aborted.+> A media burst adds roughly `INBOUND_MEDIA_CONCURRENCY` x `MEDIA_DOWNLOAD_MAX_BYTES` per session on top of that (4 x 50 MiB by default; about a third more on whatsapp-web.js, which holds each payload as base64). On whatsapp-web.js Chromium also holds each file being downloaded, encrypted and decrypted, and a download starts whenever the size the sender declares is within `MEDIA_DOWNLOAD_MAX_BYTES`, so a sender that understates it can make one download exceed that cap. Set `INBOUND_MEDIA_GLOBAL_CONCURRENCY` to cap concurrent inbound media downloads across all sessions. On whatsapp-web.js a download that times out keeps its slot until Puppeteer fails the call (`PUPPETEER_PROTOCOL_TIMEOUT_MS`, 180 s by default), since it cannot be aborted.+>+> On PostgreSQL media messages can also wait in memory after the download: received media, and the echo of media this account sends, which is downloaded the same way (every media send on whatsapp-web.js; on Baileys, media sent from a linked phone). Each payload is held as base64, about 4/3 of the file size (roughly 67 MiB for a 50 MiB file), until its message row is stored, and nothing limits how many wait: they pile up while media arrive faster than PostgreSQL writes them. A slow `message:received` or `message:sent` plugin hook, or with `RESOLVE_LID_TO_PHONE=true` a slow phone lookup for a privacy-id sender, holds payloads the same way for as long as it runs, on SQLite too, and the chat's later messages wait behind it. How many wait depends on how long each insert takes. For example, on a local PostgreSQL 16 where a 50 MiB row took about 0.4 s to insert, 24 files of 50 MiB arriving at 8 per second left 13 waiting (about 0.9 GiB, peak RSS 1.8 GiB), and at 4 per second one insert that stalled for 8 s left 21 waiting (1.4 GiB, peak RSS 2.3 GiB); SQLite left none. Size for it as messages waiting x 4/3 x media size, and treat that as a lower bound: writing a row makes further copies of its payload, so peak RSS ran up to about twice the waiting bytes.+>+> - `MEDIA_DOWNLOAD_MAX_BYTES` caps each waiting payload (larger media arrive as the omitted marker), not how many wait. It also caps outbound media sends.+> - `MEDIA_DOWNLOAD_ENABLED=false` holds no payload at all; every media message arrives as the omitted marker.+> - Lowering `INBOUND_MEDIA_CONCURRENCY` does not bound it. It only slows how fast payloads reach the database, which helps while one download takes longer than one insert; a stalled insert still lets them pile up.+> - Archiving (`CHAT_MEDIA_ARCHIVE_ENABLED=true`) adds to it on either database, in both `MESSAGE_INLINE_MEDIA` modes. Each message is archived after its row is written, with no limit on how many archive at once, and each one holds its base64 payload and the decoded bytes until the upload finishes. `MESSAGE_INLINE_MEDIA=archive` also holds the read-back file, the re-read metadata and its snapshot, and saves no memory, since the row is still written with the inline copy first. Only media up to `CHAT_MEDIA_ARCHIVE_MAX_BYTES` (25 MiB by default) are archived; larger media add nothing, so lowering it bounds the cost per message, not how many archive at once. How many overlap grows with storage latency (such as S3) and with how fast downloads complete. On SQLite, 40 files of 20 MiB at 10 per second peaked at about 0.55 GiB RSS without archiving, and at 1.4 GiB with archiving in the default inline mode when each upload took 2 s (17 at once). In the 8 per second burst above, with `CHAT_MEDIA_ARCHIVE_MAX_BYTES` raised so the 50 MiB files were archived to local disk storage, peak RSS on SQLite rose from about 1 GiB to 2.1 to 3 GiB in inline mode and to 4.2 to 5.1 GiB in archive mode (up to 20 archives at once); on PostgreSQL, whose slower inserts spread the archives out, from 1.8 GiB to 2 GiB in inline mode and to 2.7 to 2.9 GiB in archive mode.+>+> With the queue off (`QUEUE_ENABLED=false`), every webhook delivery that is running, parked or waiting out a retry backoff also holds its event's payload, including inline media up to `WEBHOOK_MEDIA_INLINE_MAX_BYTES` (1 MiB by default) as base64. Up to `WEBHOOK_DISPATCH_CONCURRENCY` + `WEBHOOK_DISPATCH_MAX_QUEUED` deliveries (1016 by default) wait this way, so receivers that stop answering during a media burst can hold about 1.3 GiB per process at the defaults. Lower either dispatch setting or `WEBHOOK_MEDIA_INLINE_MAX_BYTES`, or enable the queue, which keeps those payloads in Redis instead.**Q: Can I run 10+ sessions in one container? Will they get banned for sharing one IP?**