通过 API 创建 WhatsApp 群组：确认群 ID 与初始成员

通过 UnifyPort 创建 WhatsApp 群组时，调用 POST /v1/accounts/{account_id}/groups/create，传入必填的 name 和可选的 members 数组。在这个创建请求中，WhatsApp 初始成员使用电话号码标识。成功响应返回 data.id，并不返回成员加入明细。应立即保存群 ID，再读取群资料和成员列表，最后才启动依赖这些结果的自动化。

要点

• 创建群组、邀请他人和管理现有成员是不同操作。
• 初始 members 使用电话号码，后续成员管理采用另一套标识契约。
• 公开事件目录没有 group.created，不要等待这个回调来结束流程。
• 没收到响应代表结果不确定；自动重试创建可能产生另一个群。

先读创建契约，再设计表单

创建群组参考定义了以下契约。UnifyPort 为已连接的消息账号提供非官方接口，这里不是 WhatsApp Cloud API 端点。渠道操作支持表目前仅将创建群组映射到 whatsapp，不包括 LINE、Telegram 或独立的 whatsapp-protocol 渠道。

值	含义	不能替代它的值
路径中的 account_id	执行创建的消息账号	工作空间 ID
请求中的 name	必填群名称，最多 100 个字符	唯一资源标识
请求中的 members	可选初始成员；WhatsApp 使用电话号码	直接复制的成员 LID 数组
响应中的 data.id	新创建的群 ID	邀请码或操作 ID

创建响应的 data 只包含新群 ID，没有逐人加入结果。应用应分别保存“希望加入的初始成员”和“后来实际观察到的成员”。

WhatsApp 的官方成员管理说明分别介绍添加成员、邀请成员，以及启用审批后查看待处理申请。这些用户流程不能相互替代，更不能都视为“已加入”的证据。如果希望用户自行决定是否进入现有群，应使用邀请链接流程，而不是再建一个群。

准备一次经过确认的创建请求

按照账号生命周期参考，先确认所选消息账号已授权，且运行状态为 running。API Key 只保存在后端，操作员权限也要在后端检查。

建议应用实施以下保护：

1. 确认页显示所选账号、拟定群名和参与者。只添加知情且预期参与的人。
2. 发送前保存本地创建意图。操作员及预期参数记录在自己的应用中，不要作为额外 API 字段发送。
3. 后端阻止同一意图并发提交；仅禁用浏览器按钮并不够。
4. 只发送一次请求，先保存结果，再允许后续操作。

以下是根据已确认输入构造请求的服务端 JavaScript 示例，未在本任务中执行，也没有自动重试：

async function createGroupOnce({ apiKey, accountId, name, phones }) {
  if (!apiKey || !accountId || typeof name !== 'string' || !name.trim()) {
    throw new Error('Missing credential, account, or group name');
  }
  const body = { name };
  if (phones !== undefined) {
    if (!Array.isArray(phones) ||
        phones.some(p => typeof p !== 'string' || !/^[0-9]+$/.test(p))) {
      throw new Error('Use confirmed phone-number strings');
    }
    body.members = phones;
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/create`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

按文档格式使用实际确认过的电话号码。数字检查只是本地输入保护，不代表号码对应的用户一定能加入。还需校验文档规定的群名长度。生产代码必须处理网络异常和非 JSON 响应，在可用时安全保存 request_id，并避免记录凭证或参与者电话号码列表。

将群 ID 与成员核验分开

收到 200 OK 且存在 data.id 后，将返回 ID 与所选账号、本地创建意图一起持久化。随后调用获取群组，将该 ID 作为 group_id。

查看参与者时，调用列出会话成员，将群 ID 作为 conversation_id，并使用 type=group。按照 has_more 和 next_cursor 完成分页；某人没有出现在第一页，不代表已经完成成员核对。原样保留返回的 peer_id 与 role，不要用电话号码推算 LID。

后续管理群成员采用独立契约：每次请求包含单个 member_id 和一个动作，WhatsApp 使用成员列表以 peer_id 返回的 LID。不要把创建请求直接复用于成员管理。需要分配管理员时，继续参考管理员角色调整指南。

观察结果	建议的应用状态	下一步
成功响应且已保存群 ID	已创建，成员尚未核实	读取群资料及全部成员分页
群可读取，但预期成员尚未核清	群存在，成员待复核	检查身份映射或在原生应用核对
超时、响应不可解析或缺少预期 ID	创建结果未确定	先核对，再考虑重新创建

这些是应用内部状态，不是新增的 API 响应值。

恢复时避免重复建群

标准事件目录没有 group.created，创建成功不承诺发出这样的回调。group.updated 也不是每次创建请求必定收到的回执。

如果响应丢失，在同一账号下检查群组列表，并完成分页。该列表包括尚未产生消息的已加入群组。结合可用资料与原生应用调查；群名相同不足以证明是同一个群，读取失败或分页不完整也不足以证明创建失败。

公开创建契约没有文档化的幂等键。本地意图记录可以减少应用自身的重复提交，但不能让上游操作获得恰好一次的保证。结果未明时，暂停相关邀请及自动消息；再次创建前要求操作员复核。

常见问题

可以省略 members 吗？

可以，API 将 members 定义为可选字段。但这只是请求结构的属性，不保证每个上游账号的具体行为，仍须核对实际结果。

HTTP 成功是否表示所有人都已加入？

不是。文档返回的是群 ID，不是逐人成员结果，应单独读取成员列表。

创建时能一起传群描述和头像吗？

它们不是文档中的创建字段。创建后使用独立的群资料编辑流程。

下一步与资料来源

按照创建群组参考实现。上线前使用自己控制的账号测试重复点击、响应丢失、同名群、成员分页及无法加入的参与者。这些是建议测试项，不是已完成的测试结果。

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

• WhatsApp：添加和移除群成员
• UnifyPort：创建群组
• UnifyPort：列出会话成员
• UnifyPort：标准事件