Change WhatsApp Group Admins via API: Promote vs Demote

To change a WhatsApp group admin through UnifyPort, call POST /v1/accounts/{account_id}/groups/members with group_id, the member’s LID in member_id, and action: "promote" or "demote". Each call targets one member and one action. Demotion removes an admin role; it is not the remove action. Read current membership first, and keep the group creator outside an ordinary demotion workflow.

Key takeaways

• Select the account, group, and member together; a display name is not an identifier.
• Use the LID returned as peer_id by List conversation members, not a phone-number-derived value.
• Distinguish member, admin, and superadmin before enabling a role-change button.
• Recheck state after the request; do not automatically send an opposite action after a timeout.

Decide which role transition you mean

WhatsApp’s official group-admin guide describes dismissing an admin and states that the group creator cannot be removed and remains an admin unless they exit. An API integration does not create an exception to that rule.

The following table is a recommended application policy, not a promise that the platform accepts every request:

Observed role	Operator intention	Application decision
member	Make this participant an admin	Offer promote after permission checks
admin	Keep the participant, remove admin privileges	Offer demote after confirmation
superadmin	Remove creator privileges	Stop this workflow; explain the creator boundary
Already at the intended role	Repeat the same change	Refresh the display rather than sending another request
Missing, unknown, or incomplete membership	Change a role anyway	Read again or require manual review

This is not an admission workflow. To decide whether someone may enter the group, use the WhatsApp join-request approval queue. To distribute an invitation, use the separate group invite-link flow. Neither operation appoints an administrator.

Capture a current member selection

Use List conversation members under the selected messaging account. Supply the group’s conversation_id, follow cursor pagination, and retain the chosen item’s peer_id and role. The documented roles are member, admin, and superadmin; the last means owner or creator.

An illustrative read, using backend environment variables populated from your actual selection:

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

If data.has_more is true, continue with the returned data.next_cursor. A participant missing from the first page is not proof that they left. Preserve the LID exactly; do not manufacture one from a phone number, display name, or a differently formatted event participant ID.

Before dispatch, verify that your operator is allowed to administer this account and group, and that the connected WhatsApp account has the required group authority. Workspace API access alone is not group-admin permission. Keep API keys on the server.

Submit one explicit change

The Manage group members reference documents four actions: add, remove, promote, and demote. For role changes, use only the last two, with singular member_id—not the member_ids array used by join-request approval.

This illustrative JavaScript builds only the request body from a previously selected membership record. It does not perform authorization or make a network call:

function roleChangeBody(groupId, selectedMember, action) {
  const expectedRole = { promote: 'member', demote: 'admin' };
  if (!Object.hasOwn(expectedRole, action) ||
      selectedMember?.role !== expectedRole[action]) {
    throw new Error('Refresh membership before changing this role');
  }
  if (!groupId || !selectedMember?.peer_id?.endsWith('@lid')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  return {
    group_id: groupId,
    member_id: selectedMember.peer_id,
    action
  };
}

Send the JSON from your backend to the documented endpoint with X-Api-Key. The suffix check is only a local guard, not proof of identity or permission. The UI should show the exact group, participant, and intended change before confirmation. Do not infer the target from whichever row is currently first in a changing member list.

UnifyPort supplies an unofficial interface for the connected account. Its provider action matrix currently maps this write operation to whatsapp only, not LINE, Telegram, or the separate whatsapp-protocol provider. Reading members or receiving group events on another channel does not imply role-writing support.

Verify the result without inventing a transaction

The endpoint documents 200 OK with data.ok: true. Preserve the HTTP outcome and request_id, then read membership again to show the observed role separately from the operator’s intention.

Recommended safeguards:

1. Serialize your application’s changes for the same account, group, and member.
2. Recheck the selected role before dispatch; another admin may have changed it since the dialog opened.
3. On a timeout, mark the result unresolved and inspect current membership. Do not automatically resend or send the opposite action as compensation.
4. Do not treat a multi-person handoff as atomic. If transferring responsibilities, confirm the new admin’s observed role before separately considering a demotion.

The standard group.updated event can contain data.changes[] entries with kind: "promoted" or "demoted" and members[]. Use it to trigger reconciliation, not as a guaranteed per-request receipt. Event participant IDs are not automatically valid LIDs for a subsequent write. If consuming webhooks, follow the signature and delivery reference, verify before trusting the body, and tolerate duplicate or out-of-order deliveries.

FAQ

Does demote remove someone from the group?

No. Role demotion and membership removal are separate actions. Do not wire a “Dismiss admin” button to remove.

Can this change the group creator’s role?

Do not offer that through this workflow. WhatsApp says the creator remains an admin unless they exit; UnifyPort exposes that role as superadmin in the member list.

Can I change several admins in one request?

Not with this endpoint. It accepts one member_id and one action per call. An application batch must track each result separately.

Next step and sources

Start with List conversation members, then add role controls against Manage group members. Test pagination, a creator target, stale role selection, missing permissions, and an uncertain network result before enabling production changes. These are proposed checks, not reported test results.

References checked on 2026-10-17:

• WhatsApp: How to manage group admins
• UnifyPort: Manage group members
• UnifyPort: Standard webhook events