Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
Merge remote-tracking branch 'upstream/main' into feat/improve-message-search
Luis4d2119c408bb
diff --cc .github/workflows/ci.ymlindex 7bd144185,c94449b37..1907b73a4--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@@ -272,7 -273,7 +273,7 @@@ jobs# spec's own two-migrator race is in-file (Promise.all) and unaffected by runInBand. The# synchronize spec additionally CREATEs and DROPs a scratch database of its own, which is# only safe serialized.- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/modules/search/providers/builtin-fts.provider.contains.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/infra/infra-data.optional-tables.pg.spec.ts src/modules/message/message-selection-restore.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts src/modules/session/session-delete-claim.spec.ts src/engine/identity/lid-mapping-store.spec.ts++ run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/modules/search/providers/builtin-fts.provider.contains.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/infra/infra-data.optional-tables.pg.spec.ts src/modules/message/message-selection-restore.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts src/modules/session/session-delete-claim.spec.ts src/engine/identity/lid-mapping-store.spec.tsenv:TZ: Asia/JakartaDATABASE_TYPE: postgresdiff --cc .github/workflows/release.ymlindex 2cf7b5a7e,411067ae0..6add7d72b--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@@ -243,7 -243,7 +243,7 @@@ jobs# tree CI had passed minutes earlier). The lock spec's own two-migrator race is in-file# (Promise.all) and unaffected by runInBand. The synchronize spec additionally CREATEs and# DROPs a scratch database of its own, which is only safe serialized.- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/modules/search/providers/builtin-fts.provider.contains.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts- run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/infra/infra-data.optional-tables.pg.spec.ts src/modules/message/message-selection-restore.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts src/modules/session/session-delete-claim.spec.ts src/engine/identity/lid-mapping-store.spec.ts++ run: npx jest --runInBand src/database/migrations/__tests__/1782400000000-AddMessagesFts.pg.spec.ts src/modules/search/providers/builtin-fts.provider.contains.pg.spec.ts src/database/migrations/__tests__/pg-boot-migrations.pg.spec.ts src/modules/message/message-list-ordering.pg.spec.ts src/database/migrations/__tests__/pg-entity-synchronize.pg.spec.ts src/database/postgres-utc.pg.spec.ts src/modules/webhook/webhook-recovery.pg.spec.ts src/modules/message/idempotency/send-idempotency.service.pg.spec.ts src/modules/infra/infra-data.import.pg.spec.ts src/modules/infra/infra-data.optional-tables.pg.spec.ts src/modules/message/message-selection-restore.pg.spec.ts src/modules/session/session-content-lifetime.spec.ts src/modules/session/session-delete-claim.spec.ts src/engine/identity/lid-mapping-store.spec.tsenv:TZ: Asia/JakartaDATABASE_TYPE: postgresdiff --cc CHANGELOG.mdindex 0f0d966ad,c25c62e87..ab5f17000--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -7,13 -7,15 +7,20 @@@ and this project adheres to [Semantic V## [Unreleased]+### Added+- - 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).- - 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`, which needs `SEARCH_CONTAINS_ENABLED=true` (off by default; the route answers `501` otherwise): 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. It defaults to `match=contains` only with `SEARCH_CONTAINS_ENABLED=true`, and searches by word otherwise or while the contains index is not ready. Thanks @luisffm.+++ ## [0.26.0] - 2026-10-28++ ### Added++ - Report poll votes as a `poll.vote` webhook and WebSocket event on whatsapp-web.js: the poll, chat, voter, the option texts now selected (`[]` when the vote is cleared), the poll question when WhatsApp Web still holds the poll, and the time of the change in seconds and in milliseconds (`timestampMs`, which orders a voter's changes within one second); the JavaScript, Python, Go and Java SDKs list the event name from SDK 0.7.0 ([#1922](https://github.com/rmyndharis/OpenWA/pull/1922)). Thanks @laviniarochaprec.+ - Add Number Checker page in dashboard for single and bulk WhatsApp recipient pre-validation, in every dashboard language (#1865). Thanks @Purushotham-Prajapati-24.+ - Add the opt-in `message.receipt` event for per-recipient group and status receipts on Baileys, sent to the webhooks and `/events` subscribers that name it (#1748); the JavaScript, Python, Go and Java SDKs list the event name from SDK 0.7.0. Receipts are bounded per webhook: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, shared by a session's receipt webhooks, three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` events wait for each, and further receipts are dropped and counted in `openwa_webhook_delivery_failures_total`. Thanks @KGMA74, and @berodcdev for the request.+ - Record plugin install, update, uninstall, enable, disable, configuration and session activation 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 and ingress jobs; it covers the queues only, not the rate-limit store or the WebSocket fan-out, and a value that is not 1 to 64 letters, digits, dots, underscores or hyphens starting with a letter or digit fails the boot.- Add All, Unread, 1:1, Groups and Unknown quick filters to the dashboard chat list. Thanks @rjsebening.- Add a New chat panel to the dashboard Chats page that opens a chat with a saved contact or a number WhatsApp confirms, and on Baileys creates a group. Thanks @rjsebening.- Add chat and contact menus to the dashboard Chats page: pin, mute, archive, mark unread, save, rename and block a contact, leave a group, and clear or delete a chat on whatsapp-web.js only until #1891 is fixed. Thanks @rjsebening.diff --cc docs/05-database-design.mdindex 32b6ec505,662f4be99..fd722561a--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@@ -727,8 -730,12 +730,12 @@@ The data connection also owns- **`lid_mappings`** — LID↔phone-number identity mappings (`src/engine/identity/lid-mapping.entity.ts`).- **`chat_states`** (engine): per-session mute, archive and pin state of each Baileys chat (`src/engine/adapters/baileys-chat-state.entity.ts`), keyed `(sessionId, chatId)`. `chatId` is the person's phone JID (`<phone>@s.whatsapp.net`) whenever their lid resolves, so a state WhatsApp syncs under the lid and one set through the phone number land on the same row; it stays `<lid>@lid` while the lid is unresolved, and a row found under the lid later is folded onto the phone JID on the chat's next change (reads and the fold take each field from the newest row that observed it: `observed` lists the fields a row has seen, and null, on a row not written since the column was added, means the fields it holds a set value for; the next write that can read the row records the list). WhatsApp does not re-deliver that state, so it is kept in backups. A chat deleted on the phone or through the API loses its row, so a later message starts it clean.+ `lid_mappings.isReported` distinguishes engine mapping reports from cache-only display data. Phone/LID alias authorization, candidate expansion and list filters use only reported mappings. A conflicting cached phone revokes alias trust without replacing the stored phone, and a later actual report restores it. The migration conservatively marks older mixed-origin rows as display data; backups carry the flag, and older backups restore with alias access disabled until a new report arrives.+-Additionally, the `AddMessagesFts` migration creates the full-text-search structures over `messages` (a FTS5 virtual table on SQLite, a generated `body_ts` `tsvector` column plus GIN index on PostgreSQL) that back the `/search` endpoint.+Additionally, the `AddMessagesFts` migration creates the full-text-search structures over `messages` (a FTS5 virtual table on SQLite, a generated `body_ts` `tsvector` column plus GIN index on PostgreSQL) that back the `/search` endpoint. With `SEARCH_CONTAINS_ENABLED=true` (off by default) the search provider, not a migration, also builds the trigram index behind `/search?match=contains`: a `messages_trgm` FTS5 trigram table with its sync triggers on SQLite; the `pg_trgm` and `unaccent` extensions, an `openwa_unaccent(text)` function and the `idx_messages_body_trgm` GIN trigram index on PostgreSQL (see [26 - Global Search](./26-global-search.md#269-enabling-matchcontains)).+ On SQLite that index can stop matching `messages` after a table rebuild, and a search then returns other messages. The `RepairSqliteMessageFts` migration checks the index against the full message content once and rebuilds it on a mismatch. With `DATABASE_SYNCHRONIZE=true` the same check runs after the schema sync on every boot; it reads all stored text, and a failure of the check is logged without stopping the boot.+> [!NOTE]> **Tables that do _not_ exist.** Earlier drafts referenced `contacts`, `session_logs`, `webhook_logs`, `api_key_logs`, `webhook_idempotency`, and `ip_whitelist`. None of these are implemented. Contacts are read live from the engine; auditing is the single `audit_logs` table; webhook idempotency is not a persisted table; and per-key IP restrictions are stored inline on `api_keys."allowedIps"` (a `simple-array`), not in a separate `ip_whitelist` table.diff --cc docs/06-api-specification.mdindex 5a8071ab9,a7cb7b34b..daf166b0f--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@@ -6515,19 -6555,18 +6555,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. With the built-in provider, a phone also matches the chat's other stored forms (the other user dialect, 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 also 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; with the built-in provider, matches `from` or a group message's `author`, and a phone also matches any lid that resolves to it. |-| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. Must be between -9007199254740991 and 9007199254740991; a non-numeric or out-of-range value is rejected with `400`. |-| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. Must be between -9007199254740991 and 9007199254740991; a non-numeric or out-of-range 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, on PostgreSQL 3+ letters or digits in a row (`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. Opt-in on the built-in provider: `501` unless the server sets `SEARCH_CONTAINS_ENABLED=true` and has finished building the index (on PostgreSQL also the `pg_trgm` and `unaccent` extensions). PostgreSQL also folds letters such as `Ł`, `ß` and `Ø` that SQLite keeps. 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. 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. |++| `chatId` | string | No | — | Restrict to a single chat id. With the built-in provider, a phone also matches the chat's other stored forms (the other user dialect, 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 also 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`. |++| `from` | string | No | — | Filter by sender; with the built-in provider, matches `from` or a group message's `author`, and a phone also matches any lid that resolves to it. |++| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. Must be between -9007199254740991 and 9007199254740991; a non-numeric or out-of-range value is rejected with `400`. |++| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. Must be between -9007199254740991 and 9007199254740991; a non-numeric or out-of-range 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`@@@ -6557,18 -6596,18 +6597,22 @@@- `snippet` is a text excerpt with `<mark>`/`</mark>` highlight markers around the matched term (bothdialects emit the same markers). The body text inside it is not HTML-escaped: split on the literalmarkers and render each segment as text, never the raw snippet as HTML.+ - `timestamp` is Unix **seconds**, as in the message routes, while the `dateFrom`/`dateTo` bounds are+ epoch **milliseconds**.-- `total` is an exact count for pagination, computed lazily only when the returned page could be full.+- `total` is an exact count for pagination, computed lazily only when the returned page could be full. With+ `match=contains` it counts the ranked window, at most 1,000 matches.- `provider` names which backend answered (e.g. `builtin-fts`); it is the registered `SearchProvider`- id, so it changes when a plugin backend is selected via `SEARCH_PROVIDER`.+ id, so it changes when a plugin backend is selected via `SEARCH_PROVIDER`. A plugin provider+ receives `chatId` and `from` as the caller sent them, without the other stored forms the built-in+ provider matches.- `score` is optional and provider-specific (rank ordering is stable within a provider; cross-providerscores are not comparable). The built-in provider on SQLite leaves it out for a key restricted to- selected sessions or chats, since it is computed over the whole index.+ selected sessions or chats, since it is computed over the whole index. With `match=contains` it is+ the match quality on both dialects (3 per term found as a whole word, 2 at a word start, 1 inside a+ word) and every key gets it, since it reads only its own message.- **Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, an `offset` above `100000`, an unknown `match`, a-**Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, a `dateFrom`/`dateTo` beyond 9007199254740991 in either direction, an `offset` above `100000`, or a malformed++**Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, a `dateFrom`/`dateTo` beyond 9007199254740991 in either direction, an `offset` above `100000`, an unknown `match`, a+`match=contains` query with no term of 3 or more characters (on PostgreSQL, 3 letters or digits in a row), or a malformedSQLite FTS5 query (unbalanced quote/paren, bare operator) — Postgres's `websearch_to_tsquery` istolerant and has no equivalent · `401` missing/invalid `X-API-Key` · `403` key role below `OPERATOR`, or a chat-restricted keythat names a `chatId` outside its allowlist or uses a plugin provider ·diff --cc docs/14-migration-guide.mdindex 9057aa89b,f7a3b2d27..1e98d3a5b--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@@ -883,72 -886,71 +886,83 @@@ with `CREATE INDEX CONCURRENTLY IF NOTit. A concurrent build that fails leaves an INVALID index under that name, which the migration alsoskips: check `pg_index.indisvalid` and drop the invalid index before building it again.+> [!NOTE]+> **Enabling `match=contains`.** `SEARCH_CONTAINS_ENABLED=true` (off by default) makes `GET /api/search`+> and the `MessageSearch` MCP tool accept `match=contains`. No migration builds its index: the search+> provider does, only once the HTTP listener is up, so the build never keeps a pod from its startup probe.+> On SQLite it adds the `messages_trgm` trigram table, about three times the message text (289 MB and a+> 9.4 s backfill on a synthetic million messages), backfilled in batches that yield to the event loop.+> On PostgreSQL it creates the `pg_trgm` and `unaccent` extensions when the role may, and builds the+> `idx_messages_body_trgm` GIN index with `CREATE INDEX CONCURRENTLY`, so writes go on (76 MB on 300,000+> messages, next to 30 MB for the word index); one replica builds while the others wait. `match=contains`+> answers `501` until the index is ready. Turning the setting off later keeps the index and its upkeep;+> [26.9](./26-global-search.md#269-enabling-matchcontains) lists the statements that drop it.+### Known Upgrade Hazards- | Release | Change | Action |- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |- | `0.25.0` | Once teardown begins (SIGTERM, SIGINT, `POST /api/infra/restart`) every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included | Probe `/api/health/live` for liveness that survives teardown, and retry a `503` once the instance is up again |- | `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; on Helm upgrade with `--reset-then-reuse-values` (3.14 or later) or `-f values.yaml`, since plain `--reuse-values` keeps the 0.24.0 defaults; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |- | `0.25.0` | `400` instead of `201` or `200` for a phone number WhatsApp reports as unregistered (Baileys; `503` when the lookup gets no answer) and for `vote-poll` with no matching option text (whatsapp-web.js) | Handle `400` (`POLL_OPTION_NOT_FOUND` carries `validOptions`) and `503` on these routes; an empty `options` list still clears a vote |- | `0.25.0` | `400` for an `allowedChats` list over 2000 entries and for `GET /api/search` with `q` over 1000 characters or 32 words; on Baileys also for a sticker it converts to WebP with over 500 frames, and for an `image/svg+xml` sticker, profile picture or group picture | Shorten the list or the query; on Baileys keep an animated sticker to 500 frames and convert SVG to PNG or WebP before sending |- | `0.25.0` | On SQLite, `GET /api/search` leaves `score` out of the hits of a key restricted to sessions or chats, because it is computed over the whole index; the hits stay in relevance order | Read `hit.score` as optional |- | `0.25.0` | `PUT /api/infra/config` answers `400` for a database or Redis port outside 1-65535, a negative or fractional pool size and a local storage path the app cannot create or write | Fix the value in the request; it used to be stored and the next boot refused it |- | `0.25.0` | Boot fails on a `PORT` with surrounding whitespace and on a `WEBHOOK_SHUTDOWN_DRAIN_MS` that is not a non-negative integer (for example `30s`) | Remove the padding or the unit |- | `0.25.0` | New Baileys pairings show `Ubuntu` as the linked-device name | Set `BAILEYS_BROWSER_NAME=OpenWA` to keep the old name; linked sessions are unaffected |- | `0.25.0` | `backup.sh` and `restore.sh` exit with status 2 on an unparsable or unreadable `./.env` or `.env.generated`, read the default SQLite paths under `OPENWA_DATA_DIR`, and with `DATABASE_SSL=true` verify the PostgreSQL certificate as the app does | Fix the line or the permissions, or pass the key in the environment; trust a private CA through `NODE_EXTRA_CA_CERTS` or `PGSSLROOTCERT` |- | `0.25.0` | With `DATABASE_SSL=true` the PostgreSQL certificate is verified against `DATABASE_HOST` even when it is an IP address | Use the certificate's DNS name as the host or add the IP to its subject alternative names; `DATABASE_SSL_REJECT_UNAUTHORIZED=false` remains the escape hatch |- | `0.25.0` | The first boot builds three indexes on `messages` without `CONCURRENTLY` (about 240 MB per million messages; on PostgreSQL writes wait), and the startup probe of the Helm chart or of the docs/13 StatefulSet restarts a pod whose boot outlasts about 295 s | On a large table run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` |- | `0.25.0` | Rolling back to 0.24.0 strands webhook outbox rows in state `queued`, and the upgrade deletes duplicate terminal `webhook_delivery_failures` rows | Drain or accept the queued rows before a rollback; the deleted duplicates are not restored |- | `0.25.0` | A Baileys voice note goes out with flat waveform bars when no ffmpeg binary is found, and an `FFMPEG_PATH` wrapper script sees only `PATH`, the library paths, `HOME`, the temp directories, `LANG`, `LC_ALL` and `SystemRoot` of the gateway's environment | Use the official image, which ships ffmpeg, and export what a wrapper script needs inside the script |- | `0.24.0` | A live key refused by its `allowedIps` (including an undeterminable client IP) or its `allowedSessions` answers `403` instead of `401`; `401` now means only a missing, unknown, revoked or expired key | Handle `403` for these refusals: SDK callers catch the forbidden error (Go `ErrForbidden`) instead of the auth error |- | `0.24.0` | Every `POST /mcp` request needs a valid API key: `initialize` and `tools/list` without one answer `401`, a tool call with a missing or invalid key gets `401` instead of an `isError` result, and a key with `allowedIps` is refused with `403` on every request | Configure the API key in every MCP client, including one that only lists tools, and use a key without `allowedIps` for MCP |- | `0.24.0` | `GET /api/sessions/:sessionId/contacts/check/:number` and the MCP `ContactCheckNumber` tool require an OPERATOR key; a VIEWER key gets `403` | Give number-check integrations an OPERATOR key |- | `0.24.0` | Setting or clearing a session proxy, through `PATCH /api/sessions/:sessionId/proxy` or `proxyUrl` on `POST /api/sessions`, requires an unscoped ADMIN key; any other key gets `403`, and a create carrying `proxyUrl` is refused before the session exists | Use an ADMIN key for proxy changes; reading the proxy is unchanged |- | `0.24.0` | `DELETE /api/sessions/:sessionId/chats/:chatId/messages` and `POST /api/sessions/:sessionId/chats/delete` also remove the gateway's stored copies of the chat's messages (rows, inline and archived media, search entries) once the engine reports success | Export whatever must be kept from a chat's stored messages and media before clearing or deleting the chat |- | `0.24.0` | `main.sqlite` (API keys and audit log) runs its `migrations-main/` chain at every boot instead of defaulting to synchronize, adopting an older file in place; boot stops with a `MainSchemaMismatchError` when the ledger records a migration this release does not ship, or an entity column is still missing after the chain | Back up `main.sqlite` before upgrading. The refusal names the migration or column; [05 - Database Design, section 5.6](./05-database-design.md#56-migration-strategy) gives the recovery for each |- | `0.24.0` | The built-in storage runs `pgsty/silo` in place of the withdrawn `minio/minio` image; the compose `minio` service no longer starts without `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`, and a recreated dashboard built-in `openwa-minio` publishes no host ports | Recreate the container and set the credentials as the Storage Migration part of section 14.3 describes |- | `0.24.0` | `POST /api/sessions/:sessionId/messages/send-product` passes the `message:sending` plugin gate (type `product`, input `{ chatId, productId, body }`); a rewritten `chatId` is ignored | Branch on `source`/`type` before reading send-DTO fields; a veto now answers `400` |- | `0.24.0` | Typed SDK clients: batch cancel (JavaScript `cancelBatch`, Go `CancelBatch`, Java `cancelBatch`, Python `cancel_batch`) returns `BatchCancelResponse` (`batchId`, `status`, `progress`) instead of `BatchStatusResponse`, whose `results` and timestamps the route never sent | TypeScript, Go and Java: change the declared result type to `BatchCancelResponse`. Typed Python: update annotations. Read per-recipient results from `batchStatus` / `BatchStatus` / `batch_status`. PHP needs no change; the wire response is unchanged |- | `0.23.6` | A media URL passed to a send route or to `POST /media/convert/voice` or `.../convert/video`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts |- | `0.23.0` | Typed SDK clients: `markRead` and `subscribePresence` each take their own request type instead of the shared `MarkChatRequest`, which now serves `markUnread` alone | Go and Java: swap the type at both call sites. Typed Python: only at `markRead`, its `subscribePresence` body being structurally identical. JavaScript and PHP need no change; the wire body is unchanged |- | `0.22.0` | Baileys refuses a reply whose quoted id, or a forward whose `fromChatId`, does not name the addressed chat, with the `404` whatsapp-web.js already answered; leaving a group, unsubscribing from a channel and labelling a channel surface WhatsApp's refusal; membership requests for an id that is not a group are refused | Handle a refusal on those six calls, which previously answered `200` whatever happened |- | `0.22.0` | Typed SDK clients narrow their request bodies: 19 Python request types mark the fields the server requires, and Go and Java type the proxy scheme, call kind, membership method, chat state, pin window and status font as enums | Pass the named constants instead of bare strings or numbers and supply every required field; untyped callers are unaffected |- | `0.22.0` | `isReadOnly` on a group answers for the calling account rather than repeating the group setting, and `isMyContact` reflects whether the contact is actually saved | Re-read either field wherever logic branched on the old value |- | `0.22.0` | Images 0.19.0 to 0.21.x ship `scripts/backup.sh` but no PostgreSQL client, so with `DATABASE_TYPE=postgres` step 1 of the upgrade script fails (`pg_dump is not installed`) before anything is stopped, and writes no archive at all | Dump the data store while the database still runs: `docker exec openwa-postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backups/database.sql` for the built-in service, or `pg_dump` from the host against `DATABASE_HOST` for an external server. Then stop the app and archive the volume as the `0.19.0` row below does. To roll back, extract that archive into the emptied volume and load `database.sql` as 11 - Runbook: Restore from Backup, step 3 shows |- | `0.21.0` | The ingress route gained a per-client-IP rate bound (`INGRESS_IP_LIMIT`, default 1200 per window) alongside its per-instance one; previously the route had no bound a caller could not walk around by varying the path | Raise `INGRESS_IP_LIMIT` if one provider IP legitimately drives more than 1200 ingress requests per window |- | `0.20.0` | With `WEBHOOK_SSRF_PROTECT=false`, deliveries no longer follow redirects, and `SSRF_ALLOWED_HOSTS` entries pin to their resolved addresses (must resolve at registration) | Set `WEBHOOK_SSRF_REDIRECTS=true` for a receiver legitimately behind a 3xx; ensure allowlisted hostnames resolve when the webhook is saved |- | `0.20.0` | Plugin installs from a URL require a `#sha256=<64 hex>` pin under `NODE_ENV=production` (the compose default) | Pin catalog URLs, or set `PLUGIN_INSTALL_REQUIRE_PIN=false` to lift the requirement |- | `0.19.0` | Older images ship no `scripts/backup.sh`, so step 1 of the upgrade script fails on a 0.18.x or earlier container, before anything is stopped | Stop the app and archive the volume: `docker run --rm -v openwa_openwa-data:/data:ro -v "$PWD/backups:/o" alpine tar czf /o/data.tgz -C /data .`, with a `pg_dump` of a PostgreSQL data store. To roll back, extract it into the emptied volume |- | `0.19.0` | Production boot refuses a set `API_MASTER_KEY` shorter than 32 characters | Strengthen a short key before upgrading; unset stays allowed (first boot generates one) |- | `0.19.0` | `POST /sessions/:id/messages/send-catalog` and `PUT /api/settings` are removed (both always answered `501`) | Drop calls to either; catalog reads and `GET /api/settings` are unchanged |- | `0.18.0` | `NODE_ENV` outside `production`/`development`/`test` fails boot with a named error | Set a legal value or unset it (unset remains valid) |- | `0.18.0` | Go SDK: `UpdateWebhookRequest.Secret`/`.Headers` and `UpdateTemplateRequest.Header`/`.Footer` become pointers, plus a `ClearFilters` flag | Take the address of a variable to send a clearing value, or leave nil to keep the stored one |- | `0.18.0` | Two enabled instances of one plugin sharing a session scope no longer collapse onto a single config | Move shared keys onto each instance when provisioning a second one on the same session |- | `0.17.0` | `AUDIT_RETENTION_DAYS` is validated at boot as a plain integer | Replace `30d`-style values with plain integers (`0`/negatives keep their documented meaning) |- | `0.17.0` | Plugins must declare a `storage:use` permission to reach `ctx.storage` | Upgrade the official plugins to the floors listed in the 0.17.0 changelog BEFORE upgrading the gateway |- | `0.16.0` | `POST /sessions/:id/groups` answers `501` on the whatsapp-web.js engine (the page code it used no longer exists) | Create groups through the Baileys engine |- | `0.15.0` | Engine calls during a WhatsApp Web page reload answer a retryable `409` naming the reload (previously `500`, or `200 {success:false}` on six chat-write routes); typed 4xx no longer latch the send breaker | Retry the named-reload `409` after the session re-emits `ready` |- | `0.14.6` | `POST /groups` returns the summary shape (`participantsCount`, not the detail type), and three SDK response shapes were retyped (`ParticipantsResult`, `ContactRecord.pushName`/fields, `sendProduct` → `{id}`) | Adjust typed SDK reads; untyped JSON consumers are unaffected |- | `0.14.5` | Baileys transport failures (dead socket) propagate as 5xx instead of misclassified `403`/`400`/`404` | Treat 5xx as retryable transport failure; keep 4xx handling for genuine refusals |- | `0.14.0` | Eager status backfill on session ready is opt-in (`STATUS_SEED_ON_READY`, default off) | Set the flag only after validating the account; live status events are unaffected |- | `0.14.0` | Link previews are opt-in on the Baileys engine | Pass `linkPreview: true` or a `customLinkPreview` where a card is wanted |- | `0.12.0` | `PUT /api/plugins/:id/sessions` is a full replacement of the global activation set and now requires an **unrestricted ADMIN** key; a session-scoped key is rejected with `403` whatever it sends | Switch any automation that drives global plugin activation from a scoped key to an unrestricted ADMIN key. The per-session config override route `PUT /api/plugins/:id/config/:sessionId` is unaffected and stays scoped to the addressed session |- | `0.8.15` | PostgreSQL schemas bootstrapped with `DATABASE_SYNCHRONIZE=true` crash-loop on boot | Self-healing guard migration; see [14.9](#149-troubleshooting-migration-issues) for the large-table window |- | `0.9.0` | `GET /api/settings` no longer returns the always-zero `general.sessionTimeout` | Remove reads of that field; there is no replacement |- | `0.10.3` | Boolean/numeric request fields are parsed strictly (`1`, `yes`, `""` now `400`) | Send canonical JSON values; JSON clients and the SDKs are unaffected |- | `0.10.3` | Status posts pass the `message:sending` plugin gate, with no `chatId` in the input | Branch on `source`/`type` before reading `input.chatId` |+ | Release | Change | Action |+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+ | `0.26.0` | Existing and older-backup LID mappings become display data; phone/LID aliases stay disabled until an actual engine mapping report. Cache-only lookup results cannot authorize an alias. Baileys preserves LIDs in message and listing identities instead of deriving them from cached phone numbers | Upgrade every reader together: older versions do not enforce the origin flag. Exact-ID grants remain available. Back up before downgrade; reversing this migration clears unreported display phone mappings so an older reader cannot authorize them |+ | `0.26.0` | The first boot rewrites every legacy `messages.type` value in one `UPDATE`, inside the transaction of the other pending migrations: on PostgreSQL about a minute per million legacy rows, with the port closed. Only a database whose conversion kept being cancelled on `0.25.0` still holds a large backlog | Count them with `SELECT count(*) FROM messages WHERE type IN ('chat', 'buttons_response', 'list_response', 'template_button_reply', 'ptt', 'vcard', 'multi_vcard')`; above a few million, run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` to cover about a minute per million legacy rows (measured with twelve indexes on the table) on top of the index builds |+ | `0.26.0` | A production boot refuses a `METRICS_TOKEN` that is the `.env.example` placeholder or a weak value the other secrets are checked against (`test`, `change-me`, `changeme`, `password`, `secret`, `admin`, `demo` and a few more), trimmed and case-insensitive | Set a long random token, or unset `METRICS_TOKEN` to keep `/api/metrics` disabled (it answers `404`); there is no length floor, so a short value that is not on the list still boots |+ | `0.26.0` | Session deletion commits bounded batches (at most 2000 message rows on SQLite or 500 on PostgreSQL) before the final transaction. Current local fixtures took 23.2 s for 299,102 messages on SQLite and 11.9 s for 1,000,007 on PostgreSQL, each with about 2,000 outbox rows and 500 delivery failures. These are examples, not limits or comparisons with `0.25.0`; large outbox and failure histories can add substantially more time. Earlier batches remain committed after a later failure | Set client and proxy timeouts for the session size. Repeat DELETE to finish, or explicitly `POST /start` to keep the remaining session. Without a newer owner or explicit start, a failure after removal begins keeps the session stopped |+ | `0.26.0` | `restore.sh` stops before it copies anything, naming the key, when a path from the archive's own `.env.generated` leads out of the data directory, or into a directory the restore refills | Set that key in the environment or `./.env` to restore there; the default paths and a leftover `./uploads` restore as before |+ | `0.26.0` | A boot with `REDIS_TLS=true`, or a `REDIS_USERNAME` other than `default`, beside the built-in Redis (`REDIS_BUILTIN=true` with the bundled host) is refused, and so is an Infrastructure page save that would produce it; the container serves plain TCP and only its default user | Set `REDIS_TLS=false` and clear `REDIS_USERNAME` for the built-in Redis, or switch to an external Redis host with `REDIS_BUILTIN=false` |+ | `0.26.0` | `POST .../groups/:groupId/membership-requests/approve` and `/reject` answer `400` for a body that is a JSON list or is sent in a content type other than `application/json` or `application/x-www-form-urlencoded`; both used to act on every pending request | Send `{}` or no body to act on every pending request, and name requesters in a JSON or form body |+ | `0.26.0` | On whatsapp-web.js, `POST /api/sessions/:sessionId/pairing-code` answers `409` for a number that is the stored phone of another session of the gateway | Log that session out or delete it first, or link by QR |+ | `0.26.0` | On SQLite the first boot checks the full-text index against all stored message text and rebuilds it when they differ, so the boot takes longer on a large database while the port is closed | Allow for it in the startup probe; later boots skip the check unless `DATABASE_SYNCHRONIZE=true` |+ | `0.26.0` | The idempotency key of recurring webhook events (`message.edited`, `message.reaction`, `session.*`, `group.*`, `presence.update`) ends in a random id minted per dispatch instead of an ISO timestamp | Dedupe on the whole key; a receiver that reads its last segment as a time must stop |+ | `0.26.0` | A `conversationId` JSON pointer of an ingress route is read by RFC 6901 tokens: a trailing or doubled slash names an empty key, which the old reader skipped | Remove a stray slash from such a pointer; a delivery it no longer resolves falls back to the per-instance lane |+ | `0.25.0` | Once teardown begins (SIGTERM, SIGINT, `POST /api/infra/restart`) every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included | Probe `/api/health/live` for liveness that survives teardown, and retry a `503` once the instance is up again |+ | `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; on Helm upgrade with `--reset-then-reuse-values` (3.14 or later) or `-f values.yaml`, since plain `--reuse-values` keeps the 0.24.0 defaults; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |+ | `0.25.0` | `400` instead of `201` or `200` for a phone number WhatsApp reports as unregistered (Baileys; `503` when the lookup gets no answer) and for `vote-poll` with no matching option text (whatsapp-web.js) | Handle `400` (`POLL_OPTION_NOT_FOUND` carries `validOptions`) and `503` on these routes; an empty `options` list still clears a vote |+ | `0.25.0` | `400` for an `allowedChats` list over 2000 entries and for `GET /api/search` with `q` over 1000 characters or 32 words; on Baileys also for a sticker it converts to WebP with over 500 frames, and for an `image/svg+xml` sticker, profile picture or group picture | Shorten the list or the query; on Baileys keep an animated sticker to 500 frames and convert SVG to PNG or WebP before sending |+ | `0.25.0` | On SQLite, `GET /api/search` leaves `score` out of the hits of a key restricted to sessions or chats, because it is computed over the whole index; the hits stay in relevance order | Read `hit.score` as optional |+ | `0.25.0` | `PUT /api/infra/config` answers `400` for a database or Redis port outside 1-65535, a negative or fractional pool size and a local storage path the app cannot create or write | Fix the value in the request; it used to be stored and the next boot refused it |+ | `0.25.0` | Boot fails on a `PORT` with surrounding whitespace and on a `WEBHOOK_SHUTDOWN_DRAIN_MS` that is not a non-negative integer (for example `30s`) | Remove the padding or the unit |+ | `0.25.0` | New Baileys pairings show `Ubuntu` as the linked-device name | Set `BAILEYS_BROWSER_NAME=OpenWA` to keep the old name; linked sessions are unaffected |+ | `0.25.0` | `backup.sh` and `restore.sh` exit with status 2 on an unparsable or unreadable `./.env` or `.env.generated`, read the default SQLite paths under `OPENWA_DATA_DIR`, and with `DATABASE_SSL=true` verify the PostgreSQL certificate as the app does | Fix the line or the permissions, or pass the key in the environment; trust a private CA through `NODE_EXTRA_CA_CERTS` or `PGSSLROOTCERT` |+ | `0.25.0` | With `DATABASE_SSL=true` the PostgreSQL certificate is verified against `DATABASE_HOST` even when it is an IP address | Use the certificate's DNS name as the host or add the IP to its subject alternative names; `DATABASE_SSL_REJECT_UNAUTHORIZED=false` remains the escape hatch |+ | `0.25.0` | The first boot builds three indexes on `messages` without `CONCURRENTLY` (about 240 MB per million messages; on PostgreSQL writes wait), and the startup probe of the Helm chart or of the docs/13 StatefulSet restarts a pod whose boot outlasts about 295 s | On a large table run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` |+ | `0.25.0` | Rolling back to 0.24.0 strands webhook outbox rows in state `queued`, and the upgrade deletes duplicate terminal `webhook_delivery_failures` rows | Drain or accept the queued rows before a rollback; the deleted duplicates are not restored |+ | `0.25.0` | A Baileys voice note goes out with flat waveform bars when no ffmpeg binary is found, and an `FFMPEG_PATH` wrapper script sees only `PATH`, the library paths, `HOME`, the temp directories, `LANG`, `LC_ALL` and `SystemRoot` of the gateway's environment | Use the official image, which ships ffmpeg, and export what a wrapper script needs inside the script |+ | `0.24.0` | A live key refused by its `allowedIps` (including an undeterminable client IP) or its `allowedSessions` answers `403` instead of `401`; `401` now means only a missing, unknown, revoked or expired key | Handle `403` for these refusals: SDK callers catch the forbidden error (Go `ErrForbidden`) instead of the auth error |+ | `0.24.0` | Every `POST /mcp` request needs a valid API key: `initialize` and `tools/list` without one answer `401`, a tool call with a missing or invalid key gets `401` instead of an `isError` result, and a key with `allowedIps` is refused with `403` on every request | Configure the API key in every MCP client, including one that only lists tools, and use a key without `allowedIps` for MCP |+ | `0.24.0` | `GET /api/sessions/:sessionId/contacts/check/:number` and the MCP `ContactCheckNumber` tool require an OPERATOR key; a VIEWER key gets `403` | Give number-check integrations an OPERATOR key |+ | `0.24.0` | Setting or clearing a session proxy, through `PATCH /api/sessions/:sessionId/proxy` or `proxyUrl` on `POST /api/sessions`, requires an unscoped ADMIN key; any other key gets `403`, and a create carrying `proxyUrl` is refused before the session exists | Use an ADMIN key for proxy changes; reading the proxy is unchanged |+ | `0.24.0` | `DELETE /api/sessions/:sessionId/chats/:chatId/messages` and `POST /api/sessions/:sessionId/chats/delete` also remove the gateway's stored copies of the chat's messages (rows, inline and archived media, search entries) once the engine reports success | Export whatever must be kept from a chat's stored messages and media before clearing or deleting the chat |+ | `0.24.0` | `main.sqlite` (API keys and audit log) runs its `migrations-main/` chain at every boot instead of defaulting to synchronize, adopting an older file in place; boot stops with a `MainSchemaMismatchError` when the ledger records a migration this release does not ship, or an entity column is still missing after the chain | Back up `main.sqlite` before upgrading. The refusal names the migration or column; [05 - Database Design, section 5.6](./05-database-design.md#56-migration-strategy) gives the recovery for each |+ | `0.24.0` | The built-in storage runs `pgsty/silo` in place of the withdrawn `minio/minio` image; the compose `minio` service no longer starts without `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`, and a recreated dashboard built-in `openwa-minio` publishes no host ports | Recreate the container and set the credentials as the Storage Migration part of section 14.3 describes |+ | `0.24.0` | `POST /api/sessions/:sessionId/messages/send-product` passes the `message:sending` plugin gate (type `product`, input `{ chatId, productId, body }`); a rewritten `chatId` is ignored | Branch on `source`/`type` before reading send-DTO fields; a veto now answers `400` |+ | `0.24.0` | Typed SDK clients: batch cancel (JavaScript `cancelBatch`, Go `CancelBatch`, Java `cancelBatch`, Python `cancel_batch`) returns `BatchCancelResponse` (`batchId`, `status`, `progress`) instead of `BatchStatusResponse`, whose `results` and timestamps the route never sent | TypeScript, Go and Java: change the declared result type to `BatchCancelResponse`. Typed Python: update annotations. Read per-recipient results from `batchStatus` / `BatchStatus` / `batch_status`. PHP needs no change; the wire response is unchanged |+ | `0.23.6` | A media URL passed to a send route or to `POST /media/convert/voice` or `.../convert/video`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts |+ | `0.23.0` | Typed SDK clients: `markRead` and `subscribePresence` each take their own request type instead of the shared `MarkChatRequest`, which now serves `markUnread` alone | Go and Java: swap the type at both call sites. Typed Python: only at `markRead`, its `subscribePresence` body being structurally identical. JavaScript and PHP need no change; the wire body is unchanged |+ | `0.22.0` | Baileys refuses a reply whose quoted id, or a forward whose `fromChatId`, does not name the addressed chat, with the `404` whatsapp-web.js already answered; leaving a group, unsubscribing from a channel and labelling a channel surface WhatsApp's refusal; membership requests for an id that is not a group are refused | Handle a refusal on those six calls, which previously answered `200` whatever happened |+ | `0.22.0` | Typed SDK clients narrow their request bodies: 19 Python request types mark the fields the server requires, and Go and Java type the proxy scheme, call kind, membership method, chat state, pin window and status font as enums | Pass the named constants instead of bare strings or numbers and supply every required field; untyped callers are unaffected |+ | `0.22.0` | `isReadOnly` on a group answers for the calling account rather than repeating the group setting, and `isMyContact` reflects whether the contact is actually saved | Re-read either field wherever logic branched on the old value |+ | `0.22.0` | Images 0.19.0 to 0.21.x ship `scripts/backup.sh` but no PostgreSQL client, so with `DATABASE_TYPE=postgres` step 1 of the upgrade script fails (`pg_dump is not installed`) before anything is stopped, and writes no archive at all | Dump the data store while the database still runs: `docker exec openwa-postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backups/database.sql` for the built-in service, or `pg_dump` from the host against `DATABASE_HOST` for an external server. Then stop the app and archive the volume as the `0.19.0` row below does. To roll back, extract that archive into the emptied volume and load `database.sql` as 11 - Runbook: Restore from Backup, step 3 shows |+ | `0.21.0` | The ingress route gained a per-client-IP rate bound (`INGRESS_IP_LIMIT`, default 1200 per window) alongside its per-instance one; previously the route had no bound a caller could not walk around by varying the path | Raise `INGRESS_IP_LIMIT` if one provider IP legitimately drives more than 1200 ingress requests per window |+ | `0.20.0` | With `WEBHOOK_SSRF_PROTECT=false`, deliveries no longer follow redirects, and `SSRF_ALLOWED_HOSTS` entries pin to their resolved addresses (must resolve at registration) | Set `WEBHOOK_SSRF_REDIRECTS=true` for a receiver legitimately behind a 3xx; ensure allowlisted hostnames resolve when the webhook is saved |+ | `0.20.0` | Plugin installs from a URL require a `#sha256=<64 hex>` pin under `NODE_ENV=production` (the compose default) | Pin catalog URLs, or set `PLUGIN_INSTALL_REQUIRE_PIN=false` to lift the requirement |+ | `0.19.0` | Older images ship no `scripts/backup.sh`, so step 1 of the upgrade script fails on a 0.18.x or earlier container, before anything is stopped | Stop the app and archive the volume: `docker run --rm -v openwa_openwa-data:/data:ro -v "$PWD/backups:/o" alpine tar czf /o/data.tgz -C /data .`, with a `pg_dump` of a PostgreSQL data store. To roll back, extract it into the emptied volume |+ | `0.19.0` | Production boot refuses a set `API_MASTER_KEY` shorter than 32 characters | Strengthen a short key before upgrading; unset stays allowed (first boot generates one) |+ | `0.19.0` | `POST /sessions/:id/messages/send-catalog` and `PUT /api/settings` are removed (both always answered `501`) | Drop calls to either; catalog reads and `GET /api/settings` are unchanged |+ | `0.18.0` | `NODE_ENV` outside `production`/`development`/`test` fails boot with a named error | Set a legal value or unset it (unset remains valid) |+ | `0.18.0` | Go SDK: `UpdateWebhookRequest.Secret`/`.Headers` and `UpdateTemplateRequest.Header`/`.Footer` become pointers, plus a `ClearFilters` flag | Take the address of a variable to send a clearing value, or leave nil to keep the stored one |+ | `0.18.0` | Two enabled instances of one plugin sharing a session scope no longer collapse onto a single config | Move shared keys onto each instance when provisioning a second one on the same session |+ | `0.17.0` | `AUDIT_RETENTION_DAYS` is validated at boot as a plain integer | Replace `30d`-style values with plain integers (`0`/negatives keep their documented meaning) |+ | `0.17.0` | Plugins must declare a `storage:use` permission to reach `ctx.storage` | Upgrade the official plugins to the floors listed in the 0.17.0 changelog BEFORE upgrading the gateway |+ | `0.16.0` | `POST /sessions/:id/groups` answers `501` on the whatsapp-web.js engine (the page code it used no longer exists) | Create groups through the Baileys engine |+ | `0.15.0` | Engine calls during a WhatsApp Web page reload answer a retryable `409` naming the reload (previously `500`, or `200 {success:false}` on six chat-write routes); typed 4xx no longer latch the send breaker | Retry the named-reload `409` after the session re-emits `ready` |+ | `0.14.6` | `POST /groups` returns the summary shape (`participantsCount`, not the detail type), and three SDK response shapes were retyped (`ParticipantsResult`, `ContactRecord.pushName`/fields, `sendProduct` → `{id}`) | Adjust typed SDK reads; untyped JSON consumers are unaffected |+ | `0.14.5` | Baileys transport failures (dead socket) propagate as 5xx instead of misclassified `403`/`400`/`404` | Treat 5xx as retryable transport failure; keep 4xx handling for genuine refusals |+ | `0.14.0` | Eager status backfill on session ready is opt-in (`STATUS_SEED_ON_READY`, default off) | Set the flag only after validating the account; live status events are unaffected |+ | `0.14.0` | Link previews are opt-in on the Baileys engine | Pass `linkPreview: true` or a `customLinkPreview` where a card is wanted |+ | `0.12.0` | `PUT /api/plugins/:id/sessions` is a full replacement of the global activation set and now requires an **unrestricted ADMIN** key; a session-scoped key is rejected with `403` whatever it sends | Switch any automation that drives global plugin activation from a scoped key to an unrestricted ADMIN key. The per-session config override route `PUT /api/plugins/:id/config/:sessionId` is unaffected and stays scoped to the addressed session |+ | `0.8.15` | PostgreSQL schemas bootstrapped with `DATABASE_SYNCHRONIZE=true` crash-loop on boot | Self-healing guard migration; see [14.9](#149-troubleshooting-migration-issues) for the large-table window |+ | `0.9.0` | `GET /api/settings` no longer returns the always-zero `general.sessionTimeout` | Remove reads of that field; there is no replacement |+ | `0.10.3` | Boolean/numeric request fields are parsed strictly (`1`, `yes`, `""` now `400`) | Send canonical JSON values; JSON clients and the SDKs are unaffected |+ | `0.10.3` | Status posts pass the `message:sending` plugin gate, with no `chatId` in the input | Branch on `source`/`type` before reading `input.chatId` |The authoritative list is `CHANGELOG.md`; breaking items are flagged there with ⚠️ **Breaking**.diff --cc docs/26-global-search.mdindex d57e8f8a2,b8dad933e..eaca1ead0--- a/docs/26-global-search.md+++ b/docs/26-global-search.md@@@ -282,46 -213,8 +283,48 @@@ Adding search to an existing deploymenThe migration is safe to re-run (idempotent guards) and has a `down` path that drops the FTS schema onboth dialects. After it applies, search works immediately — no separate reindex command.+ On SQLite the `1791600000000-RepairSqliteMessageFts` migration then compares the index with the full message content and rebuilds it when they differ, which a table rebuild (a schema sync, for one) can cause. A healthy index is left alone. With `DATABASE_SYNCHRONIZE=true` the same check runs after the schema sync on every boot; it reads all stored text, and a failed check is logged and does not stop the boot.++## 26.9 Enabling `match=contains`++`SEARCH_CONTAINS_ENABLED=true` is the only switch: no migration creates the trigram index, because every+installation would pay for it while only `match=contains` callers (the REST route and the `MessageSearch`+MCP tool; the dashboard searches by word) use it. The built-in provider builds it instead, starting only+once the HTTP listener is up and without holding the boot, so a long build cannot keep the process from+answering its health probe (a boot that outlasts the Helm startup probe is restarted in a loop, see+[14 - Migration Guide](./14-migration-guide.md)). Until the build finishes, `match=contains` answers `501`.++- **SQLite** creates the `messages_trgm` FTS5 trigram table and its three sync triggers, then backfills+ the existing rows 1,000 rowids at a time, yielding to the event loop between batches; rows stored+ meanwhile are indexed by the triggers. A trigram index holds every three-character window of the body:+ on a synthetic corpus of 1,000,000 messages it took 289 MB, about 3.1 times the message text, and a+ 9.4 s backfill. Later boots only check it and re-add what is missing, so an interrupted backfill+ resumes where it stopped.+- **PostgreSQL** creates the `pg_trgm` and `unaccent` extensions when they are missing and the role may,+ the IMMUTABLE `openwa_unaccent(text)` wrapper, and the `idx_messages_body_trgm` GIN index on+ `openwa_unaccent(body)` with `CREATE INDEX CONCURRENTLY`, so writes go on during the build (it cannot+ run inside a migration's transaction). On 300,000 messages the index took 76 MB, next to 30 MB for the+ word index. The build runs on its own connection without the runtime `statement_timeout`. Replicas+ that start together take a session advisory lock: one builds, the others answer `501` until the+ index is valid. A build that died (a killed pod) leaves an INVALID index, which the next build drops+ and rebuilds. The candidate query walks the existing `IDX_messages_createdAt` index, so contains search+ adds no other index.++**Turning it off** later stops `match=contains` (`501` again) but keeps the index, and with it the cost+on every write, so turning it back on needs no rebuild. To reclaim the space, drop it by hand:++```sql+-- SQLite+DROP TRIGGER IF EXISTS messages_trgm_ai;+DROP TRIGGER IF EXISTS messages_trgm_ad;+DROP TRIGGER IF EXISTS messages_trgm_au;+DROP TABLE IF EXISTS messages_trgm;++-- PostgreSQL (the extensions stay: other objects may use them)+DROP INDEX CONCURRENTLY IF EXISTS idx_messages_body_trgm;+DROP FUNCTION IF EXISTS openwa_unaccent(text);+```+---> See also: [06 - API Specification](./06-api-specification.md) (§6.4.12 Search),diff --cc sdk/go/types_search.goindex 83a70dd44,9c5762f3c..a01c05ca9--- a/sdk/go/types_search.go+++ b/sdk/go/types_search.go@@@ -3,12 -3,11 +3,14 @@@ package openwimport "net/url"// SearchQuery is the query for GET /search. Q is required; all else optional.- // DateFrom/DateTo are epoch-ms. Match is "word" (the server default: whole- // words) or "contains" (any part of a word, ignoring case and accents; needs a- // term of 3+ characters, and a server with SEARCH_CONTAINS_ENABLED=true, else 501).+ // DateFrom/DateTo are epoch-ms. Q holds at most 1000 characters and 32 words (the server answers 400+ // above either). Limit defaults to 50 and is capped at the server's SEARCH_LIMIT_MAX (100 by default);-// Offset is at most 100000 (400 above).++// Offset is at most 100000 (400 above). Match is "word" (the server default: whole words) or "contains"++// (any part of a word, ignoring case and accents; needs a term of 3+ characters, and a server with++// SEARCH_CONTAINS_ENABLED=true, else 501).type SearchQuery struct {Q string+ Match *stringSessionID *stringChatID *stringDirection *stringdiff --cc sdk/javascript/src/types.tsindex edaac5930,ec49c26bc..abde72013--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@@ -1430,19 -1451,13 +1451,22 @@@ export interface SendProductRequest// ── Search ────────────────────────────────────────────────────────+/**+ * How `q` matches: `word` (the server default) matches whole words; `contains` matches any part of a+ * word, ignoring case and accents, and needs at least one term of 3+ characters and a server with+ * `SEARCH_CONTAINS_ENABLED=true` (501 otherwise).+ */+export type SearchMatch = 'word' | 'contains';+/** Query parameters for `GET /search`. Only `q` is required; all filters are optional. */export interface SearchParams {- /** Search term (required, non-empty — the server rejects empty/whitespace with 400). */+ /**+ * Search term (required, non-empty — the server rejects empty/whitespace with 400). At most 1000+ * characters and 32 words, punctuation included; the server answers 400 above either.+ */q: string;+ /** Match mode; the server defaults to `word`. */+ match?: SearchMatch;/** Restrict to a single session. */sessionId?: string;/** Restrict to a single chat id. */diff --cc sdk/javascript/test/resources.test.tsindex ef68d2b38,562b39efa..18b2ae968--- a/sdk/javascript/test/resources.test.ts+++ b/sdk/javascript/test/resources.test.ts@@@ -539,12 -539,66 +539,74 @@@ describe('SearchResource — exact patawait c.search.search({ q: 'term', chatId: '[email protected]', direction: 'incoming' });expect(t.lastCall!.url).toBe('http://x/api/search?q=term&chatId=628%40c.us&direction=incoming');});++ it('forwards the match mode', async () => {+ const t = new MockTransport().on('GET', /\/search$/, {+ body: { hits: [], total: 0, tookMs: 1, provider: 'builtin-fts' },+ });+ await client(t).search.search({ q: 'voic', match: 'contains' });+ expect(t.lastCall!.url).toBe('http://x/api/search?q=voic&match=contains');+ });});++ // Eleven routes no other test calls. Each row is written from the contract (openapi.json: verb, path,+ // query and request-body keys), not read off the client, so a changed verb or a renamed body key fails here.+ describe('routes with no other test: verb, path, query and body', () => {+ type Row = [name: string, call: (c: OpenWAClient) => Promise<unknown>, method: string, url: string, body?: unknown];+ const rows: Row[] = [+ ['sessions.getConfig', c => c.sessions.getConfig('s1'), 'GET', 'http://x/api/sessions/s1/config'],+ [+ 'sessions.updateConfig',+ c =>+ c.sessions.updateConfig('s1', { autoRejectCalls: true, maxReconnectAttempts: null, reconnectBaseDelay: 2000 }),+ 'PATCH',+ 'http://x/api/sessions/s1/config',+ { autoRejectCalls: true, maxReconnectAttempts: null, reconnectBaseDelay: 2000 },+ ],+ ['sessions.getProxy', c => c.sessions.getProxy('s1'), 'GET', 'http://x/api/sessions/s1/proxy'],+ [+ 'sessions.updateProxy',+ c => c.sessions.updateProxy('s1', { proxyUrl: null }),+ 'PATCH',+ 'http://x/api/sessions/s1/proxy',+ { proxyUrl: null },+ ],+ [+ 'webhooks.listAll',+ c => c.webhooks.listAll({ limit: 5, offset: 10 }),+ 'GET',+ 'http://x/api/webhooks?limit=5&offset=10',+ ],+ [+ 'webhooks.deliveryFailures',+ c => c.webhooks.deliveryFailures({ sessionId: 's1', limit: 5, offset: 10 }),+ 'GET',+ 'http://x/api/webhooks/delivery-failures?sessionId=s1&limit=5&offset=10',+ ],+ [+ 'chats.subscribePresence',+ c => c.chats.subscribePresence('s1', { chatId: '[email protected]' }),+ 'POST',+ 'http://x/api/sessions/s1/presence/subscribe',+ { chatId: '[email protected]' },+ ],+ ['chats.getPresence', c => c.chats.getPresence('s1', '[email protected]'), 'GET', 'http://x/api/sessions/s1/presence/[email protected]'],+ ['status.fromContact', c => c.status.fromContact('s1', '[email protected]'), 'GET', 'http://x/api/sessions/s1/status/[email protected]'],+ ['labels.chats', c => c.labels.chats('s1', 'l1'), 'GET', 'http://x/api/sessions/s1/labels/l1/chats'],+ [+ 'groups.joinInfo',+ c => c.groups.joinInfo('s1', 'INVITE'),+ 'GET',+ 'http://x/api/sessions/s1/groups/join-info?code=INVITE',+ ],+ ];++ it.each(rows)('%s', async (_name, call, method, url, body) => {+ const t = new MockTransport().passthrough({ status: 200, body: {} });+ await call(client(t));+ expect(t.calls).toHaveLength(1);+ expect(t.lastCall!.method).toBe(method);+ expect(t.lastCall!.url).toBe(url);+ expect(t.lastCall!.body).toEqual(body);+ });+ });diff --cc src/modules/search/dto/search-query.dto.tsindex 3df4c9755,4673eea78..536157e31--- a/src/modules/search/dto/search-query.dto.ts+++ b/src/modules/search/dto/search-query.dto.ts@@@ -3,16 -3,8 +3,16 @@@ import { IsString, IsNotEmpty, IsOptionimport { Type } from 'class-transformer';import { MessageDirection } from '../../message/entities/message.entity';import type { MessageType } from '../../../engine/interfaces/whatsapp-engine.interface';- import { ToStrictNumber } from '../../../common/utils/strict-boolean';+ import { ToStrictNumber, ToStrictString } from '../../../common/utils/strict-boolean';-import { SEARCH_OFFSET_MAX, SEARCH_QUERY_MAX_LENGTH, SEARCH_TERMS_MAX } from '../search.constants';+import {+ SEARCH_CONTAINS_MIN_TERM_LENGTH,+ SEARCH_CONTAINS_WINDOW,+ SEARCH_MATCH_MODES,+ SEARCH_OFFSET_MAX,+ SEARCH_QUERY_MAX_LENGTH,+ SEARCH_TERMS_MAX,+} from '../search.constants';+import type { SearchMatch } from '../search.types';/*** Request shape for GET /search. Numeric fields are coerced from query-string strings via@@@ -34,23 -29,9 +37,24 @@@ export class SearchQueryDto@MaxLength(SEARCH_QUERY_MAX_LENGTH)q!: string;+ @ApiPropertyOptional({+ enum: SEARCH_MATCH_MODES,+ default: 'word',+ description:+ '`word` (default) matches whole words. `contains` matches any part of a word, ignoring case and ' ++ `accents (\`voic\` finds "Invoice", \`cafe\` finds "Café"); it is opt-in on the built-in provider ` ++ '(SEARCH_CONTAINS_ENABLED=true, else 501) and needs at least one term of ' ++ `${SEARCH_CONTAINS_MIN_TERM_LENGTH} or more characters (on PostgreSQL, ${SEARCH_CONTAINS_MIN_TERM_LENGTH} letters or digits in a row). ` ++ `It ranks the ${SEARCH_CONTAINS_WINDOW} most recently stored matches by match quality, so \`total\` is at most ` ++ `${SEARCH_CONTAINS_WINDOW}.`,+ })+ @IsOptional()+ @IsIn(SEARCH_MATCH_MODES)+ match?: SearchMatch;+@ApiPropertyOptional({ description: 'Restrict to a single session' })@IsOptional()+ @ToStrictString()@IsString()sessionId?: string;