Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(api): describe every 400 of the group settings update

Yudhi Armyndharis96c45418079f
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d92a15cce..73dcd321a 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -3388,7 +3388,7 @@ Update group settings. Each present field maps to one engine call; absent fields
{ "success": true, "message": "Group settings updated" }
```
-**Errors:** `400` session is not started / empty patch / unknown body field · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, the account is not a group admin (`memberAddMode` on whatsapp-web.js), or a key restricted to selected chats names a group outside its allowlist · `404` group not found · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause
+**Errors:** `400` session is not started / empty patch / unknown body field / a value outside its constraints in the table above, or `null` · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, the account is not a group admin (`memberAddMode` on whatsapp-web.js), or a key restricted to selected chats names a group outside its allowlist · `404` group not found · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause
#### GET /api/sessions/:sessionId/groups/:groupId/membership-requests
diff --git a/openapi.json b/openapi.json
index ba6b89c25..79a41f052 100644
--- a/openapi.json
+++ b/openapi.json
@@ -10154,7 +10154,7 @@
}
},
"400": {
- "description": "No setting provided, or a value is not a boolean",
+ "description": "No setting provided, an unknown body field, or an invalid value: `announce` and `locked` take a boolean, `ephemeralSeconds` an integer of 0 or more, `memberAddMode` `all` or `admins`, and `null` is refused. Also answered when the session is not started (no engine is running for it).",
"content": {
"application/json": {
"schema": {
diff --git a/src/modules/group/group.controller.spec.ts b/src/modules/group/group.controller.spec.ts
index 1a48493d0..3c05b0fc1 100644
--- a/src/modules/group/group.controller.spec.ts
+++ b/src/modules/group/group.controller.spec.ts
@@ -183,6 +183,17 @@ describe('GroupController OpenAPI responses', () => {
expect(responsesOf('getSettings')['503']?.description).not.toContain('5xx');
});
+ // GroupSettingsDto checks each field against its own type or range and refuses an explicit null, and
+ // the engine lookup answers 400 for a session that is not started, so the 400 names all of them.
+ it('describes every 400 of the settings update', () => {
+ const description = responsesOf('updateSettings')['400']?.description ?? '';
+ for (const part of ['`ephemeralSeconds`', '0 or more', '`memberAddMode`', '`all` or `admins`', '`null`']) {
+ expect(description).toContain(part);
+ }
+ expect(description).toContain('not started');
+ expect(description).not.toContain('not a boolean');
+ });
+
it('declares the rate-limited 503 on group creation', () => {
expect(responsesOf('create')['503']?.description).toContain('429');
});
diff --git a/src/modules/group/group.controller.ts b/src/modules/group/group.controller.ts
index f91bb4d50..daccca20c 100644
--- a/src/modules/group/group.controller.ts
+++ b/src/modules/group/group.controller.ts
@@ -185,7 +185,13 @@ export class GroupController {
@ApiParam({ name: 'groupId', description: 'Group ID' })
@ApiBody({ type: GroupSettingsDto })
@ApiResponse({ status: 200, description: 'Group settings updated', type: GroupAckResponseDto })
- @ApiResponse({ status: 400, description: 'No setting provided, or a value is not a boolean' })
+ @ApiResponse({
+ status: 400,
+ description:
+ 'No setting provided, an unknown body field, or an invalid value: `announce` and `locked` take a boolean, ' +
+ '`ephemeralSeconds` an integer of 0 or more, `memberAddMode` `all` or `admins`, and `null` is refused. ' +
+ 'Also answered when the session is not started (no engine is running for it).',
+ })
@ApiResponse({ status: 403, description: 'The engine refused the change (the account is not a group admin)' })
@ApiResponse({ status: 404, description: 'Group not found' })
@ApiResponse({ status: 501, description: 'The active engine does not support a requested setting' })