Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(session): scope the reconnect keys to the gateway's reconnect

Yudhi Armyndharis6fe6c93fb69a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 key
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 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.md
index 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 generation
diff --git a/openapi.json b/openapi.json
index 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.ts
index 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.ts
index 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;
}