Set the group's picture
PUT/api/sessions/:sessionId/groups/:groupId/picture
Set the group's picture
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 413
- 501
- 503
Group picture updated
The id does not name a group, the session is not active, neither url nor base64 was supplied, the url answers non-2xx, times out or cannot be reached, or the image cannot be read (Baileys refuses an SVG)
The API key is missing, unknown, revoked, or expired
The engine refused the change: editing the group info takes an admin, or any member of a group whose info is not restricted to admins. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.
No such group — the id is unknown.
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.
The decoded base64 media, or the media downloaded from url, exceeds the media byte cap (MEDIA_DOWNLOAD_MAX_BYTES, 50 MiB by default). A whole request is separately bounded by BODY_SIZE_LIMIT (25 mb by default), and base64 inflates by about a third, so a large send usually meets that coarser limit first: the body parser rejects the request before this check runs.
On whatsapp-web.js, answered when the WhatsApp Web build the session runs has no job to send the change with. Nothing was asked of WhatsApp: the group is unchanged.
WhatsApp did not answer within the request budget. The change may or may not have been applied — the gateway stopped waiting for a confirmation that never came. On Baileys, also answered when WhatsApp rate-limits or times out the request (code 429 or 408); retry after a pause. On whatsapp-web.js, also when WhatsApp answers the change with a rate limit, a timeout or a server error (408, 423, 429 or 5xx): nothing was changed, so retry after a pause. The session routes its url fetches through an egress proxy, and the fetch failed or timed out before any response arrived, so the request was not carried out. The proxy or the target behind it may be at fault; the gateway cannot tell which. Retryable, but a 503 that persists while the proxy works points at the url. Without a session proxy the same failure answers 400.