Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(session): scope the reconnect keys to the gateway's reconnect
Yudhi Armyndharis6fe6c93fb69a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 94ef9158e..63db9aaca 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Documentation+- The docs and the OpenAPI field descriptions scope `maxReconnectAttempts` and `reconnectBaseDelay` to the gateway's own reconnect: on Baileys that is only the reconnect after a logged-out close, since the engine retries every other drop itself, with a fixed 1s to 60s backoff and no attempt cap ([#1651](https://github.com/rmyndharis/OpenWA/issues/1651)).- The docs, the README, the OpenAPI field descriptions and the dashboard's auto-reject hint mark call rejection, `autoRejectCalls` and the call outcome events as Baileys only, and `call.received` as not reliable on whatsapp-web.js ([#1118](https://github.com/rmyndharis/OpenWA/discussions/1118)). Thanks @etondeengole for the report.### Upgrade notes (behavior changes)@@ -143,7 +144,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- The amd64 image moves from Chrome for Testing 146 to 153, so every amd64 rollback to 0.23.4 or earlier crosses a browser major; the arm64 image runs the chromium Debian ships at build time, whose major can differ between releases.- A `LOG_LEVEL` other than `error`, `warn`, `info`, `debug` or `verbose` now stops the boot instead of logging at info.- Multi-node deployments run the lapsed-status correction even with `AUTO_START_SESSIONS` off, so every node needs a synced clock and, on PostgreSQL, one time zone without daylight saving (`TZ=UTC` recommended); otherwise live sessions can be marked disconnected (see `docs/13-horizontal-scaling.md`).-- A session with an explicit `maxReconnectAttempts` now stops in `failed` once those attempts run out during an outage; before, a limit above about 6 at the default base delay was never reached and the session retried indefinitely.+- A session with an explicit `maxReconnectAttempts` now stops in `failed` once the gateway's reconnect attempts run out during an outage; before, a limit above about 6 at the default base delay was never reached and the session retried indefinitely. On Baileys this covers only the reconnect after a logged-out close: every other drop is retried inside the engine, with its own backoff and no cap.- A dashboard or client signed in with a `VIEWER` key no longer receives the pairing QR over the `/events` WebSocket, matching the OPERATOR role `GET /api/sessions/{sessionId}/qr` already required.- Installing from source now needs Node.js 22.19 or newer; the published Docker image is unaffected.- Python SDK: `ChatHistoryMessage` marks the keys the contract always sends as required and narrows `type` and `kind` to literals, so a hand-built partial dict or a plain `str` assigned to either no longer type-checks.diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 9f44ecee7..7bba84716 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -373,11 +373,11 @@ clears it, and so does a gateway restart.}```-| Key | Default | Effect |-| ---------------------- | --------- | ------------------------------------------------------------------------ |-| `maxReconnectAttempts` | unlimited | Reconnect attempt cap, clamped to 0–20 (`0` disables reconnect entirely) |-| `reconnectBaseDelay` | `5000` ms | Base delay of the reconnect backoff, clamped to 1000–300000 ms |-| `autoRejectCalls` | `false` | Auto-reject an incoming call as soon as it rings (Baileys only) |+| Key | Default | Effect |+| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `maxReconnectAttempts` | unlimited | Reconnect attempt cap, clamped to 0–20 (`0` disables reconnect entirely). Bounds the gateway's own reconnect: every reconnect on whatsapp-web.js, and on Baileys only the one after a logged-out close |+| `reconnectBaseDelay` | `5000` ms | Base delay of the reconnect backoff, clamped to 1000–300000 ms. Same engine scope as `maxReconnectAttempts` |+| `autoRejectCalls` | `false` | Auto-reject an incoming call as soon as it rings (Baileys only) |Set them at creation with `POST /api/sessions`, or on an existing session with`PATCH /api/sessions/{sessionId}/config` — no restart, and no re-scan of the QR. The patch merges, so a keydiff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 056ef6dab..f1bfb3e3e 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -299,7 +299,9 @@ in it is stored but ignored).````maxReconnectAttempts: null` means unlimited (the default); `reconnectBaseDelay` is milliseconds.-See §5 (Database Design) for what each key does and the moment it is read.+Both bound the gateway's own reconnect, which on Baileys covers only the reconnect after a+logged-out close: that engine retries a transient drop internally, with a fixed 1s to 60s backoff+and no attempt cap. See §5 (Database Design) for what each key does and the moment it is read.**Errors:** `401` missing/invalid key, or key not scoped to this session · `404` session not found@@ -321,11 +323,11 @@ and therefore apply on the next start, leaving a reconnect sequence already in f**Request body** — `UpdateSessionConfigDto` (any subset; each key also accepts `null`)-| Field | Type | Constraints | Description |-| ---------------------- | ------- | ------------------------- | ------------------------------------------------------------------ |-| `autoRejectCalls` | boolean | — | Auto-reject every incoming call as soon as it rings (Baileys only) |-| `maxReconnectAttempts` | number | integer, 0–20 | Reconnect attempt cap (`0` disables reconnect; `null` = unlimited) |-| `reconnectBaseDelay` | number | integer, 1000–300000 (ms) | Base delay of the reconnect backoff |+| Field | Type | Constraints | Description |+| ---------------------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `autoRejectCalls` | boolean | — | Auto-reject every incoming call as soon as it rings (Baileys only) |+| `maxReconnectAttempts` | number | integer, 0–20 | Reconnect attempt cap (`0` disables reconnect; `null` = unlimited). Bounds the gateway's own reconnect: every reconnect on whatsapp-web.js, and on Baileys only the one after a logged-out close |+| `reconnectBaseDelay` | number | integer, 1000–300000 (ms) | Base delay of the reconnect backoff, on the same engine scope |```json{ "maxReconnectAttempts": 5 }diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex c59e00625..73847b030 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -592,7 +592,10 @@ The reconnect backoff is configured **per session**, not by environment variable`reconnectBaseDelay` is the exponential-backoff base in milliseconds (clamped to 1000–300000,default 5000). `maxReconnectAttempts` is clamped to 0–20 — `0` disables auto-reconnect entirely, and-leaving it unset means unlimited retries with the delay parking at a 5-minute cap. Subscribe to the+leaving it unset means unlimited retries with the delay parking at a 5-minute cap. Both keys bound+the gateway's own reconnect. On Baileys that is only the reconnect after a logged-out close: every+other drop is retried inside the engine, with a fixed 1s to 60s backoff and no attempt cap, so a+session behind an unreachable network keeps retrying there whatever these keys say. Subscribe to the`session.reconnect_loop` webhook to be alerted on every 5th consecutive attempt.On a slow host, raise the first-boot init wait with `WWEBJS_AUTH_TIMEOUT_MS` (see _QR generationdiff --git a/openapi.json b/openapi.jsonindex 680a76e49..18c0f3b80 100644--- a/openapi.json+++ b/openapi.json@@ -10094,7 +10094,7 @@},"config": {"type": "object",- "description": "Session configuration. Only three keys are read: autoRejectCalls (boolean, default false, Baileys engine only) rejects incoming calls as soon as they ring — the call.received event is still emitted first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects; and reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base. Anything else is stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, without restarting the session.",+ "description": "Session configuration. Only three keys are read: autoRejectCalls (boolean, default false, Baileys engine only) rejects incoming calls as soon as they ring — the call.received event is still emitted first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects and reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base, both for the gateway's own reconnect only (on Baileys the engine retries a transient drop itself, with a fixed backoff and no cap). Anything else is stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, without restarting the session.","example": {"autoRejectCalls": false,"maxReconnectAttempts": 5,@@ -10250,13 +10250,13 @@},"maxReconnectAttempts": {"type": "number",- "description": "Reconnect attempt cap; `null` means unlimited",+ "description": "Reconnect attempt cap; `null` means unlimited. Bounds the gateway's own reconnect (every reconnect on whatsapp-web.js; on Baileys only the one after a logged-out close).","example": 5,"nullable": true},"reconnectBaseDelay": {"type": "number",- "description": "Base reconnect backoff in milliseconds",+ "description": "Base reconnect backoff in milliseconds, on the same engine scope as `maxReconnectAttempts`","example": 5000}},@@ -10277,7 +10277,7 @@},"maxReconnectAttempts": {"type": "number",- "description": "Cap on consecutive reconnect attempts (`0` disables reconnect entirely). Send `null` for unlimited, which is the default. Applies on the next session start, not to a reconnect sequence already in flight.",+ "description": "Cap on consecutive reconnect attempts (`0` disables reconnect entirely). Send `null` for unlimited, which is the default. Applies on the next session start, not to a reconnect sequence already in flight. Bounds the gateway's own reconnect, which is every reconnect on whatsapp-web.js and, on Baileys, only the one after a logged-out close: the Baileys engine retries a transient drop itself, with a fixed 1s to 60s backoff and no cap.","minimum": 0,"maximum": 20,"example": 5,@@ -10285,7 +10285,7 @@},"reconnectBaseDelay": {"type": "number",- "description": "Base delay of the reconnect backoff in milliseconds. Applies on the next session start, not to a reconnect sequence already in flight.",+ "description": "Base delay of the reconnect backoff in milliseconds. Applies on the next session start, not to a reconnect sequence already in flight. Same engine scope as `maxReconnectAttempts`: the Baileys engine's internal retry uses its own fixed backoff instead.","minimum": 1000,"maximum": 300000,"example": 5000,diff --git a/src/modules/session/dto/create-session.dto.ts b/src/modules/session/dto/create-session.dto.tsindex b73a66015..c14d44acf 100644--- a/src/modules/session/dto/create-session.dto.ts+++ b/src/modules/session/dto/create-session.dto.ts@@ -20,8 +20,10 @@ export class CreateSessionDto {description:'Session configuration. Only three keys are read: autoRejectCalls (boolean, default false, ' +'Baileys engine only) rejects incoming calls as soon as they ring — the call.received event is still emitted ' +- 'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects; and ' +- 'reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base. Anything else is ' ++ 'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects and ' ++ 'reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base, both for the ' ++ "gateway's own reconnect only (on Baileys the engine retries a transient drop itself, with a " ++ 'fixed backoff and no cap). Anything else is ' +'stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, ' +'without restarting the session.',example: { autoRejectCalls: false, maxReconnectAttempts: 5, reconnectBaseDelay: 5000 },diff --git a/src/modules/session/dto/session-config.dto.ts b/src/modules/session/dto/session-config.dto.tsindex 97270713a..775084caa 100644--- a/src/modules/session/dto/session-config.dto.ts+++ b/src/modules/session/dto/session-config.dto.ts@@ -37,7 +37,9 @@ export class UpdateSessionConfigDto {description:'Cap on consecutive reconnect attempts (`0` disables reconnect entirely). Send `null` for ' +'unlimited, which is the default. Applies on the next session start, not to a reconnect ' +- 'sequence already in flight.',+ "sequence already in flight. Bounds the gateway's own reconnect, which is every reconnect on " ++ 'whatsapp-web.js and, on Baileys, only the one after a logged-out close: the Baileys engine ' ++ 'retries a transient drop itself, with a fixed 1s to 60s backoff and no cap.',minimum: 0,maximum: 20,example: 5,@@ -56,7 +58,8 @@ export class UpdateSessionConfigDto {@ApiPropertyOptional({description:'Base delay of the reconnect backoff in milliseconds. Applies on the next session start, ' +- 'not to a reconnect sequence already in flight.',+ 'not to a reconnect sequence already in flight. Same engine scope as `maxReconnectAttempts`: ' ++ "the Baileys engine's internal retry uses its own fixed backoff instead.",minimum: 1000,maximum: 300000,example: 5000,@@ -85,13 +88,18 @@ export class SessionConfigResponseDto {autoRejectCalls!: boolean;@ApiProperty({- description: 'Reconnect attempt cap; `null` means unlimited',+ description:+ "Reconnect attempt cap; `null` means unlimited. Bounds the gateway's own reconnect (every " ++ 'reconnect on whatsapp-web.js; on Baileys only the one after a logged-out close).',example: 5,nullable: true,type: Number,})maxReconnectAttempts!: number | null;- @ApiProperty({ description: 'Base reconnect backoff in milliseconds', example: 5000 })+ @ApiProperty({+ description: 'Base reconnect backoff in milliseconds, on the same engine scope as `maxReconnectAttempts`',+ example: 5000,+ })reconnectBaseDelay!: number;}