Remove a WhatsApp Group Member via API: IDs and Verification

To remove an existing WhatsApp group member through UnifyPort, send POST /v1/accounts/{account_id}/groups/members with group_id, action: "remove", and the member’s LID in member_id. Obtain that LID from peer_id in the group member list. Each request targets one person. Preserve the response and read membership again rather than treating a disappearing UI row as proof of removal.

Key takeaways

• Removing a participant is different from demoting an admin, rejecting a pending request, or leaving the group yourself.
• Select the messaging account, group, and member together. Never construct a LID from a phone number.
• Require a reviewed removal decision, not an automatic response to an unfamiliar name.
• A timeout leaves an uncertain outcome; it is not permission for repeated removal requests.

Match the control to the intended outcome

WhatsApp’s official member-management guide presents removal as selecting a particular participant in group information and confirming Remove. An API control should retain that explicit target and confirmation, rather than hiding the action behind a generic “clean up” button.

Intended outcome	Appropriate operation
Remove an existing participant	Member-management action remove
Keep the person but remove admin privileges	Separate action demote
Decline someone who has not yet joined	Reject their pending join request
Disconnect the connected account from the group	Leave group
Hide a row in your own application	Local UI change, not a membership mutation

Use the admin role-change guide for demotion. For a pending applicant, use the join-request approval queue. Those workflows must not share an ambiguous Remove button.

What the removal review card must show

Before enabling the destructive control, read List conversation members under the selected account, passing the group’s ID as conversation_id and type=group. Follow data.has_more and data.next_cursor until the relevant check is complete. A person missing from the first page is not necessarily absent.

Retain the returned peer_id, display_name, and role. The documented roles are member, admin, and superadmin, with the last identifying the owner or creator. Display names help the operator recognize someone; they are not identifiers.

Recommended application safeguards—not additional API requirements—are:

• Show the exact group and participant alongside the connected account before confirmation.
• Check both your application’s operator permissions and the connected account’s authority to manage the group. API-key possession does not establish group authority.
• Keep superadmin, the connected account itself, and unresolved identities outside an ordinary participant-removal flow; route them to separate review or the appropriate operation.
• Re-read stale selections, and prevent concurrent removal submissions for the same account, group, and member in your application.

If the target cannot be resolved to a returned WhatsApp LID, stop. Do not replace it with a phone number, a display name, or an event participant identifier in another format.

One reviewed member, one request

The Manage group members reference accepts singular member_id, not the member_ids array used for join-request decisions. UnifyPort provides an unofficial interface; the current provider action matrix limits this operation to whatsapp, not LINE, Telegram, or whatsapp-protocol.

This illustrative JavaScript builds the request body only. Supply a confirmed group ID and the selected record from the member list. It does not implement permission checks or perform a network call.

function removalBody(groupId, selectedMember) {
  if (!groupId || !/^\d+@lid$/.test(selectedMember?.peer_id ?? '')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  if (!['member', 'admin'].includes(selectedMember.role)) {
    throw new Error('This target requires separate review');
  }
  return {
    group_id: groupId,
    action: 'remove',
    member_id: selectedMember.peer_id
  };
}

The role guard is a local safety policy. The LID format check does not prove identity or permission. Send the JSON from your backend to the endpoint above with X-Api-Key and Content-Type: application/json; keep credentials out of browsers and logs. There is no documented multi-member removal transaction: track each approved participant separately if your application offers a batch UI.

Judge the evidence, not the animation

Keep the operator’s intention, HTTP result, and observed membership separate:

Evidence	What your application can say
200 OK with data.ok: true	The API returned success; refresh membership
Successful, completed membership read without the selected LID	The person was not observed in that read; record its time
Failed or incomplete membership read	Verification remains unresolved
Timeout or unreadable mutation response	Request outcome remains uncertain; investigate before another write

The documented group.updated event can contain data.changes[] with kind: "member_removed" and members[]. Treat it as a reason to reconcile, not a guaranteed request-specific receipt. Verify webhook signatures using the delivery contract before trusting events. Do not assume event participant IDs can be copied directly into another member-management request.

Record request_id when available for troubleshooting. Do not use it as an idempotency key. After an uncertain result, inspect current membership and require renewed review before another mutation. Automatically sending add as compensation is a new membership decision, not a rollback guarantee.

FAQ

Can I use the phone numbers from a group-creation request?

No. This operation documents WhatsApp member LIDs returned as peer_id. Initial group creation has a different identifier contract.

Does removal also delete stored messages or permanently prevent rejoining?

Do not promise either from this API. Its contract is member management, not history erasure or a permanent admission policy. Handle your own retention and future admission decisions separately.

What should I test before enabling removal?

Use controlled accounts to test duplicate names, a target on a later member page, a stale selection, insufficient authority, a lost response, and a failed verification read. These are proposed tests, not reported results.

Next step and sources

Implement the reviewed selection against List conversation members, then connect the destructive control to Manage group members.

References checked on 2026-11-01:

• WhatsApp: How to add and remove group members
• UnifyPort: Manage group members
• UnifyPort: Group update events