Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(labels): stop promising a 400 for a personal account

Yudhi Armyndharis4d8e04c12156
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index e1225e00d..0e8b03c6c 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -3941,7 +3941,7 @@ that label** instead of failing, because the protocol has no create-only form.
#### GET /api/sessions/:sessionId/labels
-List all labels defined for the session (WhatsApp Business accounts only).
+List all labels defined for the session. Labels exist only on a WhatsApp Business account: on whatsapp-web.js a personal account answers `200` with an empty array, not an error. Baileys has no label read and answers `501` on either account type.
**Auth:** API key
@@ -3962,7 +3962,7 @@ List all labels defined for the session (WhatsApp Business accounts only).
Bare array — raw return of `engine.getLabels()`; no envelope.
-**Errors:** `400` session is not started (no live engine), or the account is not a WhatsApp Business account · `401` missing/invalid API key · `501` the Baileys engine does not implement label reads (whatsapp-web.js only) · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-read (retryable)
+**Errors:** `400` session is not started (no live engine) · `401` missing/invalid API key · `501` the Baileys engine does not implement label reads (whatsapp-web.js only) · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-read (retryable)
#### GET /api/sessions/:sessionId/labels/:labelId
diff --git a/openapi.json b/openapi.json
index 17f850d8b..eb64ae196 100644
--- a/openapi.json
+++ b/openapi.json
@@ -6539,7 +6539,7 @@
],
"responses": {
"200": {
- "description": "List of labels",
+ "description": "List of labels (empty on a personal, non-Business account)",
"content": {
"application/json": {
"schema": {
@@ -6552,7 +6552,7 @@
}
},
"400": {
- "description": "Session not ready or not a business account"
+ "description": "Session not started"
},
"409": {
"description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."
diff --git a/src/modules/label/label.controller.ts b/src/modules/label/label.controller.ts
index 6ac7c334f..5aae6af85 100644
--- a/src/modules/label/label.controller.ts
+++ b/src/modules/label/label.controller.ts
@@ -21,8 +21,12 @@ export class LabelController {
@Get()
@ApiOperation({ summary: 'Get all labels (WhatsApp Business only)' })
@ApiParam({ name: 'sessionId', description: 'Session ID' })
- @ApiResponse({ status: 200, description: 'List of labels', type: [LabelDto] })
- @ApiResponse({ status: 400, description: 'Session not ready or not a business account' })
+ @ApiResponse({
+ status: 200,
+ description: 'List of labels (empty on a personal, non-Business account)',
+ type: [LabelDto],
+ })
+ @ApiResponse({ status: 400, description: 'Session not started' })
@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })
@ApiResponse({ status: 501, description: ENGINE_NOT_SUPPORTED_501 })
@ApiResponse({