Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(openapi): declare the group-list and presence 503s

Yudhi Armyndharis1ecfc50b0952
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index f26fada77..98aab9772 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -957,7 +957,7 @@ reporting success.
{ "success": true }
```
-**Errors:** `400` session not started / validation · `401` · `403` key lacks OPERATOR role · `404` session not found · `409` engine not ready
+**Errors:** `400` session not started / validation · `401` · `403` key lacks OPERATOR role · `404` session not found · `409` engine not ready · `503` the whatsapp-web.js page died or did not answer within the protocol timeout (retryable)
#### POST /api/sessions/:sessionId/chats/read
diff --git a/openapi.json b/openapi.json
index 7ecf00a76..5d9757add 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1836,7 +1836,7 @@
}
},
"503": {
- "description": "WhatsApp did not answer the group-list query. Deliberately not reported as an empty list — the engine returns the same empty value for \"you are in no groups\", and a caller cannot tell those apart from the body.",
+ "description": "WhatsApp did not answer the group-list query. Deliberately not reported as an empty list — the engine returns the same empty value for \"you are in no groups\", and a caller cannot tell those apart from the body. On Baileys, also answered when WhatsApp rate-limits or times out the request (code 429 or 408); retry after a pause.",
"content": {
"application/json": {
"schema": {
@@ -2355,6 +2355,16 @@
}
}
}
+ },
+ "503": {
+ "description": "The whatsapp-web.js page connection died, or WhatsApp Web did not answer within the protocol timeout. Nothing was confirmed; setting presence converges when repeated, so a retry is safe.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
}
},
"summary": "Set the account's own global presence (appear online or offline)",
diff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.ts
index 9cb6ff578..7c8fea0ca 100644
--- a/src/modules/session/session.controller.ts
+++ b/src/modules/session/session.controller.ts
@@ -522,7 +522,8 @@ export class SessionController {
description:
'WhatsApp did not answer the group-list query. Deliberately not reported as an empty list — ' +
'the engine returns the same empty value for "you are in no groups", and a caller cannot tell ' +
- 'those apart from the body.',
+ 'those apart from the body. On Baileys, also answered when WhatsApp rate-limits or times out the ' +
+ 'request (code 429 or 408); retry after a pause.',
})
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiQuery({ name: 'limit', required: false, description: 'Max groups to return (1–1000, default 1000)' })
@@ -665,6 +666,12 @@ export class SessionController {
' On Baileys this route also answers `409` for a `ready` session whose account push name has ' +
'not synced yet. Nothing was sent, and a retry succeeds only once the name has synced.',
})
+ @ApiResponse({
+ status: 503,
+ description:
+ 'The whatsapp-web.js page connection died, or WhatsApp Web did not answer within the protocol ' +
+ 'timeout. Nothing was confirmed; setting presence converges when repeated, so a retry is safe.',
+ })
async setOnlinePresence(
@Param('sessionId', ParseUUIDPipe) id: string,
@Body() dto: SetOwnPresenceDto,