Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(api): document the over-allowance 400 on group create and add
Yudhi Armyndharis0020105b3903
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 9dd2bf9f8..f26fada77 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -2889,7 +2889,7 @@ Returns the created `Group` directly (raw).}```-**Errors:** `400` validation (missing/empty `name` or `participants`, or any non-DTO field) / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused the create · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap, see Send pacing) · `501` not supported on the active engine · `503` WhatsApp rate-limited the create on Baileys (code 429; nothing was created, so a retry is safe; a timed-out create is not answered `503`)+**Errors:** `400` validation (missing/empty `name` or `participants`, or any non-DTO field) / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`), or (send pacing on) the request names more new contacts than the whole day's cold-reachout allowance (no `retryAfterSeconds`; split the batch, see Send pacing) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused the create · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap reached for today, see Send pacing) · `501` not supported on the active engine · `503` WhatsApp rate-limited the create on Baileys (code 429; nothing was created, so a retry is safe; a timed-out create is not answered `503`)#### POST /api/sessions/:sessionId/groups/:groupId/participants@@ -2931,7 +2931,7 @@ Status is forced to `200` via `@HttpCode(HttpStatus.OK)` (overriding the POST deEach entry is a `ParticipantOperationResult`: `id` (the participant the outcome belongs to), `success` (true only when the engine confirmed the change for that participant), and the optional engine-reported `status`/`message` (e.g. `200` ok, `403` invite-only/not-admin, `404` not registered, `409` already a member). Engines that only confirm the batch as a whole report one success entry per requested participant.-**Errors:** `400` validation / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused every listed participant (a partial refusal still returns `200`) · `404` group not found · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap, see Send pacing) · `503` session not ready or dependency unavailable (retryable)+**Errors:** `400` validation / session not started, or a participant does not name an individual (phone, `<phone>@c.us` or `<lid>@lid`), or (send pacing on) the request names more new contacts than the whole day's cold-reachout allowance (no `retryAfterSeconds`; split the batch, see Send pacing) · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or WhatsApp refused every listed participant (a partial refusal still returns `200`) · `404` group not found · `409` conflict or engine not ready (retryable) · `429` `SEND_PACING_LIMITED` when send pacing is enabled (cold-reachout cap reached for today, see Send pacing) · `503` session not ready or dependency unavailable (retryable)#### DELETE /api/sessions/:sessionId/groups/:groupId/participantsdiff --git a/src/modules/group/group.controller.spec.ts b/src/modules/group/group.controller.spec.tsindex 83e86cc30..1aec6c2f1 100644--- a/src/modules/group/group.controller.spec.ts+++ b/src/modules/group/group.controller.spec.ts@@ -171,4 +171,13 @@ describe('GroupController OpenAPI responses', () => {it('declares the rate-limited 503 on group creation', () => {expect(responsesOf('create')['503']?.description).toContain('429');});++ // A batch larger than a whole day's cold-reachout allowance is refused 400 without a retry hint.+ it.each(['create', 'addParticipants'])('%s describes the over-allowance 400', name => {+ expect(responsesOf(name)['400']?.description).toContain('cold-reachout allowance');+ });++ it.each(['removeParticipants', 'promoteParticipants', 'demoteParticipants'])('%s keeps the unpaced 400', name => {+ expect(responsesOf(name)['400']?.description).not.toContain('cold-reachout');+ });});diff --git a/src/modules/group/group.controller.ts b/src/modules/group/group.controller.tsindex ec380cf21..3e414884b 100644--- a/src/modules/group/group.controller.ts+++ b/src/modules/group/group.controller.ts@@ -60,6 +60,12 @@ const PARTICIPANT_ID_400 ='A participant does not name an individual. Pass a phone number, `<phone>@c.us` or `<lid>@lid`; ' +'a group id or free text is rejected.';+// Only the two routes that add people to a group are paced; remove, promote and demote are not.+const PACED_PARTICIPANT_400 =+ PARTICIPANT_ID_400 ++ ' With send pacing on, also answered (without `retryAfterSeconds`) when the request names more new ' ++ "contacts than the whole day's cold-reachout allowance; split it into smaller batches.";+// EngineRegistry.require() answers 400 for a session with no engine; ENGINE_NOT_READY_409 covers only// an engine that exists but is not ready. The body variant is for routes that also validate a DTO.const BODY_OR_SESSION_400 = 'The body failed validation, or the session is not started (no engine is running for it).';@@ -194,7 +200,7 @@ export class GroupController {@ApiResponse({ status: 201, description: 'Group created', type: GroupSummaryDto })@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 403, description: ENGINE_REFUSED_403 })- @ApiResponse({ status: 400, description: PARTICIPANT_ID_400 })+ @ApiResponse({ status: 400, description: PACED_PARTICIPANT_400 })@ApiResponse({status: 503,description:@@ -225,7 +231,7 @@ export class GroupController {@ApiResponse({ status: 503, description: PARTICIPANTS_503 })@ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })@ApiResponse({ status: 403, description: ENGINE_REFUSED_403 })- @ApiResponse({ status: 400, description: PARTICIPANT_ID_400 })+ @ApiResponse({ status: 400, description: PACED_PARTICIPANT_400 })@HttpCode(HttpStatus.OK)@ApiResponse({ status: 404, description: GROUP_NOT_FOUND_404 })async addParticipants(