通过 API 退出 WhatsApp 群组：安全操作流程

要通过 UnifyPort 让已连接的 WhatsApp 账号退出群组，请调用 POST /v1/accounts/{account_id}/groups/leave，在 JSON 正文中传入 group_id。这个操作改变的是所选账号的群组成员关系，不是替所有人删除群组，也不会清空客服数据库。发送请求前，先确认目标，并停止应用中针对该群组的排队回复。

核心要点

• 同时选择消息账号和群组；群名称不是唯一标识。
• 退群、移除其他成员、关闭通知及清理已存消息是不同操作。
• 当前 UnifyPort 退群操作仅支持 whatsapp，不能按群组读取能力推断写入能力。
• 超时意味着结果未确认；先观察当前状态，再决定是否需要再次请求。

先确认需要的是退群

WhatsApp 的官方退出与删除说明区分了保留聊天记录的 Exit group，以及从本地移除记录的 Exit and delete for me。不要把两者合并为一个含糊的“移除”按钮。如果群组属于社群，操作前还应查看成员退群说明，单独评估社群相关影响。

操作者的目的	应采用的流程
让已连接账号不再参与群组	明确的退群操作
减少通知干扰	静音通知
保留成员身份，但停止自动回复	应用自身的暂停控制
修改其他成员的管理员身份	独立的角色变更操作
删除客服系统保存的内容	自身的数据保留与删除流程

通知设置可参阅共享收件箱中的静音与屏蔽区别。如果群组仍需要管理员，先按管理员提升与降级指南单独处理职责交接，再确认是否退群。交接和数据清理都不包含在退群请求内。

确认前固定账号与群组

对所选账号调用列出群组。该接口返回已加入的群组，包括没有发过消息的安静群组；返回字段包含 id、conversation_id 和 name，群组的 conversation_id 与 id 相同。根据 has_more 和 next_cursor 完成分页，不要只查看第一页。

原样保存返回的 ID。在确认对话框中同时显示账号身份和群名称，将对应 ID 保留在服务端。不同账号中的同名群组不能共用一个操作目标。

建议在应用中设置以下保护：

1. 要求有权限的操作者确认这一次具体退群。
2. 暂停该账号与群组组合的新自动发送，检查已排队或正在发送的任务。
3. 保持签名 webhook 接收器运行；暂停发送不需要关闭入站存储。
4. 在自己的审计记录中保存操作者、目标和原因，不要把它们当成 API 字段发送。

这些是应用设计建议，不是接口额外提供的保证。

发送一次退群请求

UnifyPort 提供的是非官方接口。退出群组参考记录了下面的请求结构，以及包含 data.ok: true 的 200 OK 成功响应。渠道动作矩阵将该操作仅映射到 whatsapp，不包括 LINE、Telegram 或独立的 whatsapp-protocol 渠道。

下面是服务端 JavaScript 示例。环境变量应来自已确认的选择和密钥存储。示例只请求一次，不自动重试：

const accountId = process.env.UNIFYPORT_ACCOUNT_ID;
const groupId = process.env.WHATSAPP_GROUP_ID;
const apiKey = process.env.UNIFYPORT_API_KEY;
if (!accountId || !groupId || !apiKey) {
  throw new Error('Missing confirmed target or credential');
}

const response = await fetch(
  `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/leave`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ group_id: groupId })
  }
);
const outcome = await response.json();
if (!response.ok || outcome.data?.ok !== true) {
  throw new Error('Exit not confirmed; review the response');
}

生产调用方还需要安全保存 HTTP 状态和 request_id，处理网络及解析失败，并在运行代码之前检查操作者权限。没有收到响应，不代表 WhatsApp 已拒绝操作。

核对结果，不要把退群当成删除

成功后刷新该账号已加入的群组列表。超时后保持“结果未确认”，检查当前成员关系；如果 API 读取无法得出结论，则通过原生应用核实。读取失败或分页不完整不能证明已退群。不要自动重新加入或再次发送请求来补偿。

在人工处理完成前，继续暂停相关回复任务。延迟到达的入站事件不能悄悄恢复发送。退群也不会清除应用已保存的消息；数据保留策略应独立执行。

如果使用群组事件提示状态核对，按webhook 投递契约验证签名并处理重复事件。不要依赖并不存在于此契约中的 group.left 事件，也不要承诺每次退群都有回调。

常见问题

这会替所有人删除群组吗？

不会。文档中的操作是让已连接账号退出，不是解散群组或删除数据库的 API。

能用移除成员来退群吗？

已连接账号退出应使用专用退群操作。管理其他成员是另一种请求，输入也不同。

能列出 LINE 群组，就能调用这个接口退出吗？

不能。读取和写入支持范围不同，应核对动作矩阵，而不是只看群组是否出现在列表中。

下一步与来源

按照退出群组参考实现。开放操作前，使用自己控制的账号检查选错账号、分页、重复点击、排队回复和网络结果未确认等场景。以上是建议测试，不是已完成的测试报告。

来源核验日期：2026-10-22。

• WhatsApp：管理员退出与删除群组
• WhatsApp：成员退出群组
• UnifyPort：退出群组
• UnifyPort：渠道动作支持