Set the account's own global presence (appear online or offline)
PUT/api/sessions/:sessionId/presence
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.
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 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.
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.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 503
Presence published
Session not started, or validation failed
The API key is missing, unknown, revoked, or expired
The API key's role, session or chat scope, or IP allow-list does not allow this operation
Session not found
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 send whose first attempt had already run when the session left ready (or WhatsApp Web reloaded its page) is the exception: it answers a 409 with no code that says the message may or may not have been sent, so check the chat before sending it again (a retry with the same Idempotency-Key answers IDEMPOTENCY_OUTCOME_UNKNOWN). 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 until it has the answer is a 409 naming the reload, with code ENGINE_PAGE_RELOADING and retryAfterSeconds. That takes seconds on most reloads and can take a few minutes, and no event marks its end: ask again at that interval. 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.
The whatsapp-web.js page connection died, or WhatsApp Web did not answer within the protocol timeout. Nothing was confirmed; setting presence converges when repeated, so a retry is safe.