通过 API 修改 WhatsApp 群名称、描述和头像

通过 UnifyPort 修改 WhatsApp 群名称、描述或头像时，调用 POST /v1/accounts/{account_id}/groups/update-info，提交 group_id，以及 name、description、avatar_url 中至少一个字段。该接口要求群管理员权限。只发送操作者打算修改的字段，之后重新读取群资料；不要把打开编辑器时的旧快照当作当前状态。

要点

• 群资料不是 CRM 中的私有标签，保存前应明确修改范围。
• 编辑期间固定所选消息账号和群 ID。
• 提交明确的小范围修改，不要把整个查询响应直接回写。
• 逐字段核对结果；超时或没有收到 webhook 都不能证明修改未发生。

先确定字段，不要混用“设置”操作

WhatsApp 的群资料修改说明介绍了原生应用中的编辑入口。群管理员设置说明还介绍了允许成员编辑群设置的权限。但原生设置不代表 UnifyPort 接口放宽了要求：更新群资料文档明确要求管理员权限。

修改意图	请求字段	应分开处理的内容
修改群名称	name	收件箱中的私有别名
修改群描述	description	客服工单或聊天消息
替换群头像	avatar_url	群成员的个人头像

修改成员权限应使用群管理员提升与降级流程；分发邀请则使用群邀请链接流程。不要把这些动作放进群资料表单。

UnifyPort 提供的是非官方接口。渠道操作矩阵将此写操作映射到 whatsapp，不包括 LINE、Telegram 或独立的 whatsapp-protocol 渠道。能够读取群资料或接收群事件，不代表可以修改群资料。

以最新查询结果初始化编辑器

先在目标消息账号下通过列出群组选择群，并处理分页。保留返回的 id；群的 conversation_id 与 id 相同。名称只是显示值，不是唯一标识。

再通过获取群资料读取当前内容。在应用中分别保存：

1. 最近一次观察到的值。
2. 操作者实际编辑的字段。
3. 提交后重新观察到的值。

如果只改描述，就不要附带旧名称和旧头像。若重新读取发现其他人改了正在编辑的字段，应让操作者重新确认。这是应用层保护措施，不是服务端版本校验。

确认界面应展示消息账号、群和实际变更字段。API key 留在后端，操作者权限也应由后端检查。

只提交用户打算修改的群资料

下面是后端单次请求示例。传入真实选择的标识和服务端保存的 API key。示例刻意只支持非空替换，不定义清空字段或删除头像的行为。

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

edits 只放已编辑字段。头像字段要求公开可访问的图片 URL：使用你有权公开且能控制的图片，不要提交本地文件路径或需要浏览器登录的页面。这是基于 URL 的请求，不是图片上传接口。

文档规定的成功响应是 200 OK 且 data.ok: true，显示成功前要同时检查两者。生产代码还需处理网络异常和非 JSON 响应，保留可获取的 request_id，并避免记录凭据。此处代码仅作示例，未实际执行。

逐字段核对，不要重放整张表单

请求后重新读取同一个群，比较名称和描述的请求值与观察值。头像应检查返回的图片或原生应用，不要要求返回 URL 必须等于提交的源 URL；文档没有承诺两者一致。

标准事件文档说明，group.updated 的 data.changes[] 可以包含多个变更项：

• renamed 携带 name。
• description_changed 携带 description。
• WhatsApp 的 avatar_changed 携带 removed 和可选的 picture_id，不携带图片 URL。

这些事件用于触发核对，不是每次请求都保证收到的回执。按照webhook 投递契约验证签名、处理重复和乱序，不要因为事件省略某字段就清空对应内容。

超时后将结果标记为未确认，先查询当前状态，再决定还有哪些字段需要修改。不要自动重发旧的多字段表单，也不要直接恢复旧快照。公开文档未提供多字段原子回滚或版本前置条件。上游权限拒绝会表现为 update_group_info_failed；应查看错误详情，不能把该错误全部归为同一原因。

常见问题

能否用空值清空描述或删除头像？

本流程不作这种假设。引用的接口没有说明清空约定；在确认目标操作的契约前，不要开放对应按钮。

能读取群资料，就一定能编辑吗？

不能。读取权限、渠道动作支持和群管理员权限是三项独立检查。

必须同时提交三个字段吗？

不需要。提交 group_id 和至少一个受支持的编辑字段即可。表单未修改时不应发送写请求。

下一步与参考资料

按照更新群资料文档实现。上线前测试只改名称、表单未修改、原生端并发编辑、图片不可访问、权限拒绝和网络超时。这些是建议测试项，不是已完成的测试结果。

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

• WhatsApp：修改群资料
• WhatsApp：修改群管理员设置
• UnifyPort：更新群资料
• UnifyPort：标准事件