管理 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 终端节点并选择您希望接收的 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。如果游标无效或过期，请从第一页重新开始。

发送群组消息

使用 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 访问权限。

常见的邀请链接失败原因还包括链接已重置或过期、群组已满，或用户之前曾被企业移除。请勿无限期重试未作任何更改的请求。

端到端检查清单

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

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

本指南中的示例遵循当前的 YCloud API 约定。在生产环境中使用此集成之前，请确保顺利完成此清单。

API 参考

操作	参考
创建群组	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 示例