Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

Merge main into feat/improve-message-search

Yudhi Armyndharis2aab47732a0d
diff --cc CHANGELOG.md
index 678c38733,991e89208..da573d267
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -9,10 -9,11 +9,13 @@@ and this project adheres to [Semantic V
### Added
- - Add Number Checker page in dashboard for single and bulk WhatsApp recipient pre-validation.
+ - Add Number Checker page in dashboard for single and bulk WhatsApp recipient pre-validation, in every dashboard language.
- Add the opt-in `message.receipt` event for per-recipient group and status receipts on Baileys (#1748).
- - Add `match=contains` to `GET /api/search`: case- and accent-insensitive substring search on a trigram index (an FTS5 trigram table on SQLite, `pg_trgm` and `unaccent` on PostgreSQL). It ranks the 1,000 most recently stored matches by match quality in two bounded phases, so `total` is at most 1,000 in this mode; `match=word` stays the default. The SDKs accept `match`.
- - Add the `MessageSearch` MCP tool, which runs the global message search behind `GET /api/search` for agents, with `match=contains` by default.
+ - Record plugin install, update, uninstall, enable, disable and configuration changes in the audit log.
+ - Add `QUEUE_PREFIX` to set the Redis key prefix of the BullMQ queues, so deployments that share a Redis stop taking each other's webhook jobs.
+ - `QUEUE_PREFIX` does not separate the rate-limit store or the WebSocket fan-out.
++- Add `match=contains` to `GET /api/search`: 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. Thanks @luisffm.
### Changed
diff --cc docs/05-database-design.md
index 58b7dce56,4c2d10bf8..7e1a30607
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@@ -928,7 -930,8 +930,9 @@@ src/database/migrations/ # da
├── 1787200000000-DeduplicateTerminalWebhookFailures.ts # one terminal record per webhook and idempotency key
├── 1790812800000-AddMessageWindowIndexes.ts # compound timestamp indexes for message-time pagination
├── 1791100000000-AddIntegrationDeliveryFailureDeliveryIndex.ts # (pluginId, instanceId, deliveryId) index for the dead-letter guards
+ ├── 1791200000000-AddWebhookOutboxSessionIndex.ts # (sessionId) index for the per-session outbox delete
-└── 1791300000000-BackfillLegacyMessageTypes.ts # converts raw wwebjs message types to the neutral vocabulary, once
++├── 1791300000000-BackfillLegacyMessageTypes.ts # converts raw wwebjs message types to the neutral vocabulary, once
+└── 1792400000000-AddMessagesTrigramSearch.ts # match=contains indexes: FTS5 trigram (SQLite) / pg_trgm + unaccent GIN and (createdAt, id) b-tree (Postgres)
```
> [!NOTE]
diff --cc docs/06-api-specification.md
index 599a7c3f6,5d9356a6e..279a65265
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@@ -6512,19 -6512,18 +6512,19 @@@ Search messages across sessions (activ
**Query parameters**
-| Name | Type | Required | Default | Description |
-| ----------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, a symbol or emoji that stands apart counts as a word, a whitespace-separated word said again counts once). Passed to the active provider's native full-text matcher. |
-| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |
-| `chatId` | string | No | — | Restrict to a single chat id. A phone also matches the chat's other stored forms (the other user dialect and any lid that resolves to it). For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |
-| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |
-| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |
-| `from` | string | No | — | Filter by sender; matches `from` or a group message's `author`. A phone also matches any lid that resolves to it. |
-| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |
-| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |
-| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |
-| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |
+| Name | Type | Required | Default | Description |
+| ----------- | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, a symbol or emoji that stands apart counts as a word, a whitespace-separated word said again counts once). Passed to the active provider's native full-text matcher. |
+| `match` | enum (`word` \| `contains`) | No | `word` | `word` matches whole words. `contains` matches any part of a word, ignoring case and accents (`voic` finds "Invoice", `cafe` finds "Café"); every term must appear, at least one term needs 3+ characters (`400` otherwise), and `%`/`_` match literally. It ranks the 1,000 most recently stored matches by match quality (whole word, then word start, then inside a word; newest first within a score), so `total` is at most 1,000. On PostgreSQL it needs the `pg_trgm` and `unaccent` extensions (`501` otherwise). See [26 - Global Search](./26-global-search.md#match-modes). |
+| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |
- | `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |
++| `chatId` | string | No | — | Restrict to a single chat id. A phone also matches the chat's other stored forms (the other user dialect and any lid that resolves to it). For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |
+| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |
+| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |
- | `from` | string | No | — | Filter by sender. |
++| `from` | string | No | — | Filter by sender; matches `from` or a group message's `author`. A phone also matches any lid that resolves to it. |
+| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |
+| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |
+| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |
+| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |
**Response** `200` — `SearchResults`
diff --cc src/modules/search/search.controller.ts
index 115ffa762,b06087649..afe3328f6
--- a/src/modules/search/search.controller.ts
+++ b/src/modules/search/search.controller.ts
@@@ -52,19 -45,21 +52,29 @@@ export class SearchController
required: true,
description: 'Search term (required, non-empty, at most 1000 characters and 32 words)',
})
+ @ApiQuery({
+ name: 'match',
+ required: false,
+ enum: SEARCH_MATCH_MODES,
+ description:
+ 'word (default): whole words. contains: any part of a word, ignoring case and accents; ranks the ' +
+ `${SEARCH_CONTAINS_WINDOW} most recently stored matches by match quality`,
+ })
@ApiQuery({ name: 'sessionId', required: false, description: 'Restrict to a single session' })
- @ApiQuery({ name: 'chatId', required: false, description: 'Restrict to a single chat id' })
+ @ApiQuery({
+ name: 'chatId',
+ required: false,
+ description:
+ "Restrict to a single chat id. A phone also matches the chat's other stored forms (the other user dialect and any lid that resolves to it).",
+ })
@ApiQuery({ name: 'direction', required: false, description: 'incoming | outgoing' })
@ApiQuery({ name: 'type', required: false, description: 'Message type filter' })
- @ApiQuery({ name: 'from', required: false, description: 'Sender filter' })
+ @ApiQuery({
+ name: 'from',
+ required: false,
+ description:
+ "Sender filter. Matches `from` or a group message's `author`; a phone also matches any lid that resolves to it.",
+ })
@ApiQuery({ name: 'dateFrom', required: false, description: 'Epoch-ms lower bound (inclusive)' })
@ApiQuery({ name: 'dateTo', required: false, description: 'Epoch-ms upper bound (inclusive)' })
@ApiQuery({ name: 'limit', required: false, type: 'integer', description: 'Max hits to return' })