通过 API 设置 WhatsApp 群管理员：提升与取消权限

通过 UnifyPort 更改 WhatsApp 群管理员，调用 POST /v1/accounts/{account_id}/groups/members，传入 group_id、以成员 LID 为值的 member_id，以及 action: "promote" 或 "demote"。每次请求只处理一名成员和一个动作。取消管理员权限不等于 remove 移出群聊。先读取当前成员状态，并将群创建者排除在普通降级流程之外。

要点

• 同时选定消息账号、群和成员，不能用显示名称代替标识符。
• 使用成员列表返回的 peer_id 中的 LID，不要由手机号拼接。
• 在启用按钮前区分 member、admin 和 superadmin。
• 请求后重新读取状态；超时后不要自动执行相反动作。

先确定要改变哪一种角色

WhatsApp 的官方群管理员说明介绍了取消管理员的方法，并明确群创建者不能被移除，除非自行退出，否则会保留管理员身份。API 接入不会改变这一规则。

以下是建议的应用策略，不是平台一定接受请求的保证：

当前角色	操作意图	应用应如何处理
member	设为管理员	权限检查后提供 promote
admin	保留成员身份，取消管理权限	确认后提供 demote
superadmin	取消创建者权限	停止此流程并解释限制
已是目标角色	再做一次相同变更	刷新显示，不再发请求
成员信息缺失、未知或不完整	仍然改变角色	重新读取或交人工核实

这不是入群审批流程。决定某人能否加入群，请使用 WhatsApp 入群申请审批队列；需要分发邀请，则使用独立的群邀请链接流程。这两种操作都不会任命管理员。

保存当前选中的成员信息

在选定消息账号下调用获取会话成员列表，传入群的 conversation_id，按 cursor 分页，并保存选中项的 peer_id 和 role。文档中的角色为 member、admin、superadmin，最后一项表示群所有者或创建者。

下面是示意读取请求；环境变量应由后端根据实际选择填充：

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"

如果 data.has_more 为真，使用返回的 data.next_cursor 继续读取。第一页没有某人，不能证明对方已经退群。原样保留 LID，不要从手机号、显示名称或不同格式的事件成员 ID 推算。

发送前，验证操作员有权管理这个账号和群，并确认连接的 WhatsApp 账号具有所需群权限。工作空间 API 访问权不等于群管理员权限。API Key 必须留在服务端。

每次提交一个明确动作

管理群成员文档列出 add、remove、promote、demote 四种动作。角色变更只使用后两项，并传单数 member_id，而不是入群审批接口的 member_ids 数组。

下面的 JavaScript 仅从已选成员记录构造请求体，不执行权限认证，也不发送网络请求：

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

后端使用 X-Api-Key 将 JSON 发至文档中的接口。后缀检查只是本地防误用检查，不能证明身份或权限。确认界面应明确显示群、成员和目标动作，不要从实时变化列表的第一行动态推断操作对象。

UnifyPort 为连接的账号提供非官方接口。当前渠道动作支持矩阵仅将此写操作映射到 whatsapp，不包括 LINE、Telegram 或独立的 whatsapp-protocol。能够读取某渠道的成员或接收群事件，不代表可以修改该渠道的角色。

核对结果，不假设存在事务

接口文档的成功响应为 200 OK 和 data.ok: true。保存 HTTP 结果及 request_id，然后重新读取成员信息，将实际观察到的角色与操作员意图区分展示。

建议采取以下保护措施：

1. 对同一账号、群和成员的应用内变更串行处理。
2. 发送前复核角色；确认框打开后，其他管理员可能已经修改了它。
3. 超时后将结果标记为待核实，读取当前成员信息。不要自动重发，也不要用相反动作补偿。
4. 不要把多人交接当成原子事务。交接职责时，先确认新管理员的实际角色，再单独考虑是否取消另一人的权限。

标准 group.updated 事件的 data.changes[] 可包含 kind: "promoted" 或 "demoted" 及 members[]。可以用它触发重新核对，但不要把它当成每个请求必有的回执。事件成员 ID 不一定能直接作为后续写入所需的 LID。消费 webhook 时遵循签名与投递文档，先验证再信任正文，并处理重复或乱序投递。

常见问题

demote 会把成员踢出群吗？

不会。角色降级和移除成员是不同动作。“取消管理员”按钮不能调用 remove。

可以更改群创建者的角色吗？

不要在此流程中提供该操作。WhatsApp 说明创建者除非自行退出，否则保留管理员身份；UnifyPort 成员列表将其表示为 superadmin。

一次请求可以更改多名管理员吗？

此接口不可以。一次仅接受一个 member_id 和一个动作。应用层批量操作必须分别记录每项结果。

下一步与参考资料

先实现获取会话成员列表，再按管理群成员添加角色控制。上线前测试分页、创建者目标、过期角色选择、权限不足和网络结果不明等情形。这些是建议测试项，不是已执行的测试结果。

资料核对日期：2026-10-17。

• WhatsApp：管理群管理员
• UnifyPort：管理群成员
• UnifyPort：标准 webhook 事件