Set the account profile picture (URL or base64 image)
PUT/api/sessions/:sessionId/profile/picture
Set the account profile picture (URL or base64 image)
Request
Responses
- 200
- 400
- 401
- 403
- 409
- 413
- 503
Profile picture updated
Neither url nor base64 provided, base64 without mimetype, session is not started, 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 whatsapp-web.js engine refused the picture change. The Baileys engine has no acceptance signal and answers 200 for an upload WhatsApp declined. Also returned when the API key's role, session or chat scope, or IP allow-list does not allow this operation.
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.
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.
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. 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.