Update a WhatsApp Group Name, Description, or Avatar via API

To change a WhatsApp group’s name, description, or avatar through UnifyPort, send POST /v1/accounts/{account_id}/groups/update-info with group_id and at least one of name, description, or avatar_url. The endpoint requires group-admin permission. Send only the fields the operator intends to change, then read the group again; do not treat an old editor snapshot as the current group state.

Key takeaways

• Group information is not a private CRM label. Make the scope clear before saving.
• Keep the selected account and group IDs fixed throughout the edit.
• Submit a small, explicit change rather than copying the entire read response into a write.
• Reconcile each requested field; neither a timeout nor a missing webhook proves nothing changed.

Choose the field, not a generic settings action

WhatsApp documents native editing in How to make changes to groups. Its group-admin settings guide also explains the “Edit group settings” permission for members. That native setting does not widen UnifyPort’s contract: the Update group info reference explicitly requires admin permission.

Intended edit	Request field	Separate concern
Change the group name	name	Your inbox’s private display alias
Change the group description	description	A support ticket or message body
Replace the group image	avatar_url	A participant’s profile photo

For a role change, follow promoting and demoting group admins. For invitation distribution, use the group invite-link workflow. Neither action belongs in this metadata form.

UnifyPort is an unofficial interface. Its provider action matrix maps this write to whatsapp, not LINE, Telegram, or the separate whatsapp-protocol provider. Group reads and group-event support do not imply permission to update group information.

Build the editor around a fresh read

Select the target through List groups under the intended messaging account, following pagination. Retain the returned id; for a group, conversation_id equals id. Names are display values, not unique identifiers.

Then use Get group to retrieve current information. Keep three things separate in your application:

1. The last observed values.
2. The fields the operator actually edited.
3. The values observed after submitting the change.

If the operator edits only the description, do not resend the old name and avatar. If a fresh read shows another person’s change to a field being edited, ask the operator to review it before saving. These are application safeguards, not server-side version checks.

Display the selected account, group, and changed fields in the confirmation view. Keep API keys on the backend and enforce your own operator permissions there.

Submit only the intended group changes

The following JavaScript illustrates one backend request. Supply the actual selected identifiers and a server-held API key. This example deliberately supports only non-empty replacements; it does not define a clearing or avatar-removal operation.

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

Pass only edited fields in edits. For an avatar, the reference requires a public image URL. Use an image you control and can expose publicly; do not send a local file path or a page requiring a browser login. This is a URL-based request, not an image-upload endpoint.

The documented success response is 200 OK with data.ok: true. Check both before showing success. A production caller must also handle network failures and non-JSON responses, preserve request_id when available, and avoid logging credentials. The example is illustrative and has not been executed here.

Reconcile fields instead of replaying the form

After the request, read the same group again. Compare the requested name and description with observed values. For images, inspect the returned avatar or native app rather than requiring the returned URL to equal the submitted source URL; the contract does not promise URL identity.

The standard events reference documents group.updated with multiple possible entries in data.changes[]:

• renamed carries name.
• description_changed carries description.
• WhatsApp avatar_changed carries removed and optionally picture_id, not an image URL.

Use these as reconciliation signals, not guaranteed per-request receipts. Verify signed deliveries according to the webhook delivery contract, tolerate duplicates and reordering, and never clear unrelated fields because an event omitted them.

After a timeout, mark the outcome unresolved and inspect current state before deciding what remains to be changed. Do not automatically resend an old multi-field form or restore the old snapshot. The public reference provides no atomic multi-field rollback or version precondition. It identifies upstream permission rejections as update_group_info_failed; inspect the error details rather than assuming every such error has the same cause.

FAQ

Can I clear the description or remove the avatar with an empty value?

This workflow does not assume that. The cited endpoint does not document a clearing convention. Keep those controls unavailable until you have a confirmed contract for the intended operation.

Does a successful group read mean this account can edit it?

No. Read access, provider action support, and group-admin permission are separate checks.

Must I send all three fields?

No. Supply group_id and at least one supported edit field. An untouched form should make no write request.

Next step and sources

Build against Update group info. Before enabling it, test a name-only edit, an unchanged form, a concurrent native edit, an inaccessible image, a permission rejection, and a timeout. These are suggested tests, not reported results.

References checked on 2026-10-23:

• WhatsApp: Make changes to groups
• WhatsApp: Change group admin settings
• UnifyPort: Update group info
• UnifyPort: Standard events