> ## 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 群组 > 了解如何创建仅限邀请加入的 WhatsApp 群组、邀请成员、审核加群请求以及管理群组设置。 ## 功能简介 YCloud WhatsApp Groups API 允许您的企业创建仅限邀请加入的 WhatsApp 群组。您可以向每个人发送邀请链接，由对方选择是否加入。如果群组需要审批，您可以在允许其入群前先审核该用户的加群请求。 本指南涵盖群组设置、管理和出站群组消息。群聊消息不会显示在 Inbox 中。 ## 准备工作 在开始集成前，请确保您的 WhatsApp 商业电话号码满足以下要求： * 企业拥有官方商业账户（OBA）。 * 电话号码使用的是 WhatsApp Cloud API，而非 WhatsApp Business App。 * 电话号码未使用多方案对话（Multi-solution Conversations）。 * 您的 YCloud 账户具有该电话号码的访问权限。 * 您拥有一个公开的 HTTPS URL，以便 YCloud 发送 Webhook 事件。 * 在通过消息模板发送邀请链接前，您已拥有获得批准的 群组邀请模板。 YCloud 会管理所需的 WhatsApp 平台订阅。您只需[配置 YCloud Webhook 终端节点](/zh/api-reference/guides/api-fundamentals/configure-webhooks)并选择您希望接收的 YCloud 群组事件。 YCloud 和 WhatsApp 会检查电话号码是否符合条件。若不符合， 请核验其 OBA 状态、Cloud API 设置以及 YCloud 中的访问权限。 ## 支持的功能与限制 YCloud 目前支持： * 创建、列出、获取和删除群组。 * 获取和重置邀请链接。 * 向单个 WhatsApp 用户发送已获批准的邀请链接模板。 * 列出、批准和拒绝加群请求。 * 移除群成员。 * 更新群组主题和描述。 * 使用 JPEG 文件更新群组头像。 * 向群组发送文本、媒体、贴纸及受支持的模板消息。 * 接收群组生命周期、成员、设置和封禁相关的 Webhook。 WhatsApp 平台应用了以下限制： * 一个群组最多可有 8 名成员。 * 一个商业电话号码最多可创建 10,000 个群组。 * 一个群组只能包含一个 Cloud API 商业电话号码。 * 单个 YCloud 请求最多可移除 8 名成员。 * 群组主题最多可包含 128 个字符。 * 群组描述最多可包含 2,048 个字符。 这些 API 不支持置顶或取消置顶消息。 ## 工作原理 1. 选择 YCloud 应发送到您的 Webhook 终端节点的群组事件。 2. 发送创建群组请求。YCloud 会立即返回 `requestId`。 3. 等待生命周期 Webhook 报告创建是否成功。 4. 如果创建成功，请保存返回的 `groupId` 和邀请链接。存储并 严格按照 YCloud 返回的格式使用 `groupId`。 5. 一次向一个人发送邀请链接。 6. 如果群组需要审批，请批准或拒绝每个加群请求。 7. 使用成员事件和获取群组 API 来保持群成员列表 为最新状态。 8. 使用 Webhook 事件确认群组删除、成员移除和 设置更改。 状态为 `status: "pending"` 的 `200` 响应仅表示 YCloud 已收到 该请求。操作会在稍后完成。请使用对应的 Webhook 事件来查看 操作是否成功。 ## 配置 Webhook 在创建群组之前，请让您的 YCloud Webhook 终端节点订阅以下事件： | 事件 | 用途 | | - | - | | `whatsapp.group.lifecycle_update` | 群组创建和删除结果。 | | `whatsapp.group.participants_update` | 加入、加群请求、移除、退群以及成员级失败。 | | `whatsapp.group.settings_update` | 主题和描述更新结果。 | | `whatsapp.group.status_update` | 群组封禁和解除封禁事件。 | 当 YCloud 发送事件时，请验证 `YCloud-Signature`，保存该事件，并及时返回 `2xx` 响应。然后您可以在后台对其进行处理。YCloud 可能会多次发送同一事件，不同事件的到达顺序也可能颠倒。请使用事件 `id` 来识别已处理过的推送。 对于通过 API 发起的操作，请通过 `requestId` 将 Webhook 与原始请求进行匹配。由群成员发起的动作（例如加入或离开）可能不包含 `requestId`。在这种情况下，请使用事件类型、`groupId`、成员标识符和事件时间。 ## 创建群组 选择加群审批模式： | 模式 | 行为 | | - | - | | `auto_approve` | 用户可以直接通过邀请链接加入。这是默认设置。 | | `approval_required` | 用户提交加群请求，必须经过您的审批后方可加入。 | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "subject": "New purchase inquiry", "description": "Discuss purchase requirements with our team.", "joinApprovalMode": "approval_required" }' ``` 群组创建是异步完成的。首次响应仅确认 YCloud 已收到请求： ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "requestId": "REQ_1", "status": "pending" } ``` 等待 `whatsapp.group.lifecycle_update`。成功的 `group_create` 事件会包含最终的 `groupId` 和 `inviteLink`。 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "evt_group_lifecycle_123", "type": "whatsapp.group.lifecycle_update", "whatsappGroup": { "type": "group_create", "requestId": "REQ_1", "status": "created", "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE", "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK" } } ``` 保存并使用成功事件中完全一致的 `groupId`。它区分大小写。切勿自行解码、修改或生成它。 ## 邀请成员 您可以使用创建 Webhook 中的邀请链接，或稍后通过邀请链接接口获取该链接。仅当您需要所有先前分享的链接失效时，才重置链接。重置后，用户将无法通过旧链接加入。 如需通过 WhatsApp 发送链接，请先准备一份已获批准的邀请模板。然后将该模板发送给单个用户： ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups/inviteLink/messages \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "to": "+16315552222", "templateName": "group_invite_link", "languageCode": "en_US", "parameters": [ { "type": "group_id", "group_id": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE" } ] }' ``` 此端点会向 `to` 或 `recipient` 指定的用户发送模板消息。它不会向群组发送消息。如果您同时提供了这两个字段，YCloud 将使用 `to`。 ## 处理加群请求 对于 `auto_approve` 群组，请等待成员已添加的 Webhook，然后再将该用户记录为成员。 对于 `approval_required` 群组： 1. 接收 `group_join_request_created`，或检索待处理请求。 2. 在请求仍处于待处理状态时保存 `joinRequestId`。 3. 将每个 ID 发送到批准或拒绝端点。 4. 检查响应中的成功和失败项，包括 `failedJoinRequests` 和 `errors`。 5. 通过成员已添加的 Webhook 或通过 检索群组来确认该用户已加入。 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups/GROUP_ID/joinRequests/approve \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "joinRequests": ["join-request-id"] }' ``` 用户可以撤回待处理的请求。如果批准因请求不再存在而失败，请刷新待处理请求列表，而不是无限期地重试相同的 ID。 ## 列出群组和加群请求 群组列表和加群请求列表分页返回结果。cursor（游标）是一个临时值，用于标记您在列表中的位置。`limit` 控制页面大小，范围为 `1` 到 `1024`，默认为 `25`。传递 `after` 获取下一页，或传递 `before` 获取上一页。 ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --get \ https://api.ycloud.com/v2/whatsapp/+16315551111/groups \ --header "X-API-Key: $YCLOUD_API_KEY" \ --data-urlencode "limit=25" \ --data-urlencode "after=NEXT_CURSOR" ``` 请勿将游标保存为永久 ID。如果游标无效或过期，请从第一页重新开始。 ## 发送群组消息 使用 `POST /whatsapp/groupMessages/sendDirectly` 向群组的当前成员发送一条消息。YCloud 会先检索群组，并为该消息固定接收者快照。如果群组包含商业发送者在内共有八位成员，YCloud 会创建七条成员结果。之后加入的用户不会收到先前的消息，也不会被添加到该消息的历史记录中。 发送响应仅确认已接收。使用 `GET /whatsapp/groupMessages/{id}` 检索群组级结果、每个成员的送达状态以及最终定价。群组级的 `status` 描述整体发送结果：已被 YCloud 接收、已被 Meta 发送或已失败。`recipients` 中的每个项目对应一位成员，并且可以具有不同的状态。 YCloud 支持 `text`、`image`、`video`、`audio`、`document`、`sticker` 以及支持的 `template` 消息。身份验证模板以及包含交互式或商业组件的模板将被拒绝。 对于营销模板，当 WABA 符合资格且至少有一位接收者具有 MM Lite 价格时，YCloud 可以使用 MM Lite 通道。此时成员记录使用 `group_marketing_lite`。效用和服务消息保留 `group_utility` 和 `group_service`，且不使用 MM Lite。如果某个成员在所选通道中没有价格，只要至少可以向一位成员发送，YCloud 仍会提交该群组。系统不会为缺少价格的成员冻结预估金额，也不会回退到其他通道的价格。最终计费将采用送达结果中报告的价格。 ## 维护群组 ### 移除成员 您可以在单个请求中移除最多八位成员。在发送请求之前，请移除重复的成员标识符。可能会出现部分成员被成功移除而其他成员失败的情况，因此请检查成员 Webhook 中的 `removedParticipants`、`failedParticipants[].errors` 以及顶层 `errors`。 ### 更新设置 您可以更新 `subject`、`description`、JPEG 格式的 `profile_picture_file`，或这些设置的任意组合。仅更改文本时请发送 JSON。上传个人资料照片时请发送 `multipart/form-data`。初始响应仅确认 YCloud 已接收该请求。请等待设置 Webhook 并检查每个 `settings[]` 条目，以确认实际更新的内容。 ### 删除群组 初始删除响应并不确认群组已被删除。请等待带有 `type: "group_delete"` 和最终 `status` 的生命周期 Webhook。删除后，该群组将无法再次使用。已在进行中的事件可能仍会送达。 ## 安全处理异步结果 * 将 `requestId`、请求的操作以及您自己的参考 ID 一并存储。 * 如果再次收到相同的事件 `id`，请勿重复应用相同的更改。 * 确保再次处理同一事件不会产生重复数据 或副作用。 * 考虑到事件可能会重复或乱序送达。 * 当事件与当前数据发生冲突时，请重新检索群组。 * 对于部分成功的操作，请检查顶层和单项级别的错误。 * 从常规应用程序日志中脱敏 API 密钥、邀请链接、成员标识符和个人数据 。 ## 错误与排查 API 请求可能会立即失败，也可能会在 YCloud 接收后失败： * 对于即时失败，请检查标准 YCloud 错误响应。 顶层的 `error.code` 是通用的 YCloud 代码，例如 `BAD_REQUEST` 或 `FORBIDDEN`。`error.whatsappApiError` 可能包含来自 WhatsApp 的其他详细信息。切勿通过匹配可读的 `message` 文本来决定应用程序的操作。 * 对于稍后报告的失败，请检查群组 Webhook。根据具体 操作，查看 `whatsappGroup.errors`、`failedParticipants[].errors` 或 `settings[].errors`. | 场景 | 建议操作 | | - | - | | 群组未找到或不可用 | 确认 `groupId` 与 YCloud 返回的值完全一致，然后检索最新的群组状态。 | | 游标无效或已过期 | 从第一页重新开始分页。 | | 操作部分成功 | 分别处理成功的项目和失败的项目。 | | 重复的群成员 | 重试前移除重复的群成员 ID。 | | 达到群成员上限 | 停止添加群成员并提示群组已满。 | | 群组已暂停 | 等待状态更新或联系客服支持。 | | 群组操作触发限流 | 使用指数退避、抖动和有限重试次数进行重试。 | | 达到电话号码群组上限 | 移除未使用的群组或联系客服支持。 | | 群成员不在群组中 | 刷新群成员列表，不要重复执行移除操作。 | | 未找到加群请求 | 刷新待处理的请求；该请求可能已被撤销或处理。 | | 群组创建暂时受限 | 停止创建群组并检查最近的消息发送策略。 | | 电话号码不符合条件 | 验证 OBA 状态、Cloud API 入驻情况以及 YCloud 访问权限。 | 常见的邀请链接失败原因还包括链接已重置或过期、群组已满， 或用户之前曾被企业移除。请勿无限期重试未作任何更改的 请求。 ## 端到端检查清单 在正式上线前，请使用符合条件的测试电话号码完成以下完整流程： 1. 将测试 Webhook 终端节点订阅到所有四种群组事件类型。 2. 创建一个 `approval_required` 群组并存储返回的 `requestId`。 3. 等待匹配的 `group_create` 事件并存储其 `groupId` 与 `inviteLink`. 4. 向测试用户发送已获批的邀请模板。 5. 让该用户提交加群请求。 6. 接收或列出该请求，然后批准其 `joinRequestId`。 7. 等待群成员添加成功的事件。 8. 检索群组并确认该成员已存在。 9. 移除测试群成员并确认异步结果。 10. 删除测试群组并确认生命周期事件。 本指南中的示例遵循当前的 YCloud API 约定。在 生产环境中使用此集成之前，请确保顺利完成此清单。 ## API 参考 | 操作 | 参考 | | - | - | | 创建群组 | [API 参考](/api-reference/whatsapp-groups/create-a-group) | | 列出群组 | [API 参考](/api-reference/whatsapp-groups/list-groups) | | 检索群组 | [API 参考](/api-reference/whatsapp-groups/retrieve-a-group) | | 删除群组 | [API 参考](/api-reference/whatsapp-groups/delete-a-group) | | 检索邀请链接 | [API 参考](/api-reference/whatsapp-groups/retrieve-a-group-invite-link) | | 重置邀请链接 | [API 参考](/api-reference/whatsapp-groups/reset-a-group-invite-link) | | 发送邀请链接消息 | [API 参考](/api-reference/whatsapp-groups/send-a-group-invite-link-message) | | 列出加群请求 | [API 参考](/api-reference/whatsapp-groups/list-group-join-requests) | | 批准加群请求 | [API 参考](/api-reference/whatsapp-groups/approve-group-join-requests) | | 拒绝加群请求 | [API 参考](/api-reference/whatsapp-groups/reject-group-join-requests) | | 移除群成员 | [API 参考](/api-reference/whatsapp-groups/remove-group-participants) | | 更新群组设置 | [API 参考](/api-reference/whatsapp-groups/update-group-settings) | | 直接发送群组消息 | [API 参考](/api-reference/whatsapp-group-messages/send-a-group-message-directly) | | 检索群组消息 | [API 参考](/api-reference/whatsapp-group-messages/retrieve-a-group-message) | ## Webhook 示例 处理群组创建和删除结果。 处理加群、加群请求、移除以及群成员级别的失败。 处理主题和描述更新结果。 处理群组暂停及解除暂停事件。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.