Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(status): document the Baileys 403 on a status revoke

Yudhi Armyndharis661344534f5c
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 2b54162f8..cca2207b2 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4421,7 +4421,7 @@ Delete one of the session's own posted statuses.
The service returns `void`; the controller returns a fixed success object. DELETE default status is `200`.
-**Errors:** `401` missing/invalid API key · `403` key lacks `OPERATOR` role, or (whatsapp-web.js) the id is not one of the account's own statuses · `404` `Session {id} not found or not connected` · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request, so the revoke did not complete
+**Errors:** `401` missing/invalid API key · `403` key lacks `OPERATOR` role, or (whatsapp-web.js) the id is not one of the account's own statuses, or (Baileys) this session did not post the status in the last 24 hours, so its recipients are unknown (a status posted from the phone or from another node, or posted before a restart, is refused too) · `404` `Session {id} not found or not connected` · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request, so the revoke did not complete
Safe to retry: revoking an already-revoked status converges. The status POST routes deliberately do
NOT answer `503` for the same failure, because whatsapp-web.js can throw after the request is on the
diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.md
index b8d43efe0..3f1acdb9b 100644
--- a/docs/29-engine-capability-matrix.md
+++ b/docs/29-engine-capability-matrix.md
@@ -926,10 +926,13 @@ adapter boundary — none silently stubs.
`400` on Baileys. ffmpeg is deliberately not wired in on the Baileys side: the binary ships only
in the Docker image, so depending on it would make the same request succeed or fail depending on
how the gateway was installed.
-- **`deleteStatus` (baileys).** Marked ✅ (no throw), but the `sendMessage(status@broadcast,
-{delete})` revoke shape is _empirically unverified_ — only posting was live-spiked. May fall back
- to 501 if WA rejects the shape. On wwjs it calls `revokeStatusMessage(statusId)` (own status
- only).
+- **`deleteStatus` (baileys).** Baileys sends a status stanza, the revoke included, to exactly its
+ `statusJidList`, so the revoke is addressed to the recipients the adapter remembered when it posted
+ the status. It keeps them in memory for 24 hours, so a status this session did not post in the last
+ 24 hours (one posted from the phone or from another node, or posted before a restart) is refused
+ with `403` (`EngineRefusedError`) instead of a revoke that reaches nobody while the status stays up.
+ The `sendMessage(status@broadcast, {delete})` revoke shape is _empirically unverified_: only posting
+ was live-spiked. On wwjs it calls `revokeStatusMessage(statusId)` (own status only).
- **`getContactStatus` / `getContactStatuses` (wwjs).** `Status.type` is the `text|image|video`
union — audio/other story types collapse to `text`.
- **`archiveChat` / `clearChatMessages` / `deleteChat` / `sendSeen` / `markUnread` (baileys).** All