Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(session): say when the reconnect attempt count restarts

Yudhi Armyndharisdea91cf758fb
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 5fb8ebd05..ebd68d960 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -384,6 +384,9 @@ clears it, and so does a gateway restart.
| `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) |
+The reconnect attempt count restarts only once the session has stayed READY for 5 minutes, so a
+session that keeps dropping sooner than that spends a finite `maxReconnectAttempts` and ends FAILED.
+
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
it does not mention keeps its stored value, and an explicit `null` clears a key back to the default
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d1d8e179d..90c4e788e 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -303,7 +303,9 @@ in it is stored but ignored).
`maxReconnectAttempts: null` means unlimited (the default); `reconnectBaseDelay` is milliseconds.
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.
+and no attempt cap. The attempt count restarts only once the session has stayed READY for 5 minutes,
+so a session that keeps dropping sooner than that spends its 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
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 81f87f1b4..2e2354b91 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -649,7 +649,9 @@ leaving it unset means unlimited retries with the delay parking at a 5-minute ca
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.
+`session.reconnect_loop` webhook to be alerted on every 5th consecutive attempt. Attempts stop being
+consecutive only once the session has stayed READY for 5 minutes, so a session that keeps dropping
+sooner than that spends a finite cap and ends FAILED.
On a slow host, raise the first-boot init wait with `WWEBJS_AUTH_TIMEOUT_MS` (see _QR generation
times out on slow first boot_ above).
diff --git a/openapi.json b/openapi.json
index 724140ce3..f458bdcfc 100644
--- a/openapi.json
+++ b/openapi.json
@@ -10332,7 +10332,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, and 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 a restart: autoRejectCalls applies from the next incoming call, the two reconnect settings from the next session start.",
+ "description": "Session configuration. Only three keys are read: autoRejectCalls (boolean, default false, Baileys engine only) rejects incoming calls as soon as they ring, and the call.received event is still emitted first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects (the count restarts once the session has stayed READY for 5 minutes) 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 a restart: autoRejectCalls applies from the next incoming call, the two reconnect settings from the next session start.",
"example": {
"autoRejectCalls": false,
"maxReconnectAttempts": 5,
diff --git a/src/modules/session/dto/create-session.dto.ts b/src/modules/session/dto/create-session.dto.ts
index 44fa3ce3a..a39624c65 100644
--- a/src/modules/session/dto/create-session.dto.ts
+++ b/src/modules/session/dto/create-session.dto.ts
@@ -21,7 +21,8 @@ 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, and the call.received event is still emitted ' +
- 'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects and ' +
+ 'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects (the count ' +
+ 'restarts once the session has stayed READY for 5 minutes) 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 ' +