Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: describe the declined chat writes and the member label route
Yudhi Armyndharisfd60844d63ee
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2b9639d43..302374d4d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,8 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Add a session switcher to the dashboard Chats page that lists every session with its state, picture, push name and number, and lets only a ready one be selected. Thanks @rjsebening.- Add a contact info panel to the dashboard chat room with the contact's picture, name, number and copyable chat id. Thanks @rjsebening.- Add Today, Yesterday and date separators to the dashboard chat thread. Thanks @rjsebening.-- Add `match=contains` to `GET /api/search`, which needs `SEARCH_CONTAINS_ENABLED=true`: case- and accent-insensitive substring search on a trigram index (FTS5 on SQLite, `pg_trgm` and `unaccent` on PostgreSQL) that ranks the 1,000 most recently stored matches, so `total` is at most 1,000 in this mode; `match=word` stays the default and the SDKs accept `match`. Thanks @luisffm.-- Add the `MessageSearch` MCP tool, which runs the global message search for agents, with `match=contains` by default only when `SEARCH_CONTAINS_ENABLED=true`. Thanks @luisffm.+- Add `match=contains` to `GET /api/search`, which needs `SEARCH_CONTAINS_ENABLED=true`: case- and accent-insensitive substring search on a trigram index (FTS5 on SQLite, `pg_trgm` and `unaccent` on PostgreSQL) that ranks the 1,000 most recently stored matches, so `total` is at most 1,000 in this mode; `match=word` stays the default and the SDKs accept `match` (#1899). Thanks @luisffm.+- Add the `MessageSearch` MCP tool, which runs the global message search for agents, with `match=contains` by default only when `SEARCH_CONTAINS_ENABLED=true` (#1899). Thanks @luisffm.- Add `PUT /api/sessions/{sessionId}/groups/{groupId}/member-label` to set this account's member label in a group on Baileys; whatsapp-web.js answers `501` (#1918). Thanks @xwork1 for the report.### Changed@@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Index a Baileys clear, delete, archive or unread by the same chat jid as its message key, so the phone applies it (#1891). Thanks @rjsebening.- Key Baileys chat writes and read receipts to the gateway's newest stored message when the session holds none in memory (#1891). Thanks @rjsebening.+- Send a Baileys archive or mark unread without a range for a chat the session knows but holds no message for, where it answered `success: false` (#1891). Thanks @rjsebening.- Group dashboard phone numbers in threes and fours, so `+49 157 333 4 4455` now reads `+49 157 3334 4455`; 10-digit numbers keep their shape (#1940).- Answer `400` to a NUL character in `q` on `GET /api/search`, which failed with `500` on PostgreSQL.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex d2a20dfae..6b687c728 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -47,7 +47,7 @@ API keys carry one of three roles, ordered by privilege:A key may additionally be scoped to specific sessions (`allowedSessions`) and/or source IPs (`allowedIps`). The scope/IP check runs in the guard **before** any role check, so a request outside that scope is rejected with `403` even if the role would otherwise allow it. `401` is kept for a missing, unknown, revoked or expired key.-A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`), at most 2000 entries. An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. The chat-scoped routes are the message sends (text, template, image, video, audio, document, location, contact, sticker, poll, reply, click-button, forward, bulk and `send-product`), react, edit, delete, pin, unpin, star and vote-poll, and the history, reactions and media of one chat; the chat actions (read, unread, archive, mute, pin, delete, typing, clearing a chat's messages) and a chat's presence (subscribe and read); one contact's read, profile picture, phone lookup, update, delete, block and unblock routes; one group's detail, settings, subject, description, leave and picture routes; the label routes that address a chat; and the session's own detail (`GET /api/sessions/:sessionId`), which names no chat. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. The chat, group, contact and label-chat list routes (`GET /api/sessions/:sessionId/chats`, `/groups`, `/contacts` and `/labels/:labelId/chats`) return only the allowed entries, filtered before paging. `GET /api/search` with the built-in provider narrows its hits to the allowed chats before `limit`/`offset`/`total` apply, and an optional `?chatId=` must name an allowed chat. Plugin providers return `403` for these keys before the worker is invoked; set `SEARCH_PROVIDER=builtin-fts` to enable scoped search. `GET /api/sessions/:sessionId/groups/:groupId` and its `GET`/`PUT .../settings` admit a group inside the allowlist and answer `403` for any other. On `GET /api/sessions/:sessionId/messages` such a key must pass `?chatId=`; omitting it answers `403`. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The `/events` WebSocket admits chat-restricted keys and delivers only chat events inside their allowlist. MCP tools enforce the same chat fence, filter list results before paging, and refuse tools without chat-scoped authorization. The Bull Board queue dashboard still refuses chat-restricted keys with `403`.+A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`), at most 2000 entries. An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. The chat-scoped routes are the message sends (text, template, image, video, audio, document, location, contact, sticker, poll, reply, click-button, forward, bulk and `send-product`), react, edit, delete, pin, unpin, star and vote-poll, and the history, reactions and media of one chat; the chat actions (read, unread, archive, mute, pin, delete, typing, clearing a chat's messages) and a chat's presence (subscribe and read); one contact's read, profile picture, phone lookup, update, delete, block and unblock routes; one group's detail, settings, subject, description, member label, leave and picture routes; the label routes that address a chat; and the session's own detail (`GET /api/sessions/:sessionId`), which names no chat. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. The chat, group, contact and label-chat list routes (`GET /api/sessions/:sessionId/chats`, `/groups`, `/contacts` and `/labels/:labelId/chats`) return only the allowed entries, filtered before paging. `GET /api/search` with the built-in provider narrows its hits to the allowed chats before `limit`/`offset`/`total` apply, and an optional `?chatId=` must name an allowed chat. Plugin providers return `403` for these keys before the worker is invoked; set `SEARCH_PROVIDER=builtin-fts` to enable scoped search. `GET /api/sessions/:sessionId/groups/:groupId` and its `GET`/`PUT .../settings` admit a group inside the allowlist and answer `403` for any other. On `GET /api/sessions/:sessionId/messages` such a key must pass `?chatId=`; omitting it answers `403`. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The `/events` WebSocket admits chat-restricted keys and delivers only chat events inside their allowlist. MCP tools enforce the same chat fence, filter list results before paging, and refuse tools without chat-scoped authorization. The Bull Board queue dashboard still refuses chat-restricted keys with `403`.### API-Key Lifecyclediff --git a/docs/07-api-collection.md b/docs/07-api-collection.mdindex 3ce4a5f83..c14e91900 100644--- a/docs/07-api-collection.md+++ b/docs/07-api-collection.md@@ -802,7 +802,7 @@ curl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/descr#### PUT /api/sessions/:sessionId/groups/:groupId/member-label-Set this account's member label in the group, up to 30 characters; an empty string clears it (OPERATOR, Baileys only: whatsapp-web.js answers `501`).+Set this account's member label in the group, up to 30 UTF-16 code units (an emoji outside the Basic Multilingual Plane counts as two); an empty string clears it (OPERATOR, Baileys only: whatsapp-web.js answers `501`).```bashcurl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/member-label" \diff --git a/openapi.json b/openapi.jsonindex f31bc5b58..c1ad4eb07 100644--- a/openapi.json+++ b/openapi.json@@ -2526,7 +2526,7 @@},"responses": {"200": {- "description": "Chat marked as unread successfully",+ "description": "Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the mark to the chat's newest message in memory, else the newest stored one, else sends it without one for a chat the session knows; an id it knows no chat for answers `false`, and so does an archived chat with no known message, which the phone leaves unmarked without one.","content": {"application/json": {"schema": {@@ -3037,7 +3037,7 @@},"responses": {"200": {- "description": "Chat deleted successfully",+ "description": "Returns `{ success }`. `false` means the engine declined to act: an unknown chat, or on the Baileys engine a chat with no message in memory or stored, since the delete is keyed to its last message.","content": {"application/json": {"schema": {diff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.tsindex 0b921f849..00c097f47 100644--- a/src/modules/session/session.controller.ts+++ b/src/modules/session/session.controller.ts@@ -761,7 +761,15 @@ export class SessionController {@HttpCode(HttpStatus.OK)@ApiOperation({ summary: 'Mark a chat as unread' })@ApiParam({ name: 'sessionId', description: 'Session ID' })- @ApiResponse({ status: 200, description: 'Chat marked as unread successfully', type: SessionActionResponseDto })+ @ApiResponse({+ status: 200,+ description:+ 'Returns `{ success }`. `false` means the engine declined to act. The Baileys engine keys the mark ' ++ "to the chat's newest message in memory, else the newest stored one, else sends it without one for a " ++ 'chat the session knows; an id it knows no chat for answers `false`, and so does an archived chat ' ++ 'with no known message, which the phone leaves unmarked without one.',+ type: SessionActionResponseDto,+ })@ApiResponse({ status: 400, description: 'Session not ready' })@ApiResponse({ status: 404, description: 'Session not found' })@ApiResponse({@@ -931,7 +939,14 @@ export class SessionController {'media, search entries) and emits `message:deleted` for each. Changes made on the phone are not mirrored.',})@ApiParam({ name: 'sessionId', description: 'Session ID' })- @ApiResponse({ status: 200, description: 'Chat deleted successfully', type: SessionActionResponseDto })+ @ApiResponse({+ status: 200,+ description:+ 'Returns `{ success }`. `false` means the engine declined to act: an unknown chat, or on the ' ++ 'Baileys engine a chat with no message in memory or stored, since the delete is keyed to its ' ++ 'last message.',+ type: SessionActionResponseDto,+ })@ApiResponse({ status: 400, description: 'Session not ready' })@ApiResponse({ status: 404, description: 'Session not found' })@ApiResponse({