Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: describe the declined chat writes and the member label route

Yudhi Armyndharisfd60844d63ee
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 Lifecycle
diff --git a/docs/07-api-collection.md b/docs/07-api-collection.md
index 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`).
```bash
curl -X PUT "$BASE/api/sessions/$SESSION_ID/groups/[email protected]/member-label" \
diff --git a/openapi.json b/openapi.json
index 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.ts
index 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({