Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(presence): describe the no-name 409 and every preference drop

Yudhi Armyndharis90511b240419
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-25
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 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 back
engines.
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` returns
diff --git a/docs/07-api-collection.md b/docs/07-api-collection.md
index 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/123456789
Set the account's OWN global presence — appear online or offline (OPERATOR, both engines). A
successful 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.
```bash
curl -X PUT "$BASE/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/presence" \
diff --git a/openapi.json b/openapi.json
index 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.ts
index 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.ts
index 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.ts
index 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();