管理 WhatsApp 群组

功能简介

YCloud WhatsApp Groups API 允许您的企业创建仅限受邀加入的 WhatsApp 群组。您可以向每位用户发送邀请链接，由其自主选择是否加入。如果群组需要审批，您可以在允许其进群前审核其加入申请。本指南涵盖群组的设置与管理。目前暂不支持向群组发送消息及获取群组消息。群组对话不会出现在收件箱（Inbox）中。

准备工作

在开始集成之前，请确保您的 WhatsApp 商业电话号码满足以下要求：

企业拥有官方商业账户（OBA）。
该电话号码使用的是 WhatsApp Cloud API，而非 WhatsApp Business App。
该电话号码未启用多方案对话（Multi-solution Conversations）。
您的 YCloud 账户拥有该电话号码的访问权限。
您拥有一个可供 YCloud 推送 Webhook 事件的公网 HTTPS URL。
在通过消息模板发送邀请链接之前，您拥有已获批准的群组邀请模板。

YCloud 会代为管理所需的 WhatsApp 平台订阅。您只需配置 YCloud Webhook 端点，并选择您希望接收的 YCloud 群组事件即可。

YCloud 和 WhatsApp 会检查该电话号码是否符合要求。如果不符合，请核验其 OBA 认证状态、Cloud API 设置以及在 YCloud 中的访问权限。

支持的功能与限制

YCloud 目前支持：

创建、列出、获取和删除群组。
获取和重置邀请链接。
向单个 WhatsApp 用户发送已审核通过的邀请链接模板。
列出、批准和拒绝加入申请。
移除群成员。
更新群组主题和群描述。
使用 JPEG 文件更新群头像。
接收群组生命周期、群成员、设置和封禁相关的 Webhook。

WhatsApp 平台应用了以下限制：

一个群组最多可容纳 8 名参与者。
一个商业电话号码最多可创建 10,000 个群组。
一个群组中只能包含一个 Cloud API 商业电话号码。
单次 YCloud 请求最多可移除 8 名参与者。
群组主题最多可包含 128 个字符。
群描述最多可包含 2,048 个字符。

这些 API 不支持置顶或取消置顶消息。

工作原理

选择 YCloud 应发送到您的 Webhook 端点的群组事件。
发送创建群组的请求。YCloud 会立即返回 requestId。
等待生命周期 Webhook 报告创建是否成功。
若创建成功，保存返回的 groupId 和邀请链接。严格按照 YCloud 返回的原始格式存储并使用 groupId。
每次将邀请链接发送给一个人。
如果群组需要审批，请批准或拒绝每个加入申请。
利用群成员事件和查询群组 API 保持成员列表最新。
使用 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`	用户需提交加入申请，您审批后方可加入。

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 已收到请求：

{
  "requestId": "REQ_1",
  "status": "pending"
}

等待 whatsapp.group.lifecycle_update。创建成功的 group_create 事件将包含最终的 groupId 和 inviteLink。

{
  "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 发送该链接，请先准备一个已获批准的邀请模板。然后将该模板发送给单个用户：

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 群组：

接收 group_join_request_created，或获取待处理的请求。
在请求仍处于待处理状态时保存 joinRequestId。
将每个 ID 发送到批准或拒绝端点。
检查响应中的成功和失败条目，包括 failedJoinRequests 和 errors。
通过“添加参与者”Webhook 或通过获取群组信息来确认该人员已加入。

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 获取上一页。

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 保存。如果游标无效或已过期，请从第一页重新开始。

维护群组

移除参与者

您可以在单个请求中最多移除八位参与者。在发送请求前请先去重参与者标识符。部分参与者可能会被成功移除而其他参与者失败，因此请检查参与者 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 访问权限。

常见的邀请链接失败原因还包括链接被重置或过期、群组已满，或者用户此前已被商家移除。请勿无限期重试未经修改的请求。

端到端检查清单

在正式上线前，请使用符合条件的测试电话号码完成此完整流程：

让测试 Webhook 端点订阅所有四种群组事件类型。
创建一个 approval_required 群组并存储返回的 requestId。
等待匹配的 group_create 事件并存储其 groupId 以及 inviteLink.
向测试用户发送已获批的邀请模板。
让该用户提交加群申请。
接收或列出该申请，然后批准其 joinRequestId。
等待成员已添加事件。
获取群组并确认该成员已存在。
移除测试成员并确认异步结果。
删除测试群组并确认生命周期事件。

本指南中的示例遵循当前 YCloud API 规范。请在生产环境中使用该集成之前，成功完成此检查清单。

API 参考

操作	参考
创建群组	API 参考
列出群组	API 参考
获取群组	API 参考
删除群组	API 参考
获取邀请链接	API 参考
重置邀请链接	API 参考
发送邀请链接消息	API 参考
列出加群申请	API 参考
批准加群申请	API 参考
拒绝加群申请	API 参考
移除成员	API 参考
更新群组设置	API 参考

Webhook 示例

生命周期事件

处理群组创建和删除结果。

成员事件

处理加群、加群申请、移除以及成员级别的失败。

设置事件

处理群主题和描述更新结果。

状态事件

处理群组封禁及解除封禁事件。

开始使用

指南

接口

Webhooks

管理 WhatsApp 群组

功能简介

准备工作

支持的功能与限制

工作原理

配置 Webhook

创建群组

邀请参与者

处理加群请求

列出群组和加群请求

维护群组

移除参与者

更新设置

删除群组

安全处理异步结果

错误与故障排查

端到端检查清单

API 参考

Webhook 示例

生命周期事件

成员事件

设置事件

状态事件

​功能简介

​准备工作

​支持的功能与限制

​工作原理

​配置 Webhook

​创建群组

​邀请参与者

​处理加群请求

​列出群组和加群请求

​维护群组

​移除参与者

​更新设置

​删除群组

​安全处理异步结果

​错误与故障排查

​端到端检查清单

​API 参考

​Webhook 示例

生命周期事件

成员事件

设置事件

状态事件

功能简介

准备工作

支持的功能与限制

工作原理

配置 Webhook

创建群组

邀请参与者

处理加群请求

列出群组和加群请求

维护群组

移除参与者

更新设置

删除群组

安全处理异步结果

错误与故障排查

端到端检查清单

API 参考

Webhook 示例