Pin a message in its chat
POST/api/sessions/:sessionId/messages/pin
Pin a message in its chat
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 501
- 503
Message pinned
Session not active, or durationSeconds is not one of 86400 / 604800 / 2592000
The API key is missing, unknown, revoked, or expired
The whatsapp-web.js engine refused the pin (in a group only admins may pin, or the chat is with a contact the account blocked). Also answered when WhatsApp Web reports the send as failed, which its sender says no more about, so a rate limit of the send reads the same. The Baileys engine has no acceptance signal and answers 200. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.
Message not found in the chat
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 whatsapp-web.js, answered when the WhatsApp Web build the session runs has no pin sender this gateway can call. Nothing was sent: the message is not pinned.
Baileys could not complete the recipient lookup within the request budget. On send routes, no message was handed to WhatsApp for this lookup failure. On Baileys, also when WhatsApp rate-limits the request (code 429: nothing was sent, and a keyed send frees its Idempotency-Key), times out a query it awaits (code 408: the outcome is not proven, and a keyed send keeps its Idempotency-Key taken), or the connection closes before the message is written (nothing was sent, and a keyed send frees its Idempotency-Key). The whatsapp-web.js page connection died mid-request, or WhatsApp Web did not answer within the request budget. The pin may or may not have been applied; a retry is safe, but it restarts the pin duration from the moment it succeeds. Also answered on whatsapp-web.js when WhatsApp answers the read of the group in front of the send with a rate limit, a timeout or a server error (408, 423, 429 or 5xx): nothing was sent.