Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk): document the incomplete force-kill answer

Yudhi Armyndharis5494ac48638c
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 975187b7c..24f81180c 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -144,7 +144,7 @@ The top-level client also exposes:
| `start` | `start(id)` | Start a session and initialize the WhatsApp connection. **OPERATOR** |
| `stop` | `stop(id)` | Stop a session and disconnect gracefully. **OPERATOR** |
| `logout` | `logout(id)` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** |
-| `forceKill` | `forceKill(id)` | Force-kill a stuck session (SIGKILL + teardown). **OPERATOR** |
+| `forceKill` | `forceKill(id)` | Force-kill a stuck session (SIGKILL + teardown). A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** |
| `getQrCode` | `getQrCode(id)` | Get the current QR code for authentication (live from the engine). **OPERATOR** |
| `requestPairingCode` | `requestPairingCode(id, body)` | Request an 8-character pairing code for phone-based login. **OPERATOR** |
| `setOnlinePresence` | `setOnlinePresence(id, body)` | Set the account's own global presence (appear online or offline). **OPERATOR** |
@@ -523,7 +523,7 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All
| `start` | `start(session_id) -> SessionResponse` | Start (connect) a session. **OPERATOR** |
| `stop` | `stop(session_id) -> SessionResponse` | Stop a session. **OPERATOR** |
| `logout` | `logout(session_id) -> SessionResponse` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** |
-| `force_kill` | `force_kill(session_id) -> SessionResponse` | Force-terminate a session. **OPERATOR** |
+| `force_kill` | `force_kill(session_id) -> SessionResponse` | Force-terminate a session. A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** |
| `get_qr_code` | `get_qr_code(session_id) -> QrCodeResponse` | Fetch the login QR code. **OPERATOR** |
| `request_pairing_code` | `request_pairing_code(session_id, body) -> PairingCodeResponse` | Request a phone-number pairing code. **OPERATOR** |
| `set_online_presence` | `set_online_presence(session_id, body) -> SuccessResult` | Set the account's own global presence (appear online or offline). **OPERATOR** |
@@ -875,7 +875,7 @@ All payloads are associative arrays; all listed methods are synchronous and retu
| `start` | `start(string $id): array` | Start a session. **OPERATOR** |
| `stop` | `stop(string $id): array` | Stop a session. **OPERATOR** |
| `logout` | `logout(string $id): array` | Attempt an engine-native unlink of this device, then stop the session. A `200` means the unlink + local cleanup completed (not an independent Linked-Devices observation); a later `start` needs a fresh QR. A `502` (`SESSION_LOGOUT_INCOMPLETE`) stops locally but leaves the operation incomplete; start and retry. Requires a running session. **OPERATOR** |
-| `forceKill` | `forceKill(string $id): array` | Force-kill a session. **OPERATOR** |
+| `forceKill` | `forceKill(string $id): array` | Force-kill a session. A `502` (`SESSION_FORCE_KILL_INCOMPLETE`) stops locally but the engine process may still be running; a retry answers `400`, so restart the node to reap it. **OPERATOR** |
| `getQrCode` | `getQrCode(string $id): array` | Fetch the current QR code. **OPERATOR** |
| `requestPairingCode` | `requestPairingCode(string $id, array $body): array` | Request a phone-pairing code. **OPERATOR** |
| `setOnlinePresence` | `setOnlinePresence(string $id, array $body): array` | Set the account's own global presence (appear online or offline). **OPERATOR** |