跳转到主要内容
WhatsApp 群组可将多名参与者汇聚到一个共享对话中。 YCloud 当前的 Groups API 侧重于群组的创建和管理。在构建基于群组的业务体验之前，请确认此范围是否符合您的用例。
YCloud 当前不支持通过 Messages API 向群组内发送消息，群组对话也不会出现在 Inbox（收件箱）中。向个人发送包含邀请链接的消息与向群组发送消息并不相同。

​
检查号码资格

当前的 YCloud Groups 指南 要求具备官方商业账户（Official Business Account）以及支持的 Cloud API 号码。该功能不适用于 Business App 号码和多方案对话（Multi-solution Conversations）。 您的 YCloud 账户必须拥有对该号码的访问权限。群组功能的可用性仍受平台及 YCloud 的资格审核约束；仅拥有 API Key 并不代表号码具备相应资格。 本指南记录了最多 8 名参与者的小型群组规范。在围绕群组数量、参与者上限或其他容量假设进行方案设计之前，请查阅最新指南。

​
YCloud 支持的功能

当前 API 支持：
  • 创建、列出、获取和删除群组。
  • 获取和重置邀请链接。
  • 向个人发送已获批准的邀请链接模板。
  • 列出、批准和拒绝加群请求。
  • 移除参与者。
  • 更新群主题和描述。
  • 接收群组生命周期、参与者、设置和状态事件。
YCloud OpenAPI 规范 定义了确切的操作。它明确区分了向个人发送邀请与向群组发送消息。
创建群组，在 webhook 中接收邀请链接，并邀请 WhatsApp 用户。

Meta's invitation model: create the group, receive the invite link through the lifecycle webhook, then invite WhatsApp users. This diagram does not imply YCloud outbound group-message support.

来源：Meta 官方示例。

​
成员加入基于邀请流程

客户通过邀请自主选择是否加入。如果需要审核，则由您的企业审核加群请求。 请勿认为知晓某人的电话号码即可直接将其加入群组。在分享链接之前，请先说明群组的目的以及参与人员。 请将邀请链接视为具有访问权限敏感性的信息。请评估未受限的链接是否可能被转发给目标受众之外的人员，并明确何时应当重置该链接。

​
等待最终结果

部分管理操作以异步方式完成。即时响应仅代表确认收到请求，最终结果通过 Webhook 上报。 在发送邀请之前，请先确认群组已成功创建。在成员发生变更后，请确认受影响的具体参与者，而不是假定整个请求都已成功。 即使 Inbox 中未显示对话，集成系统仍可能会收到入站群组消息事件。该事件并不代表支持出站群组消息发送。

​
安全的初次建群工作流

  1. 确认发信号码的 OBA 状态及 Groups 使用资格。
  2. 创建具有明确主题的群组，并选择自动加入或需要批准加入。
  3. 存储创建请求 ID。包含 status: "pending" 的响应并不代表最终的群组已建立。
  4. 等待群组创建成功的生命周期事件，并存储其群组 ID 和邀请链接。
  5. 向符合条件的个人收件人发送已获批准的邀请链接消息模板。
  6. 如果需要批准，请审核每个加群请求并执行批准或拒绝。
  7. 在将某人视为正式成员之前，请根据参与者处理结果确认其成员资格。
邀请送达并不意味着收件人已打开链接、请求访问或已加入。如果某次批准操作返回混合结果，请分别处理各个结果。

​
标识符与记录的限制

请将群组 ID 视为不透明且区分大小写的标识符。请勿对其进行规范化或解码。创建请求 ID、群组 ID、邀请消息 ID 和加群请求 ID 是不同的标识符，不可互换。

​
保护成员变更

重置邀请链接会使之前的链接失效。请同步更新仍在使用旧链接的邀请或受控分发渠道；持有旧链接的收件人可能将无法再加入。 为群组生命周期、参与者、设置和状态更新配置 YCloud Webhook 端点。YCloud 会管理相关的平台订阅；您的应用程序仍需验证 Webhook 签名并安全处理重复事件。 保留关于操作请求者、受影响群组、请求 ID 和最终结果的审计记录。请勿在公开仪表板中记录私有邀请链接。

​
决定是否继续

如果支持的管理操作符合您的需求，请参考群组集成指南。 如果您的核心需求是在 YCloud Inbox 中或通过 Messages API 进行双向群组消息收发，请在实施前与 YCloud 确认其可用性。请勿围绕不受支持的功能向客户做出承诺。

​
常见问题

请等待最终的创建结果。请求 ID 并非群组 ID 或邀请链接。请保存成功生命周期事件中的群组信息，然后向符合条件的个人收件人发送获批的邀请。
送达仅确认邀请已到达收件人。客户仍需要打开链接并选择加入；需要审批的群组还需要获得成功的审批结果。请检查加入请求和参与者事件，而不要将邀请的送达状态直接视为已成为成员。
首先检查链接是否已被重置。重置会使之前的链接失效，因此请使用当前链接并更新受控的分发点。如果链接是最新的，请检查群组是否已满或参与者之前是否已被移出。在创建重复群组之前，请先确认群组和参与者的状态。请参阅 Meta 的群组常见问题。
在当前记录的 YCloud 范围内不支持。群组会话不会出现在 Inbox 中，Messages API 也不支持发送出站群组消息。群组管理端点和入站群组事件并不构成完整的双向群聊产品。
Meta 仍可能会传递在删除前收到的消息或状态事件。这些延迟的事件并不意味着群组已被重新创建。请保留群组 ID 和删除结果，安全地处理历史事件，不要仅根据迟到的 Webhook 重新发起邀请。请参阅 Meta 的群组常见问题。