Set a WhatsApp Group Icon via API
Groups are the part of WhatsApp the official Cloud API never reached: there is no endpoint to create one, administer it or read its members. Wapito drives a linked number instead, so a group is an ordinary REST call.
Can the official WhatsApp Cloud API do this?
No. There is no group, so there is no group icon.
Read the full comparisonHow it works
Upload a square image, set it on the group, read it back for your dashboard, and clear it when the group is retired.
Upload the image
Send a square JPEG or PNG and keep the source file to hand. A rectangular image is cropped by WhatsApp rather than letterboxed, so anything with text near the edge will lose it.
API reference for this stepSet it as the group icon
Apply the uploaded media to the group. The change is announced in the group, so avoid running this on a schedule that flips the icon back and forth.
API reference for this stepRead the current icon
Fetch the current picture to show it in your own dashboard or to check whether an admin has replaced the one your automation set.
API reference for this stepRemove it when the group is retired
Clearing the icon is a cheap, visible signal that a group is closed, which works well alongside renaming it and locking it to admins only.
API reference for this step
curl --request GET \
--url https://api.wapito.com/v1/groups/120363041234567890@g.us/icon \
--header 'Authorization: Bearer wpt_YOUR_TOKEN'Endpoints
Webhook events
groupsGroup joined, left or updatedonGroups()
What you can build with it
- Brand every client group automatically
An agency sets the client's logo as the icon the moment a project group is created, so a consultant opening WhatsApp can identify the right thread at a glance among twenty similar-looking groups.
- Show status at a glance
A support team uses a small set of coloured icons to show whether a job group is open, waiting on the customer, or closed. The icon is set by the same automation that moves the ticket, so it is never out of date.
- Clear the icon when a group is archived
At the end of an intake, the automation renames the group, clears its icon and locks it to admins. Members can still read the history, and it is obvious from the chat list that nothing new is coming.
What the official WhatsApp Cloud API does here
Meta's official WhatsApp Cloud API is built for business messaging: templates, customer-service windows and per-conversation pricing. A large part of what WhatsApp itself can do — groups, channels, status, presence, contact lookups — has no endpoint there at all, which is why so many teams end up looking past it. Everything below is checked against Meta's own published reference, with the link and the date we checked it.
Not possible on the Cloud API
No. There is no group, so there is no group icon.
Meta's Cloud API can manage a business profile picture for the number itself, but it documents no group object and therefore no group icon. The two are not substitutes: one is how your business appears, the other is how a shared conversation appears to its members.
Paraphrase (not a verbatim quote), checked against the Cloud API reference index: the reference has a business profile for the number but no group node and no group picture.
The official workaround
None for groups. A business can set its own profile picture through the official API, which is a different thing entirely.
Wapito is an independent product. It is not affiliated with, endorsed by, sponsored by or certified by WhatsApp or Meta Platforms, Inc. WhatsApp is a trademark of Meta Platforms, Inc.
Gotchas
- Non-square images are cropped to a circle by the client, so anything important near an edge disappears; resize to a square before uploading rather than relying on the crop.
- Setting the icon needs admin rights, and a group whose settings restrict edits to admins will refuse the call from a member that was demoted since your last run.
Tutorials by language
Frequently asked questions
What size should the image be?
Square, and large enough that the client's downscale looks clean rather than soft - a few hundred pixels on a side is plenty. WhatsApp compresses aggressively, so fine detail and small text will not survive; a simple mark on a solid background reads far better in a chat list.
Can I read the icon of a group I am not in?
No. Like everything else about a group, the icon is visible only to members. Resolving an invite code gives you the group's name and size before joining, but not its picture, so a preview screen has to make do with the metadata the code returns.
Does changing the icon notify everyone?
It appears as a system message in the group naming the admin who changed it, which every member sees in the thread. It does not usually generate a push notification, but it does take up a line in the conversation, so batch changes rather than flipping the icon repeatedly.
What happens if the upload succeeds but the set call fails?
The media stays uploaded and unused, and the group keeps its old icon. Retry the set call with the same media id rather than re-uploading, and expire unused media ids in your own records so a failed run does not leave you guessing which upload was which.
Related
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.