Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(presence): describe the no-name 409 and every preference drop
Yudhi Armyndharis90511b240419
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9c1f47289..8c9fbeea4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed- A plugin `configUi` editor receives the dashboard language as `locale` in `config:value`, and the `schema` it gets carries field titles and descriptions localized from the manifest `i18n` block, as the generated form already showed. Thanks @probably-ABHINAV, and @TreIngenia for the proposal.+- `PUT /api/sessions/:sessionId/presence` is re-applied once each time the engine's connection opens, so an `available: false` survives a Baileys transient reconnect instead of being replaced by the connect-time announcement. It is still dropped when the gateway replaces the engine. On Baileys the route answers `409` while the account push name has not synced, where it answered `200` and sent nothing. Thanks @gabrielmmoraes1999.## [0.23.7] - 2026-09-25diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 8acdabc43..a80421341 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -889,10 +889,12 @@ offline suppresses the phone's own alerts — `available: false` hands them backengines.A successful call is remembered for the life of the running engine and re-applied once each time-that connection opens, including a Baileys transient reconnect. Baileys broadcasts `available` on-connect (`markOnlineOnConnect`), which would otherwise replace a previous `available: false`. The-preference is dropped when the engine is replaced (stop, or a restart that builds a new engine) and-must be re-issued after that. Typing, recording, and outbound sends do not change global presence.+that connection opens, including a Baileys transient reconnect. Baileys announces itself on connect+(`available` unless `BAILEYS_MARK_ONLINE_ON_CONNECT=false`), which would otherwise replace the+caller's choice. The preference is dropped whenever the gateway replaces the engine: stop, restart,+reconnect recovery, a watchdog recycle, or a takeover by another node. Re-issue it after+`session.status` reports `ready` again. On Baileys, typing, recording and outbound sends do not+change global presence.Not best-effort — a failure surfaces instead of leaving the account silently online. On Baileys a`409` is also returned when the account push name has not synced yet: `sendPresenceUpdate` returnsdiff --git a/docs/07-api-collection.md b/docs/07-api-collection.mdindex 03dbd5082..ba5a07908 100644--- a/docs/07-api-collection.md+++ b/docs/07-api-collection.md@@ -218,8 +218,9 @@ curl "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence/123456789Set the account's OWN global presence — appear online or offline (OPERATOR, both engines). Asuccessful call is re-applied once each time that engine's connection opens, including a Baileys-transient reconnect, and dropped when the engine is replaced. On Baileys a `409` means the push-name has not synced yet and nothing was sent.+transient reconnect. It is dropped whenever the gateway replaces the engine (stop, restart, reconnect+recovery, watchdog recycle, takeover), so re-issue it after `session.status` reports `ready`. On+Baileys a `409` on a ready session means the push name has not synced yet and nothing was sent.```bashcurl -X PUT "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence" \diff --git a/openapi.json b/openapi.jsonindex 66331656b..2fb3303ca 100644--- a/openapi.json+++ b/openapi.json@@ -1218,7 +1218,7 @@},"/api/sessions/{sessionId}/presence": {"put": {- "description": "Publishes whether this account appears online. WhatsApp routes notifications away from the phone while a linked device announces itself online, so a headless bot that never goes offline suppresses the phone's own alerts — set `available: false` to hand them back.\n\nA successful call is remembered for the life of the running engine and re-applied once each time that connection opens, including a Baileys transient reconnect: the socket broadcasts `available` on connect (`markOnlineOnConnect`), which would otherwise wipe `available: false`. The preference is dropped when the engine is replaced (stop, or a restart that builds a new engine) and must be re-issued after that. Typing, recording, and outbound sends do not publish global presence.\n\nOn Baileys the call fails with 409 when the account push name has not synced yet — the library would otherwise accept the request and send nothing. Supported on both engines.",+ "description": "Publishes whether this account appears online. WhatsApp routes notifications away from the phone while a linked device announces itself online, so a headless bot that never goes offline suppresses the phone's own alerts — set `available: false` to hand them back.\n\nA successful call is remembered for the life of the running engine and re-applied once each time that connection opens, including a Baileys transient reconnect: the socket announces itself on connect (`available` unless `BAILEYS_MARK_ONLINE_ON_CONNECT=false`), which would otherwise replace the caller's choice. The preference is dropped whenever the gateway replaces the engine: stop, restart, reconnect recovery, a watchdog recycle, or a takeover by another node. Re-issue it after `session.status` reports `ready` again. On Baileys, typing, recording and outbound sends do not publish global presence.\n\nOn Baileys the call fails with 409 when the account push name has not synced yet — the library would otherwise accept the request and send nothing. Supported on both engines.","operationId": "SessionController_setOnlinePresence","parameters": [{@@ -1259,7 +1259,7 @@"description": "Session not found"},"409": {- "description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly."+ "description": "The session is not connected: an engine exists for it but is not `ready`, meaning disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Wait for `ready` and retry. A session that was never started answers `400` instead, and the session lifecycle routes answer `409` for a conflicting state rather than this. One window answers this while the session still reads `ready`: WhatsApp Web periodically reloads its own page and the engine re-injects into it, and for those few seconds the answer is a `409` naming the reload; retry shortly. On Baileys this route also answers `409` for a `ready` session whose account push name has not synced yet. Nothing was sent, and a retry succeeds only once the name has synced."}},"summary": "Set the account's own global presence (appear online or offline)",diff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.tsindex 883dd9214..1e7288cf7 100644--- a/src/engine/interfaces/whatsapp-engine.interface.ts+++ b/src/engine/interfaces/whatsapp-engine.interface.ts@@ -1496,9 +1496,10 @@ export interface PresenceCapability {* wire operation (`<chatstate>` / `sendStateTyping`) and do not publish this.** The call itself is one-shot. The gateway remembers a successful one for the life of the running- * engine and re-applies it once each time that connection opens: Baileys broadcasts `available`- * on connect (`markOnlineOnConnect`), which would otherwise wipe `available: false` on a- * transient reconnect. Replacing the engine drops the preference.+ * engine and re-applies it once each time that connection opens: Baileys announces itself on+ * connect per `markOnlineOnConnect` (`available` by default), which would otherwise replace the+ * caller's choice on a transient reconnect. Replacing the engine drops the preference: stop,+ * restart, reconnect recovery, a watchdog recycle, or a takeover by another node.** On Baileys this throws when the account push name is not set yet. `sendPresenceUpdate`* resolves without sending in that case (`no name present, ignoring presence update request`).diff --git a/src/modules/session/session.controller.ts b/src/modules/session/session.controller.tsindex d79d2b272..23a40d06a 100644--- a/src/modules/session/session.controller.ts+++ b/src/modules/session/session.controller.ts@@ -602,11 +602,12 @@ export class SessionController {'phone while a linked device announces itself online, so a headless bot that never goes ' +"offline suppresses the phone's own alerts — set `available: false` to hand them back.\n\n" +'A successful call is remembered for the life of the running engine and re-applied once each ' +- 'time that connection opens, including a Baileys transient reconnect: the socket broadcasts ' +- '`available` on connect (`markOnlineOnConnect`), which would otherwise wipe `available: false`. ' +- 'The preference is dropped when the engine is replaced (stop, or a restart that builds a new ' +- 'engine) and must be re-issued after that. Typing, recording, and outbound sends do not ' +- 'publish global presence.\n\n' ++ 'time that connection opens, including a Baileys transient reconnect: the socket announces ' ++ 'itself on connect (`available` unless `BAILEYS_MARK_ONLINE_ON_CONNECT=false`), which would ' ++ "otherwise replace the caller's choice. The preference is dropped whenever the gateway replaces " ++ 'the engine: stop, restart, reconnect recovery, a watchdog recycle, or a takeover by another ' ++ 'node. Re-issue it after `session.status` reports `ready` again. On Baileys, typing, recording ' ++ 'and outbound sends do not publish global presence.\n\n' +'On Baileys the call fails with 409 when the account push name has not synced yet — the ' +'library would otherwise accept the request and send nothing. Supported on both engines.',})@@ -614,7 +615,13 @@ export class SessionController {@ApiResponse({ status: 200, description: 'Presence published', type: SessionActionResponseDto })@ApiResponse({ status: 400, description: 'Session not started, or validation failed' })@ApiResponse({ status: 404, description: 'Session not found' })- @ApiResponse({ status: 409, description: ENGINE_NOT_READY_409 })+ @ApiResponse({+ status: 409,+ description:+ ENGINE_NOT_READY_409 ++ ' On Baileys this route also answers `409` for a `ready` session whose account push name has ' ++ 'not synced yet. Nothing was sent, and a retry succeeds only once the name has synced.',+ })async setOnlinePresence(@Param('sessionId', ParseUUIDPipe) id: string,@Body() dto: SetOwnPresenceDto,diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex f3db4877d..dd3ddb48d 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -5673,6 +5673,22 @@ describe('SessionService', () => {expect(mockEngine.setOnlinePresence).toHaveBeenCalledWith(false);});+ it('re-applies on every later open of the same engine, and keeps the preference after a failed re-apply', async () => {+ const callbacks = await startAndCaptureCallbacks();+ await service.setOnlinePresence('sess-uuid-1', false);+ mockEngine.setOnlinePresence.mockClear();++ // A transient reconnect keeps the engine and fires onReady again; the first re-apply fails.+ mockEngine.setOnlinePresence.mockRejectedValueOnce(new Error('socket closed'));+ callbacks.onReady!('628123', 'Alice');+ await flush();+ callbacks.onReady!('628123', 'Alice');+ await flush();++ expect(mockEngine.setOnlinePresence).toHaveBeenCalledTimes(2);+ expect(mockEngine.setOnlinePresence).toHaveBeenNthCalledWith(2, false);+ });+it('does not publish own presence on ready when the caller never set one', async () => {const callbacks = await startAndCaptureCallbacks();mockEngine.setOnlinePresence.mockClear();