WhatsApp 群组成员更新 Webhook 示例

如需查看基于 Schema 衍生的完整目录，请参阅所有示例。

什么是群组成员更新 Webhook

处理 WhatsApp 群组成员及加群申请更新。

开始之前

在您的应用程序中创建一个公开的 HTTPS 端点。
为您所需的事件类型配置 YCloud Webhook 端点。
安全存储端点签名密钥。
确保事件处理具备幂等性。

工作原理

当事件发生时，YCloud 会发送 HTTP POST 请求。验证签名，持久化记录事件，返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送至您 Webhook URL 的请求。请将事件 id 视为投递标识符，并使用 type 路由有效负载。

响应

接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

成员已添加

当有成员被添加到 WhatsApp 群组时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "invite_link",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "addedParticipants": [
      {
        "input": "US.abc123",
        "waId": "16315551111",
        "recipientUserId": "US.abc123",
        "parentRecipientUserId": "US.parent123"
      }
    ],
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或易出错的任务移至异步处理器。

加群申请已创建

当用户申请加入需要审批的 WhatsApp 群组时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_participants_124",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_join_request_created",
    "status": "requested",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "admin_approval",
    "joinRequestId": "join-request-id",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    }
  }
}

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或易出错的任务移至异步处理器。

成员移除失败

当移除一名或多名成员失败或部分成功时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_participants_125",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "requestId": "REQ_REMOVE",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "initiatedBy": "business",
    "removedParticipants": [
      {
        "input": "16315551111"
      }
    ],
    "failedParticipants": [
      {
        "input": "16315552222",
        "errors": [
          {
            "code": 131212,
            "title": "Participant cannot be removed"
          }
        ]
      }
    ],
    "errors": [
      {
        "title": "Not all participants were removed"
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

type：对于群组成员和加群申请事件，固定为 whatsapp.group.participants_update
whatsappGroup：包含群组成员或加群申请更新的详细信息
- field：固定为 group_participants_update
- type：成员事件类型，例如 group_participants_add、group_participants_remove、group_join_request_created 或 group_join_request_revoked
- status：规范化的事件状态，例如 added、removed、left、requested、revoked 或 failed
- groupId：WhatsApp 群组 ID
- reason：成员或加群申请事件的原因
- joinRequestId：加群申请 ID，包含在加群申请事件中
- initiatedBy：指示谁发起了移除事件，例如 business 或 participant
- recipientUserId 与 parentRecipientUserId：受影响成员的业务级用户 ID
- addedParticipants、 removedParticipants 和 failedParticipants：批量或部分结果更新中的成员级别详细信息

开始使用

指南

接口

Webhooks

WhatsApp 群组成员更新 Webhook 示例

什么是群组成员更新 Webhook

开始之前

工作原理

请求

响应

成员已添加

请求

响应

说明

加群申请已创建

请求

响应

说明

成员移除失败

请求

响应

说明

​什么是群组成员更新 Webhook

​开始之前

​工作原理

​请求

​响应

​成员已添加

​请求

​响应

​说明

​加群申请已创建

​请求

​响应

​说明

​成员移除失败

​请求

​响应

​说明

什么是群组成员更新 Webhook

开始之前

工作原理

请求

响应

成员已添加

请求

响应

说明

加群申请已创建

请求

响应

说明

成员移除失败

请求

响应

说明