Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(session): say engineLoaded is actionable only where it routes

Yudhi Armyndharis1db12cf16530
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 070a38ac5..fe1510822 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -243,7 +243,7 @@ List all sessions, scoped to the API key's `allowedSessions`, ordered `createdAt
`code` is the engine's own token for the cause, passed through verbatim (`TOS_BLOCK`, `BIZ_QUALITY`, `WEB_COMPANION_ONLY`, …), so a value newer than your gateway build still reaches you rather than being flattened. Because `tos_block`/`proxy_block` prevent the session from linking at all, neither can appear alongside a `ready` status; a `reachout_timelock` can, and usually does. Like `engineLoaded`, the field is derived from live engine state, never persisted, and re-established on the next connect. Changes are also delivered as the `session.restriction` webhook.
-`engineLoaded` reports whether a node of the gateway holds a live engine for the session at the moment of the response: the process that answered, or, in a multi-node deployment, the node with a live claim on the session. It is the precondition the lifecycle routes enforce, and **`status` is not a substitute for it**: `disconnected` covers both a session whose engine is still registered while an automatic reconnect backs off — where `POST /start` answers `400` — and one stopped through `POST /stop`, which has no engine and does need a start. When `engineLoaded` is `true`, `stop`, `logout` and `force-kill` can act; when it is `false`, `start` is the applicable route. The field is derived per request from live state (this process's engines and the other nodes' session claims), so it is never persisted and never appears in historical/exported data.
+`engineLoaded` reports whether a node of the gateway holds a live engine for the session at the moment of the response: the process that answered, or, in a multi-node deployment, the node with a live claim on the session. It is the precondition the lifecycle routes enforce, and **`status` is not a substitute for it**: `disconnected` covers both a session whose engine is still registered while an automatic reconnect backs off — where `POST /start` answers `400` — and one stopped through `POST /stop`, which has no engine and does need a start. When `engineLoaded` is `true`, `stop`, `logout` and `force-kill` can act; when it is `false`, `start` is the applicable route. For a session another node holds, that assumes request routing (`NODE_URL` set on every node, see [13 - Horizontal Scaling](./13-horizontal-scaling.md)): the lifecycle routes are then forwarded to the owner and act there. Without routing only the owner can act on the session; on any other node `start` and `stop` answer `409` and `logout` and `force-kill` answer `400`. The field is derived per request from live state (this process's engines and the other nodes' session claims), so it is never persisted and never appears in historical/exported data.
**Errors:** `400` empty or repeated `name` · `401` missing/invalid `X-API-Key`
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index 96ff7f520..2b5cab589 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -66,7 +66,10 @@
> the first two come from what this node's engines recorded, `active` counts only this node's engines,
> and `memoryUsage` is this process's. `engineLoaded` is the exception, since it also counts a live
> claim by another node. With routing on, `GET /api/sessions/:sessionId` is forwarded to the owner, so
-> its answer is the owner's.
+> its answer is the owner's; `start`, `stop`, `logout` and `force-kill` are forwarded the same way, so a
+> `true` means they can act. Without `NODE_URL` nothing is forwarded, so a node that does not hold the
+> session still reports `true` but cannot act on it: `start` and `stop` answer `409` there, and `logout`
+> and `force-kill` answer `400`.
>
> **A failed forward says whether the owner could have acted.** When the owner cannot be
> reached at all (connection refused, unresolvable or unusable `NODE_URL`), the answer is