> ## 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 群组成员更新 Webhook 示例

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

<Note>如需查看基于 Schema 衍生的完整目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。</Note>

## 什么是群组成员更新 Webhook

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

## 开始之前

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

## 工作原理

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

## 请求

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

## 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。</Note>

<br />

## 成员已添加

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

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 加群申请已创建

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

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 成员移除失败

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

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**：批量或部分结果更新中的成员级别详细信息

<br />


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