Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: correct comments and entries that describe code they do not match

Yudhi Armyndharis853926762fab
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68a25b9f5..4feaf42ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
-- A WebSocket client that emits without an ack callback receives command replies again. The gateway answered by returning a frame, which Socket.IO delivers through the ack callback and nowhere else, so a client written to the documented `message` event saw no subscribe confirmation, no pong, and none of the refusals, including the session-scope denial. Replies now go out on `message` as well as through the ack.
+- A WebSocket client that emits without an ack callback now receives command replies at all. The gateway answered by returning a frame, which Socket.IO delivers through the ack callback and nowhere else, so a client written to the documented `message` event saw no subscribe confirmation, no pong, and none of the refusals, including the session-scope denial. Replies now go out on `message` as well as through the ack.
- A Baileys message the account sent from its phone is no longer lost when the message store cannot be read. The repeat-delivery check threw on a locked database or an unparseable row and the message was dropped with it, and WhatsApp does not re-deliver one it has already acked; the check now fails open, so at worst such a message is reported twice rather than never.
- Baileys `editMessage` answers with the edited message's id and original send time instead of the edit envelope's. The id named a message no route could address, and both fields disagreed with the whatsapp-web.js engine, which reports the message rather than the edit.
- Saved Baileys contacts are no longer evicted by peers seen once in a group or a broadcast. Both populations shared one capped map, so a busy session answered `GET /api/sessions/:sessionId/contacts` with fewer and fewer of the contacts the account actually saved. `BAILEYS_SESSION_STORE_MAX_ENTRIES` now bounds the peer side of that map; the saved side is bounded by the account's own address book.
@@ -41,7 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Uploading a zip whose trailer parses but whose directory does not answers `400`, not `500`.
- A `socks5://` or `socks4://` proxy at an IPv6 literal connects: the brackets `URL` keeps were going on the wire as part of a hostname.
- A proxy password no longer reaches the log. A failed SOCKS connect carries the whole proxy config as the error's only property, and `BAILEYS_LOG_LEVEL=debug` wrote it to stdout verbatim.
-- Baileys sessions list the saved address book again after a process restart. WhatsApp sends neither history nor an app-state snapshot to a device that has synced once, and the contact store is in memory, so a restarted gateway answered `GET /api/sessions/:sessionId/contacts` with only the peers it had seen since. Each session now re-pulls the snapshot of the app-state collection that carries saved contacts, once per engine start. That also repairs a PARTIAL address book, which is the usual shape: during the initial sync WhatsApp folds saved contacts into the history batch, where their names are stripped as chat titles, so the store keeps plenty of contacts with the saved ones missing. The list is also the address book only: a peer known by pushname alone is no longer listed, while `GET .../contacts/:contactId` still resolves it with `isMyContact: false`, and a chat title from history sync no longer overwrites a saved name. Thanks @gabrielmmoraes1999.
+- Baileys sessions list the saved address book again after a process restart. WhatsApp sends neither history nor an app-state snapshot to a device that has synced once, and the contact store is in memory, so a restarted gateway answered `GET /api/sessions/:sessionId/contacts` with only the peers it had seen since. Each session now re-pulls the snapshot of the app-state collection that carries saved contacts, once per engine start. That also repairs a PARTIAL address book, which is the usual shape: during the initial sync the library's event buffer folds the saved-contact updates into the history batch it is already holding, where their names are stripped as chat titles, so the store keeps plenty of contacts with the saved ones missing. The list is also the address book only: a peer known by pushname alone is no longer listed, while `GET .../contacts/:contactId` still resolves it with `isMyContact: false`, and a chat title from history sync no longer overwrites a saved name. Thanks @gabrielmmoraes1999.
- whatsapp-web.js sessions send media again on the WhatsApp Web builds rolled out on 2026-09-17: the library spread the media model into the outgoing message after its id, and the model's private `__x_id` clobbered it, so every image, video, audio, document, sticker and status media send failed with `Data passed to getter must include an id property` while text kept working. An install-time patch carries upstream's one-line fix until a whatsapp-web.js release ships it ([#1643](https://github.com/rmyndharis/OpenWA/issues/1643), [#1636](https://github.com/rmyndharis/OpenWA/issues/1636)). Thanks @15874611923 and @Magnarks for the reports.
- An ingress route can declare `dedupOn: "body"` to key provider retries on the raw body instead of the delivery-id header. A provider that mints a fresh delivery id on every retry attempt, as supabase/auth does inside its hook retry loop, was never deduplicated when an ack was lost, so the contact received the message twice; routes that do not declare it keep the header ([#1641](https://github.com/rmyndharis/OpenWA/issues/1641)).
- Baileys sessions record a message the account sent from its phone while the gateway was down, and dispatch `message.sent` for it, as they already did for one sent while the gateway was online. The offline replay carried the same `append` tag as the library's echo of an API send, which the upsert handler dropped wholesale; it now skips only the ids this session sent itself, and the phone's reactions, edits and revokes from that window are replayed the same way ([#1667](https://github.com/rmyndharis/OpenWA/issues/1667)).
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 245eb47dd..05d07a8d3 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -180,7 +180,7 @@ Every timestamp column on the PostgreSQL data connection is `timestamp without t
Three `@CreateDateColumn`/`@UpdateDateColumn` columns are filled by the app rather than by that default: `lid_mappings.updatedAt`, `chat_states.updatedAt` and `baileys_stored_messages.createdAt` reach the database through an `upsert` that passes the value, so the default behind them never fires and they follow the binding rule above instead of the session zone.
-`messages.createdAt` is a fourth, and the only split one: a live message takes the server default, while a row written by the Baileys history backfill carries the message's own time, stamped in `message-history-projector.ts` so the chat panel orders history correctly. Both conventions are UTC from this release on, and the two cannot be told apart row by row, which is why the upgrade notes exclude that column from any blanket conversion.
+`messages.createdAt` is a fourth, and split within itself: a live message takes the server default, while a row written by the Baileys history backfill carries the message's own time, stamped in `message-history-projector.ts` so the chat panel orders history correctly. Both conventions are UTC from this release on, and the two cannot be told apart row by row, which is why the upgrade notes exclude that column from any blanket conversion. A restore writes `createdAt`/`updatedAt` explicitly wherever the archive carries them, so a restored table follows the archive rather than either rule above; the upgrade notes cover that case separately.
Comparisons therefore mean the same thing on both dialects: a retention `LessThan(cutoff)`, a lease deadline written by another node, and a backup restored from any host all line up. SQLite is unaffected; it already stores ISO text in UTC.
diff --git a/src/database/postgres-utc.ts b/src/database/postgres-utc.ts
index 7dd26541f..539a183d9 100644
--- a/src/database/postgres-utc.ts
+++ b/src/database/postgres-utc.ts
@@ -12,8 +12,8 @@ import { DataSource } from 'typeorm';
* columns, the pending-delivery stamps: every column the app itself writes),
* - the driver parses a naive timestamp back as PROCESS-local,
* - `DEFAULT now()`, which is what fills a `@CreateDateColumn`/`@UpdateDateColumn` the app leaves
- * alone (TypeORM binds one only when a value is passed, as the contact and message-store upserts
- * and the Baileys history backfill do), writes the SERVER session's zone.
+ * alone (TypeORM binds one only when a value is passed, as the lid-mapping, chat-state and
+ * message-store upserts and the Baileys history backfill do), writes the SERVER session's zone.
*
* Off UTC the row therefore carries two conventions at once, and comparisons that mix them are wrong by
* the offset: a retention `LessThan(cutoff)` binds the cutoff as local wall time and measures it against
@@ -71,8 +71,7 @@ const SET_SESSION_UTC = "SET TIME ZONE 'UTC'";
* guaranteed to survive the path to the server (a pooler may drop it, and PgBouncer refuses the startup
* packet outright unless it is listed in `ignore_startup_parameters`), and on this connection it is
* already spoken for by the search_path of a non-public schema. pg-pool awaits this hook for every
- * client it opens, the first one during `DataSource.initialize()` included, so none can start unpinned,
- * and `connectionTimeoutMillis` still bounds the whole connect, the extra round trip included.
+ * client it opens, the first one during `DataSource.initialize()` included, so none can start unpinned.
*
* The hook rather than a `Client` subclass that pins inside its own `connect`, because the pool owns two
* things a subclass cannot reach. It attaches the client's `error` listener BEFORE calling the hook, so
@@ -80,6 +79,10 @@ const SET_SESSION_UTC = "SET TIME ZONE 'UTC'";
* instead of reaching Node as an unhandled `error` event, which ends the process. And it calls
* `client.end()` when the hook rejects, so a server that refuses the statement does not leave an
* authenticated backend open once per acquire until `max_connections` runs out.
+ *
+ * `connectionTimeoutMillis` does NOT cover this statement: pg-pool clears that timer once the socket
+ * is connected, before it invokes the hook, so a server that accepts the connection and then never
+ * answers holds the acquire until the statement's own failure. Nothing else in the pool bounds it.
*/
const pinSessionToUtc = (client: ClientBase): Promise<unknown> => client.query(SET_SESSION_UTC);
diff --git a/src/engine/adapters/baileys-events.ts b/src/engine/adapters/baileys-events.ts
index ef6cead4a..892a309c9 100644
--- a/src/engine/adapters/baileys-events.ts
+++ b/src/engine/adapters/baileys-events.ts
@@ -195,8 +195,9 @@ export class BaileysEvents {
// Throttle through the limiter so a burst of media messages can't run unbounded parallel
// downloads (each a full decrypted buffer in heap). Ordering stays correct — the message store
// keeps the newest by timestamp. The queue is unbounded, so a burst parks rather than shedding
- // and the message keeps its media either way; on any rejection we still re-process WITHOUT
- // media, so the body and metadata are emitted rather than lost.
+ // and the message keeps its media either way. The catch below is the teardown path: the
+ // limiter rejects only when it has been closed, since processInboundMessage handles its own
+ // failures (a media download that fails emits the omitted marker rather than throwing).
void this.host.inboundLimiter
.run(() => this.processInboundMessage(msg))
.catch((error: unknown) => {
diff --git a/src/engine/adapters/baileys-session-store.ts b/src/engine/adapters/baileys-session-store.ts
index 07eea6d08..a776f45d8 100644
--- a/src/engine/adapters/baileys-session-store.ts
+++ b/src/engine/adapters/baileys-session-store.ts
@@ -118,7 +118,10 @@ class LruMap<K, V> {
*
* Every map is LRU-bounded (`BAILEYS_SESSION_STORE_MAX_ENTRIES`, default 5000 per map, 0 = unbounded)
* because contacts/chats/lastMessages/lidToPn all grow from peer-controlled traffic — without a cap a
- * chatty account leaks one entry per distinct peer ever seen. Miss paths after an eviction:
+ * chatty account leaks one entry per distinct peer ever seen. On the contacts map that cap governs the
+ * peers ALONE: a contact carrying a saved name is pinned and never evicted, because it comes from the
+ * account's own address book rather than from traffic, and that side is bounded by the address book
+ * instead (see LruMap's `pinned`). Miss paths after an eviction:
* `lidToPn` falls back to the contacts map and then the persisted cross-session lid->phone table (all
* writes are written through), `lastMessage` reads null (callers treat it as "nothing known"),
* `getEphemeralExpiration` falls back to `Chat.ephemeralExpiration` then undefined (never forces a