通过 API 移除 WhatsApp 群成员：标识选择与结果核验

通过 UnifyPort 移除已有 WhatsApp 群成员，应调用 POST /v1/accounts/{account_id}/groups/members，传入 group_id、action: "remove"，以及放在 member_id 中的成员 LID。LID 应来自群成员列表返回的 peer_id。每次请求只针对一个人。保存响应后重新读取成员状态，不要把界面中一行消失当成移除成功的证据。

要点

• 移除成员、撤销管理员身份、拒绝待审批申请，以及消息账号自己退群，是不同操作。
• 同时锁定消息账号、群组和成员，不要用手机号拼出 LID。
• 移除前必须确认对象和意图，不应因昵称陌生就自动移除。
• 请求超时意味着结果不确定，不意味着可以反复提交。

让按钮对应真实意图

WhatsApp 的官方成员管理说明将移除操作描述为：在群资料中选中具体成员，再确认移除。API 界面也应保留明确的目标和确认步骤，而不是把危险动作藏在“清理”按钮后。

操作目的	对应操作
移除已入群成员	成员管理 remove
保留成员，只撤销管理员权限	独立的 demote
拒绝尚未入群的申请人	拒绝待审批申请
让当前连接的账号离开群	退群
仅隐藏自己系统中的一行	本地界面变化，不是群成员变更

撤销管理员身份请参考管理员升降级指南；处理尚未入群的人请使用入群申请审批队列。这些流程不能共用含义模糊的“移除”按钮。

移除确认卡片需要展示什么

启用危险操作前，在选定消息账号下调用列出会话成员，将群 ID 作为 conversation_id，并传入 type=group。根据 data.has_more 和 data.next_cursor 继续分页，直到完成所需核验。第一页没有找到某人，不代表他不在群中。

保留返回的 peer_id、display_name 和 role。文档中的角色为 member、admin、superadmin，最后一个表示群主或创建者。显示名称仅用于识别，不能作为操作标识。

以下是建议的应用保护措施，不是新增的 API 必填要求：

• 确认前同时显示消息账号、目标群和成员。
• 检查操作员在你系统中的权限，以及连接账号管理该群的权限。持有 API Key 不等于拥有群管理权限。
• 不让 superadmin、连接账号自身或身份尚未确认的对象进入普通移除流程；转交单独审核或使用对应操作。
• 重新读取过期的成员选择，并在应用后端阻止同一账号、群、成员的并发移除提交。

无法将目标对应到返回的 WhatsApp LID 时，应停止操作。不要改用手机号、显示名称，或其他格式的事件参与者标识。

一个经确认的成员，一次请求

管理群成员参考接受单数 member_id，而不是入群审批使用的 member_ids 数组。UnifyPort 提供非官方接口；当前渠道动作能力表仅将此操作映射到 whatsapp，不包括 LINE、Telegram 或 whatsapp-protocol。

下面的 JavaScript 示例只构造请求体。传入已确认的群 ID 和从成员列表选中的记录；它不执行权限检查，也不发送网络请求。

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
  };
}

角色检查是本地安全策略；LID 格式检查不能证明身份或权限。由后端向前述端点发送 JSON，使用 X-Api-Key 和 Content-Type: application/json，不要将密钥放进浏览器或日志。文档没有定义多人移除事务；即使界面提供批量操作，也要分别记录每个经批准对象的结果。

判断证据，不要看界面动画

将操作意图、HTTP 结果和实际观察到的成员状态分开保存：

证据	应用可以得出的结论
200 OK 且 data.ok: true	API 返回成功，接下来刷新成员列表
成功完成成员读取，未发现所选 LID	该次读取未观察到此人，同时记录读取时间
成员读取失败或未完成	核验仍未解决
写请求超时或响应不可读	请求结果不确定，再次写入前先调查

文档中的 group.updated 事件可在 data.changes[] 中包含 kind: "member_removed" 和 members[]。将它作为重新核验的信号，不要当成每次请求都保证产生的回执。信任事件前，按投递契约验证签名。事件中的参与者标识也不一定能直接用于下一次成员管理请求。

有 request_id 时保存它用于排查，但不要当成幂等键。结果不确定时，检查当前成员状态，再次变更前要求重新审核。自动发送 add 作为补偿是新的成员变更决定，不是有保证的回滚。

常见问题

能使用创建群时的手机号吗？

不能。此操作要求成员列表 peer_id 返回的 WhatsApp LID；创建群的初始成员标识是另一套契约。

移除是否同时删除已存消息，或永久禁止再次入群？

不要根据这个 API 作出这些承诺。它管理群成员，不是历史内容删除或永久准入策略。自行管理数据保留与后续入群决策。

上线前应测试什么？

使用受控账号测试重名、目标位于后续分页、选择已过期、权限不足、响应丢失及核验读取失败。这些是建议测试，不是已执行结果。

下一步与参考资料

先基于列出会话成员实现确认选择，再将危险操作接入管理群成员。

资料核对日期：2026-11-01。

• WhatsApp：添加和移除群成员
• UnifyPort：管理群成员
• UnifyPort：群更新事件