> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp 群组

> 了解仅限邀请的群组、适用资格，以及当前 YCloud 群组管理与群组消息发送之间的边界。

WhatsApp 群组可将多名参与者汇聚到一个共享对话中。

YCloud 当前的 Groups API 侧重于群组的创建和管理。在构建基于群组的业务体验之前，请确认此范围是否符合您的用例。

<Warning>
  YCloud 当前不支持通过 Messages API 向群组内发送消息，群组对话也不会出现在 Inbox（收件箱）中。向个人发送包含邀请链接的消息与向群组发送消息并不相同。
</Warning>

## 检查号码资格

当前的 [YCloud Groups 指南](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-groups) 要求具备官方商业账户（Official Business Account）以及支持的 Cloud API 号码。该功能不适用于 Business App 号码和多方案对话（Multi-solution Conversations）。

您的 YCloud 账户必须拥有对该号码的访问权限。群组功能的可用性仍受平台及 YCloud 的资格审核约束；仅拥有 API Key 并不代表号码具备相应资格。

本指南记录了最多 8 名参与者的小型群组规范。在围绕群组数量、参与者上限或其他容量假设进行方案设计之前，请查阅最新指南。

## YCloud 支持的功能

当前 API 支持：

* 创建、列出、获取和删除群组。
* 获取和重置邀请链接。
* 向个人发送已获批准的邀请链接模板。
* 列出、批准和拒绝加群请求。
* 移除参与者。
* 更新群主题和描述。
* 接收群组生命周期、参与者、设置和状态事件。

[YCloud OpenAPI 规范](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml) 定义了确切的操作。它明确区分了向个人发送邀请与向群组发送消息。

<Frame caption="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.">
  <img src="https://mintcdn.com/lchnan/3gBf_HfRdWRqXdyx/images/whatsapp-platform/meta-groups-invitation.png?fit=max&auto=format&n=3gBf_HfRdWRqXdyx&q=85&s=a5d7f27301641076470c8faf9a801fd9" alt="创建群组，在 webhook 中接收邀请链接，并邀请 WhatsApp 用户。" className="bg-white" width="606" height="391" data-path="images/whatsapp-platform/meta-groups-invitation.png" />
</Frame>

来源：[Meta 官方示例](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/)。

## 成员加入基于邀请流程

客户通过邀请自主选择是否加入。如果需要审核，则由您的企业审核加群请求。

请勿认为知晓某人的电话号码即可直接将其加入群组。在分享链接之前，请先说明群组的目的以及参与人员。

请将邀请链接视为具有访问权限敏感性的信息。请评估未受限的链接是否可能被转发给目标受众之外的人员，并明确何时应当重置该链接。

## 等待最终结果

部分管理操作以异步方式完成。即时响应仅代表确认收到请求，最终结果通过 Webhook 上报。

在发送邀请之前，请先确认群组已成功创建。在成员发生变更后，请确认受影响的具体参与者，而不是假定整个请求都已成功。

即使 Inbox 中未显示对话，集成系统仍可能会收到入站群组消息事件。该事件并不代表支持出站群组消息发送。

## 安全的初次建群工作流

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

邀请送达并不意味着收件人已打开链接、请求访问或已加入。如果某次批准操作返回混合结果，请分别处理各个结果。

## 标识符与记录的限制

| 项目 | 当前 YCloud 指南 |
| - | - |
| 群组大小 | 最多 8 名参与者。 |
| 每个商业号码的群组数 | 最多 10,000 个。 |
| 单个群组内的商业号码 | 1 个 Cloud API 商业号码。 |
| 群主题 | 最多 128 个字符。 |
| 群描述 | 最多 2,048 个字符。 |

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

## 保护成员变更

重置邀请链接会使之前的链接失效。请同步更新仍在使用旧链接的邀请或受控分发渠道；持有旧链接的收件人可能将无法再加入。

为群组生命周期、参与者、设置和状态更新配置 YCloud Webhook 端点。YCloud 会管理相关的平台订阅；您的应用程序仍需验证 Webhook 签名并安全处理重复事件。

保留关于操作请求者、受影响群组、请求 ID 和最终结果的审计记录。请勿在公开仪表板中记录私有邀请链接。

## 决定是否继续

如果支持的管理操作符合您的需求，请参考[群组集成指南](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-groups)。

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

## 常见问题

<AccordionGroup>
  <Accordion title="创建响应显示为 pending。我可以使用该 ID 邀请人员吗？">
    请等待最终的创建结果。请求 ID 并非群组 ID 或邀请链接。请保存成功生命周期事件中的群组信息，然后向符合条件的个人收件人发送获批的邀请。
  </Accordion>

  <Accordion title="邀请已送达。为什么客户还不是成员？">
    送达仅确认邀请已到达收件人。客户仍需要打开链接并选择加入；需要审批的群组还需要获得成功的审批结果。请检查加入请求和参与者事件，而不要将邀请的送达状态直接视为已成为成员。
  </Accordion>

  <Accordion title="旧的邀请链接失效了。我应该创建另一个群组吗？">
    首先检查链接是否已被重置。重置会使之前的链接失效，因此请使用当前链接并更新受控的分发点。如果链接是最新的，请检查群组是否已满或参与者之前是否已被移出。在创建重复群组之前，请先确认群组和参与者的状态。请参阅 [Meta 的群组常见问题](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/faq)。
  </Accordion>

  <Accordion title="客服人员可以从 YCloud Inbox 回复此群组吗？">
    在当前记录的 YCloud 范围内不支持。群组会话不会出现在 Inbox 中，Messages API 也不支持发送出站群组消息。群组管理端点和入站群组事件并不构成完整的双向群聊产品。
  </Accordion>

  <Accordion title="为什么删除群组后仍会收到 Webhook？">
    Meta 仍可能会传递在删除前收到的消息或状态事件。这些延迟的事件并不意味着群组已被重新创建。请保留群组 ID 和删除结果，安全地处理历史事件，不要仅根据迟到的 Webhook 重新发起邀请。请参阅 [Meta 的群组常见问题](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups/faq)。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.