Manage the business profile and product catalog
Two WhatsApp business surfaces exist in the API: the business profile — the display name, about text, and profile picture WhatsApp shows next to your number — and the product catalog — the shopfront of product cards a business can send in chats. The profile endpoints work on both engines; catalog reads and product-card sends work on the Baileys engine (since v0.13.0), while whatsapp-web.js — which has no catalog API — still returns 501 Not supported for every catalog call.
This guide shows you how to update the profile fields, and how to read and send from the catalog on a Baileys session.
- A session in the
readystate — see Connect a Session. - An API key with the operator role or higher, sent as
X-API-Key— see Authentication.
All examples use these placeholders. Set them once in your shell:
export BASE="http://localhost:2785/api" # /api is the global prefix; behind your domain + TLS in production
export API_KEY="YOUR_API_KEY" # an operator-or-higher key, from your dashboard
export SESSION="8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a" # the UUID id of a ready session
Update the display name
PUT /api/sessions/{sessionId}/profile/name sets the account display name, capped at 25 characters (WhatsApp's limit).
curl -X PUT "$BASE/sessions/$SESSION/profile/name" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "OpenWA Store"}'
A 200 means the name was accepted. 400 means the session is not started, or since v0.26.0 that name is a JSON boolean or object (before, it was converted to text, so true was sent as the display name); 403 means the engine refused the change.
Update the about/status text
PUT /api/sessions/{sessionId}/profile/status sets the about text shown on the profile. It may be empty to clear it, and is capped at 139 characters (WhatsApp's limit).
curl -X PUT "$BASE/sessions/$SESSION/profile/status" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "We reply within a day."}'
A 200 means the status was accepted; 400 means the session is not started, or since v0.26.0 that status is a JSON boolean or object. A JSON number is still read as its text. On whatsapp-web.js the route answers 501 when the WhatsApp Web build the session runs no longer has the call the library uses to set the About text (v0.31.0+); nothing is asked of WhatsApp and the text is unchanged. Baileys is not affected.
Update the profile picture
PUT /api/sessions/{sessionId}/profile/picture sets the profile picture from either an image url or inline base64 data. When sending base64, mimetype is required (for example image/jpeg).
From a URL:
curl -X PUT "$BASE/sessions/$SESSION/profile/picture" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/store-logo.jpg"}'
From base64 data:
curl -X PUT "$BASE/sessions/$SESSION/profile/picture" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wB...",
"mimetype": "image/jpeg"
}'
DELETE /api/sessions/{sessionId}/profile/picture removes the picture again. It takes no request body:
curl -X DELETE "$BASE/sessions/$SESSION/profile/picture" \
-H "X-API-Key: $API_KEY"
A 200 carries {"success": true, "message": "Profile picture removed"}. The gateway sends the removal to WhatsApp without first checking whether a picture is set, so a repeat answers what WhatsApp answers: the route does not promise that removing a picture that is already absent is a no-op, and WhatsApp's answer for an account with no picture has not been observed. Both verbs work on both engines; unlike the catalog routes below, neither returns 501 for want of engine support. On whatsapp-web.js either verb answers 501 when the WhatsApp Web build the session runs has no job to send the change with (v0.31.0+; nothing was asked of WhatsApp, the picture is unchanged).
Error responses:
| Status | Meaning |
|---|---|
400 | Neither url nor base64 provided, base64 without mimetype, a url that is not an absolute http(s) URL, or the session is not started. Before v0.23.6 a url with no scheme (such as example.com/a.jpg) or an ftp:// link passed validation and was sent as garbled base64. Since v0.23.6 also a url whose server answers a non-2xx status other than a redirect, whose download times out, or whose connection fails (a 500 before). Since v0.31.0 also a url that carries a user name or password (Media URL must not contain credentials (userinfo)), and a url whose host cannot be resolved, that points at or resolves to a blocked internal address, or whose server answers with a redirect (3xx; Destination address is not allowed), all of which answered 500 before (PUT only) |
403 | The engine refused the picture change, or refused the removal |
413 | The decoded base64 image, or since v0.23.6 the image downloaded from url, exceeds the configured media cap (PUT only) |
501 | On whatsapp-web.js, the WhatsApp Web build the session runs has no job to send the change with (v0.31.0+); nothing was asked of WhatsApp and the picture is unchanged |
503 | WhatsApp did not answer within the request budget, on either verb — the change may or may not have applied. Since v0.23.6 a PUT also answers 503 when the session routes url fetches through an egress proxy and the image download failed to connect or timed out before any response, in which case nothing was changed. The gateway resolves and checks the host itself before the request reaches the proxy, so the blocked-address cases above answer 400 on a proxied session too. Since v0.31.0, on whatsapp-web.js, either verb also answers 503 when WhatsApp itself answers with a rate limit, a timeout or a server error (408, 423, 429 or 5xx): nothing was changed, so retry after a pause (it answered 403 before) |
Since v0.23.6 the url check on PUT is also looser than it was. A single-label host such as http://media-store/logo.jpg, a host containing an underscore, and a URL longer than 2084 characters (a long presigned S3 link, for example) used to answer 400; now they pass validation and are fetched. The SSRF guard still checks the host, so an internal host must be listed in SSRF_ALLOWED_HOSTS; one that is not now answers 500 (see the table above) instead of 400. Since v0.31.0 that refusal answers 400 again, as it does on the send routes.
Read the catalog (Baileys engine)
Since v0.13.0, the catalog reads are implemented on the Baileys engine. A whatsapp-web.js session has no catalog API, so every catalog call on it still returns 501 Not supported by the active engine.
GET /api/sessions/{sessionId}/catalog returns the catalog metadata:
curl "$BASE/sessions/$SESSION/catalog" \
-H "X-API-Key: $API_KEY"
The metadata is synthesized from the first collection; a business without collections gets null.
GET /api/sessions/{sessionId}/catalog/products lists the products, with page/limit pagination:
curl "$BASE/sessions/$SESSION/catalog/products?page=1&limit=10" \
-H "X-API-Key: $API_KEY"
The engine walks the library's cursor-based catalog in full and slices page/limit in memory, so pagination.total and pagination.totalPages are exact rather than estimated.
Fetch a single product with GET /api/sessions/{sessionId}/catalog/products/{productId}:
curl "$BASE/sessions/$SESSION/catalog/products/product-42" \
-H "X-API-Key: $API_KEY"
A 200 returns the product, or an empty body when no product in the catalog carries that id. The 404 on this route means no session is running under that id, not an unknown product.
Since v0.24.0, a catalog read that WhatsApp refuses answers 403 with the WhatsApp code in the message; it answered 500 before. A read that WhatsApp rate-limits or leaves unanswered within the request budget answers 503.
Send a product card
POST /api/sessions/{sessionId}/messages/send-product resolves the product from the catalog and sends it as a native product card:
curl -X POST "$BASE/sessions/$SESSION/messages/send-product" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatId": "628123456789@c.us",
"productId": "product-42",
"body": "Back in stock!"
}'
chatId and productId are required; body is optional text accompanying the card. Error responses:
| Status | Meaning |
|---|---|
400 | The product has no image, and the card cannot render without one; since v0.25.0, the chatId is a phone number WhatsApp reports as not registered; since v0.26.0, the chatId is not in the form localpart@host (a number without @c.us answered 500 before) or is sent as a JSON boolean or object; or a message:sending plugin blocked the send or returned an invalid productId or body |
403 | Since v0.24.0, WhatsApp refused the product lookup (it answered 500 before). This refusal does not count toward the send breaker. A key restricted with allowedChats also gets 403 for a chatId outside its allowlist |
404 | Two causes, told apart by the message. Either the session is not started or not connected (Session <id> not found or not connected), which this route reports like the catalog reads above rather than as a 400, because it is served by the catalog service despite sitting under /messages/; or the productId is not in the session's catalog (Product <id> not found in the session catalog) |
409 | An engine exists for the session but is not ready. A Baileys connection replaced or stopped while the card was being written also answers 409, and since v0.31.0 its message says the card may or may not have been sent: check the chat before sending again |
429 | Send pacing is enabled (SEND_PACING_ENABLED, off by default) and the send is over a budget; the body carries code: "SEND_PACING_LIMITED" and retryAfterSeconds. See Ban risk & safe sending |
501 | Called on a whatsapp-web.js session |
503 | WhatsApp did not answer the catalog lookup within the request budget, or rate-limited it; since v0.25.0, also when it did not answer the recipient lookup in time. Nothing was sent for those. Since v0.26.0, on Baileys, also when WhatsApp rate-limits the send itself (code 429: nothing was sent) or times out a query the send awaits (code 408: the outcome is not proven, so the card may have been delivered); these answered 500 before |
503 is not always transientWhatsApp does not always answer the underlying w:biz:catalog query for a business account. When the server simply stays silent, with the socket healthy and every other query replying normally, the request spends its budget and answers 503. That is a WhatsApp-side limitation of the affected account rather than a passing failure, so this particular 503 does not clear on retry and can be permanent. It applies to the catalog reads and to send-product. Retrying is worth one attempt; a 503 that repeats on a healthy session is telling you the account's catalog is not readable through this API at all.
send-catalog was removed in v0.19.0POST /api/sessions/{sessionId}/messages/send-catalog always answered 501 — neither library has a catalog-share message type — so v0.19.0 removed the route entirely. A call to the old URL now gets a 404. Sending a full catalog grid is not available anywhere; send a product card with send-product, or share a product link as text.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
400 Session is not started | On the profile routes, no engine is running for the session | Start the session, then retry |
404 Session ... not found or not connected | The same case on the catalog routes and send-product, which report an unstarted session as 404 rather than 400 | Start the session, then retry |
409 | An engine exists but is not ready: disconnected, reconnecting, or still initializing, so the request never reached WhatsApp. Since v0.26.0 a profile request on whatsapp-web.js also answers 409 when WhatsApp Web reloads its page under it or the session is stopped while it runs (a 500 or 503 before). Since v0.31.0 the page-reload 409 carries code: "ENGINE_PAGE_RELOADING" and retryAfterSeconds, and a profile picture write that reaches a page that has not finished loading answers it too (a bare 500 before) | Wait for the session to reach ready, then retry. For ENGINE_PAGE_RELOADING, ask again every retryAfterSeconds: a reload takes seconds on most pages and can take a few minutes, and no event marks its end |
503 | WhatsApp did not answer within the request budget | Retry shortly; on a write, read the value back before replaying. On the catalog reads and send-product, see the caution below: a 503 there can be permanent for the account |
403 The engine refused the name change | WhatsApp rejected the value (for example, an unavailable name) | Retry with a different value |
413 on picture upload | The decoded base64 image, or since v0.23.6 the image downloaded from url, exceeds the media cap | Compress the image or raise the media cap |
501 Not supported on catalog calls | Session runs on the whatsapp-web.js engine (no catalog API) | Use a Baileys session for catalog reads and send-product |
403 Reading the catalog was refused by WhatsApp (code <n>) | WhatsApp rejected a catalog read, or the product lookup behind send-product (v0.24.0+; a 500 before) | The gateway cannot change what WhatsApp permits: confirm the linked account may read its own catalog, then retry |
403 API key is restricted to selected chats | The key carries allowedChats (v0.23.6+). The profile routes and the catalog reads refuse such a key | Use a key without allowedChats. send-product stays open to a chat-scoped key for a chatId in its allowlist and answers 403 for any other; see Authentication |
404 on send-catalog | The route was removed in v0.19.0 — it never worked on any engine | Send a product card with send-product, or share a product link as text |
Next steps
- Send other message types — see Send messages from a session.
- See the full request and response shapes in the API reference.
- Learn how session state gates these calls in Sessions.