Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct the pairing hint, receipt gate and restart stop text
Yudhi Armyndharis053106c9f606
diff --git a/.env.example b/.env.exampleindex c127476a1..1114bee73 100644--- a/.env.example+++ b/.env.example@@ -474,13 +474,14 @@ WEBHOOK_RETRY_DELAY=5000 # Base delay between retries in ms (doubles# 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 webhook whose- # receiver never answers holds only its own places, but the pool- # is shared: a session holds at most a quarter of the pool at once+ # openwa_webhook_delivery_failures_total. A receiver that never+ # answers holds its places for a WEBHOOK_TIMEOUT, and the pool is+ # shared: a session holds at most a quarter of the pool at once# (four at the defaults) however many of its webhooks name the- # event, and another session's events wait for a slot once such- # sessions together hold all of them. The events waiting are not- # capped process-wide.+ # event, so beyond four such webhooks one that hangs can delay+ # its siblings, and another session's events wait for a slot once+ # such sessions together hold all of them. The events waiting are+ # not capped process-wide.# 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 keepsdiff --git a/dashboard/src/hooks/useProfilePictures.ts b/dashboard/src/hooks/useProfilePictures.tsindex 1215b1b07..274432225 100644--- a/dashboard/src/hooks/useProfilePictures.ts+++ b/dashboard/src/hooks/useProfilePictures.ts@@ -3,9 +3,10 @@ import { contactApi } from '../services/api';// Signed CDN URLs rotate: a held picture is reused for an hour, then asked for again.const PICTURE_TTL_MS = 60 * 60 * 1000;-// The batch route answers null for a hidden or missing picture and also for a lookup that failed (throttled, past-// its per-id deadline, or skipped after another lookup timed out), and the two look alike. A null is held for-// a minute only: a failure heals on the next change of ids after that, and a real null costs one more lookup then.+// The batch route answers null for a hidden or missing picture and also for a lookup that failed (throttled or past+// its per-id deadline), and the two look alike; an id skipped after another lookup timed out is absent from the+// answer. A null is held for a minute only: a failure heals on the next change of ids after that, and a real null+// costs one more lookup then. An absent id is asked for again at once.const NULL_TTL_MS = 60 * 1000;interface ResolvedPicture {diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 8a59281e3..795b77532 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5805,7 +5805,7 @@ Request a graceful server restart, optionally orchestrating Docker profiles (add}```-`estimatedTime` (seconds, a typical healthy value rather than a bound; teardown is force-exited 67 s after the grace at the default `WEBHOOK_SHUTDOWN_DRAIN_MS`) = base 15 + 20/postgres + 13/redis + 15/minio + 5/removal. The echoed `profilesToRemove`, and the removal count, already omit any bundled service the environment pins the app to (for example `DATABASE_HOST=postgres` set in the host environment or the project `.env`, or the container name `openwa-postgres`, in any letter case); such a service is never stopped. Likewise the echoed `profiles` omit a bundled service whose host the environment pins to anything else (for example `DATABASE_HOST=db.example.com`): the next boot dials that host, so its container is not started. `orchestration` is present only when Docker is available and at least one managed profile (`postgres`, `redis`, `minio`) remains in `profiles`; `removal` only when Docker is available and at least one managed profile remains in `profilesToRemove` after dropping pinned services and profiles that are also being started. Without Docker, a `data/.orchestration-request.json` signal file is written instead. After responding, `shutdownService.shutdown()` runs (default ~3s grace); readiness returns `503` during drain.+`estimatedTime` (seconds, a typical healthy value rather than a bound; teardown is force-exited 67 s after the grace at the default `WEBHOOK_SHUTDOWN_DRAIN_MS`) = base 15 + 20/postgres + 13/redis + 15/minio + 5/removal. The echoed `profilesToRemove`, and the removal count, already omit any bundled service the environment pins the app to (for example `DATABASE_HOST=postgres` set in the host environment or the project `.env`, or the container name `openwa-postgres`, in any letter case); such a service is kept while the next boot uses its datastore, and stopped by the restart once that datastore is switched off (SQLite, local storage, no consumer of Redis), even when the pinned host still names it. Likewise the echoed `profiles` omit a bundled service whose host the environment pins to anything else (for example `DATABASE_HOST=db.example.com`): the next boot dials that host, so its container is not started. `orchestration` is present only when Docker is available and at least one managed profile (`postgres`, `redis`, `minio`) remains in `profiles`; `removal` only when Docker is available and at least one managed profile remains in `profilesToRemove` after dropping pinned services and profiles that are also being started. Without Docker, a `data/.orchestration-request.json` signal file is written instead. After responding, `shutdownService.shutdown()` runs (default ~3s grace); readiness returns `503` during drain.**Errors:** `401` · `403`@@ -7353,7 +7353,7 @@ Webhook delivery is **at-least-once**. A consumer can legitimately receive the sOutbox creation is best effort, and message persistence and outbox insertion are separate transactions. A write failure or crash between them can still lose the webhook delivery. Failure records with zero attempts are excluded from operator redrive. Capacity and shutdown rejections can still be recovered from an unsettled outbox record; shutdown during retry backoff may follow earlier POSTs. The direct dispatcher leaves its local in-flight work alone during reconciliation. Graceful shutdown drains current queue jobs for at most 10 s; direct sends, an operator redrive replay in flight, and an outbox replay in flight with its plugin hooks, get up to `WEBHOOK_SHUTDOWN_DRAIN_MS` (default 5s). That replay sends at most one more POST, bounded by `WEBHOOK_TIMEOUT`, and no further row is replayed; the next start replays what it left pending.-**Opt-in events are bounded, not replayed.** `message.receipt` fires once per recipient and status, so one flush of buffered receipts can be thousands of events in a tick. Each webhook that names it has a queue of its own before the shared dispatch pool: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, divided among the session's webhooks that name `message.receipt` (each keeps at least one place, and the session as a whole never runs more than that quarter at once, however many webhooks name it), and up to three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` more receipts wait their turn. With the defaults a flush of 500 is delivered in full and at least 750 of a flush of 2000 (754 with one webhook, 751 with four). A flush drains at that quarter of the pool: 750 receipts to a receiver that takes 30 ms each take about 6 s, or about 24 s when four webhooks share the quarter. Any further receipt is dropped for that webhook: it leaves no outbox or failure row, is not replayed, and is counted in `openwa_webhook_delivery_failures_total` once for each webhook it is dropped for. It is logged once per burst and webhook (`webhook_opt_in_dropping` when the webhook starts dropping, then `webhook_opt_in_dropped` with the count). A webhook's queue is its own, so a receiver of it that never answers holds only that webhook's places: the session's other webhooks and its other events are not slowed. Between sessions the isolation has a limit, because the dispatch pool is shared. A receiver that never answers holds its places for a `WEBHOOK_TIMEOUT`; a session holds at most a quarter of the pool at once, four at the defaults, however many webhooks name `message.receipt` and whenever they were added. An event of another session waits for a slot once such sessions together hold all `WEBHOOK_DISPATCH_CONCURRENCY` of them, which at the defaults is four sessions: it then waits one `WEBHOOK_TIMEOUT` with four or five, two with eight. The receipts waiting in all queues together are not capped. Receipts still waiting at shutdown are dropped without being counted.+**Opt-in events are bounded, not replayed.** `message.receipt` fires once per recipient and status, so one flush of buffered receipts can be thousands of events in a tick. Each webhook that names it has a queue of its own before the shared dispatch pool: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, divided among the session's webhooks that name `message.receipt` (the session as a whole never runs more than that quarter at once, however many webhooks name it), and up to three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` more receipts wait their turn. With the defaults a flush of 500 is delivered in full and at least 750 of a flush of 2000 (754 with one webhook, 751 with four). A flush drains at that quarter of the pool: 750 receipts to a receiver that takes 30 ms each take about 6 s, or about 24 s when four webhooks share the quarter. Any further receipt is dropped for that webhook: it leaves no outbox or failure row, is not replayed, and is counted in `openwa_webhook_delivery_failures_total` once for each webhook it is dropped for. It is logged once per burst and webhook (`webhook_opt_in_dropping` when the webhook starts dropping, then `webhook_opt_in_dropped` with the count). A webhook's queue is its own, so a receiver of it that never answers holds only that webhook's places: the session's other webhooks and its other events are not slowed as long as the quarter has a place for each webhook that names `message.receipt` (four at the defaults). With more webhooks, or one added after another's queue was sized, a receiver that never answers can hold the places its siblings need until its `WEBHOOK_TIMEOUT`. Between sessions the isolation has a limit, because the dispatch pool is shared. A receiver that never answers holds its places for a `WEBHOOK_TIMEOUT`; a session holds at most a quarter of the pool at once, four at the defaults, however many webhooks name `message.receipt` and whenever they were added. An event of another session waits for a slot once such sessions together hold all `WEBHOOK_DISPATCH_CONCURRENCY` of them, which at the defaults is four sessions: it then waits one `WEBHOOK_TIMEOUT` with four or five, two with eight. The receipts waiting in all queues together are not capped. Receipts still waiting at shutdown are dropped without being counted.Before downgrading to a version that does not recognize the `queued` outbox state, drain or recover those records and take a backup. Its cleanup may otherwise treat an unsettled queued record as settled. Reverting the terminal-identity migration removes its index but does not restore historical duplicates.diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.tsindex e7171267d..a8f26de1f 100644--- a/src/modules/session/session-engine-controls.ts+++ b/src/modules/session/session-engine-controls.ts@@ -137,7 +137,7 @@ export class StopMarks extends Set<string> {}}-/** Caller callbacks for stop()/delete(), run around the session read that opens each verb. */+/** Caller callbacks for stop(), delete(), forceKill() and logout(), run around the session read that opens each verb. */export interface StopHooks {/** delete() only: the ownership captured by its caller still covers this operation. */ownsClaim?: () => boolean;diff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.tsindex 66c3f6c75..2062134d9 100644--- a/src/modules/session/session.controller.ts+++ b/src/modules/session/session.controller.ts@@ -531,7 +531,7 @@ export class SessionController {description:PAIRING_NOT_READY_409 +' On whatsapp-web.js also answered, with nothing sent to WhatsApp, when the requested number is the stored ' +- 'phone of another session of this gateway: log that session out or delete it first.',+ 'phone of another session of this gateway: delete that session, or log it out while it runs, first.',})@ApiResponse({ status: 503, description: PAIRING_TRANSPORT_503 })async requestPairingCode(diff --git a/src/modules/session/session.service.ts b/src/modules/session/session.service.tsindex e769a94da..3bf3ed438 100644--- a/src/modules/session/session.service.ts+++ b/src/modules/session/session.service.ts@@ -1346,7 +1346,7 @@ export class SessionService implements OnModuleDestroy, OnModuleInit, OnApplicat// Baileys adds a companion device and showed no such effect, so two of its sessions may share a number.if (this.pairingMayRevoke() && (await this.otherSessionHoldsNumber(id, phoneNumber))) {throw new ConflictException(- 'That number is linked to another session. Log that session out or delete it before pairing this one.',+ 'That number is linked to another session. Delete that session, or log it out while it runs, before pairing this one.',);}