> ## 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.group.participants_update

> 在 WhatsApp 群组成员或加群请求发生更新时触发。

在您的 Webhook 端点处使用 `whatsapp.group.participants_update` 来处理此事件。

## 触发条件

在 WhatsApp 群组成员或加群请求发生更新时触发。

在[配置您的 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时订阅 `whatsapp.group.participants_update`。

## 语法

YCloud 会向您配置的 Webhook URL 发送一个 HTTP `POST` 请求。以下结构展示了其中一种有效负载变体。尖括号中的值为占位符；其类型列于 **参数** 下。可选字段及其他变体将在下文进行说明。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "waId": "<WA_ID>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "parentRecipientUserId": "<PARENT_RECIPIENT_USER_ID>",
    "customerProfile": {
      "name": "<NAME>",
      "username": "<USERNAME>"
    },
    "addedParticipants": [
      {
        "input": "<INPUT>",
        "waId": "<WA_ID>",
        "recipientUserId": "<RECIPIENT_USER_ID>",
        "parentRecipientUserId": "<PARENT_RECIPIENT_USER_ID>",
        "customerProfile": {
          "name": "<NAME>",
          "username": "<USERNAME>"
        }
      }
    ],
    "webhookTime": "<WEBHOOK_TIME>"
  }
}
```

## 参数

在处理 JSON 请求体之前，请先验证 `YCloud-Signature` HTTP 请求头。请参阅[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

### 事件信封

| 参数 | 类型 | 必需 | 说明 |
| - | - | - | - |
| `id` | string | 是 | 事件的唯一 ID。最小长度：`6`。最大长度：`128`。 |
| `type` | string | 是 | 固定为 `whatsapp.group.participants_update`。 |
| `apiVersion` | string | 是 | 用于渲染此事件的 API 版本。 |
| `createTime` | string (date-time) | 是 | 此事件的创建时间，格式为 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)。例如 `2022-06-01T12:00:00.000Z`。 |

### 事件有效负载

| 参数 | 类型 | 必需 | 说明 |
| - | - | - | - |
| `whatsappGroup` | object | 否 | 特定于事件的 `whatsappGroup` 有效负载。 |

四个通用信封字段为必需字段。有效负载字段取决于具体的事件变体。在每个对象表中， **必需** 仅在其父对象存在时适用。可选字段可以省略；示例中展示并不代表该字段为必需。

#### whatsappGroup

| 参数 | 类型 | 必需 | 说明 |
| - | - | - | - |
| `wabaId` | string | 否 | WhatsApp 商业账户 ID。 |
| `displayPhoneNumber` | string | 否 | 来自 WhatsApp Webhook 元数据的显示电话号码。 |
| `phoneNumberId` | string | 否 | WhatsApp 电话号码 ID。 |
| `field` | string | 否 | 产生该群组事件的 WhatsApp Webhook 字段。取值：`group_lifecycle_update`、`group_participants_update`、`group_settings_update`、`group_status_update`、`messages`。 |
| `type` | string | 否 | 具体的 WhatsApp 群组事件类型。取值：`group_create`、`group_delete`、`group_participants_add`、`group_participants_remove`、`group_join_request_created`、`group_join_request_revoked`、`group_settings_update`、`group_suspend`、`group_suspend_cleared`、`message_status`。 |
| `requestId` | string | 否 | 异步群组 API 操作返回的请求 ID。 |
| `status` | string | 否 | WhatsApp 群组 Webhook 状态。取值：`created`、`failed`、`deleted`、`added`、`removed`、`left`、`requested`、`revoked`、`updated`、`suspended`、`suspend_cleared`、`sent`、`delivered`、`read`、`expired`。 |
| `groupId` | string | 否 | WhatsApp 群组 ID。 |
| `messageId` | string | 否 | YCloud 群组消息 ID。仅在状态事件与已保存的出站群组消息关联时出现。 |
| `inviteLink` | string | 否 | 群组邀请链接。 |
| `reason` | string | 否 | 参与者变更、加入请求或移除事件的原因。 |
| `initiatedBy` | string | 否 | 指示谁发起了群成员移除事件。取值：`business`、`participant`。 |
| `joinRequestId` | string | 否 | 加群请求 ID。 |
| `waId` | string | 否 | 单个群成员事件的 WhatsApp 用户 ID。 |
| `recipientUserId` | string | 否 | 单个群成员事件的业务范围用户 ID（Business-scoped user ID）。 |
| `parentRecipientUserId` | string | 否 | 单个参与者事件的父级企业范围用户 ID。 |
| `customerProfile` | object | No | WhatsApp 客户个人资料信息。 |
| `subject` | string | 否 | 群组主题。 |
| `description` | string | 否 | 群组描述。 |
| `joinApprovalMode` | string | 否 | WhatsApp 群组加入审批模式。<ul><li>`approval_required`：新成员加入前必须经过批准。</li><li>`auto_approve`：新成员无需批准即可加入。</li></ul> |
| `addedParticipants` | object\[] | 否 | 添加到群组的参与者。 |
| `removedParticipants` | object\[] | 否 | 从群组中移除的成员。 |
| `failedParticipants` | object\[] | 否 | 添加或移除失败的参与者。 |
| `settings` | object\[] | 否 | 群组设置更新详情。 |
| `errors` | object\[] | 否 | WhatsApp 返回的错误。 |
| `contacts` | object\[] | 群组消息状态 Webhook 中未包含 | 联系人。 |
| `statuses` | object\[] | 否 | 群组消息状态详情。 |
| `webhookTime` | string (date-time) | 否 | WhatsApp 触发此 Webhook 的时间。 |
| `dedupeKey` | string | 否 | 用于对群组 Webhook 事件进行去重的幂等键。 |

> [accordion] whatsappGroup.customerProfile
>
> | 参数 | 类型 | 是否必填 | 描述 |
> | - | - | - | - |
> | `name` | string | 否 | WhatsApp 个人资料名称。 |
> | `username` | string | 否 | WhatsApp 用户名。 |

> [accordion] whatsappGroup.addedParticipants\[]
>
> | 参数 | 类型 | 必填 | 描述 |
> | - | - | - | - |
> | `input` | string | 否 | 原始参与者输入。 |
> | `waId` | string | 否 | WhatsApp 用户 ID。 |
> | `recipientUserId` | string | 否 | 商业范围内用户 ID。 |
> | `parentRecipientUserId` | string | 否 | 父级商业范围用户 ID（Parent business-scoped user ID）。 |
> | `customerProfile` | object | 否 | WhatsApp 客户个人资料信息。 |
> | `errors` | object\[] | 否 | WhatsApp 针对该参与者返回的错误。 |

> [accordion] whatsappGroup.addedParticipants\[].customerProfile
>
> | 参数 | 类型 | 必填 | 描述 |
> | - | - | - | - |
> | `name` | string | 否 | WhatsApp 个人资料名称。 |
> | `username` | string | 否 | WhatsApp 用户名。 |

> [accordion] whatsappGroup.removedParticipants\[]
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `input` | string | 否 | 原始输入的群成员信息。 |
> | `waId` | string | 否 | WhatsApp 用户 ID。 |
> | `recipientUserId` | string | 否 | 业务范围用户 ID（Business-scoped user ID）。 |
> | `parentRecipientUserId` | string | 否 | 父级业务范围用户 ID（Parent business-scoped user ID）。 |
> | `customerProfile` | object | 否 | WhatsApp 客户个人资料信息。 |
> | `errors` | object\[] | 否 | WhatsApp 针对该成员返回的错误。 |

> [accordion] whatsappGroup.removedParticipants\[].customerProfile
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `name` | string | 否 | WhatsApp 个人资料名称。 |
> | `username` | string | 否 | WhatsApp 用户名。 |

> [accordion] whatsappGroup.failedParticipants\[]
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `input` | string | 否 | 原始输入的群成员信息。 |
> | `waId` | string | 否 | WhatsApp 用户 ID。 |
> | `recipientUserId` | string | 否 | 业务范围用户 ID（Business-scoped user ID）。 |
> | `parentRecipientUserId` | string | 否 | 父级业务范围用户 ID（Parent business-scoped user ID）。 |
> | `customerProfile` | object | 否 | WhatsApp 客户个人资料信息。 |
> | `errors` | object\[] | 否 | WhatsApp 针对该成员返回的错误。 |

> [accordion] whatsappGroup.failedParticipants\[].customerProfile
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `name` | string | 否 | WhatsApp 个人资料名称。 |
> | `username` | string | 否 | WhatsApp 用户名。 |

> [accordion] whatsappGroup.settings\[]
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `name` | string | 否 | 设置名称。可选值：`profile_picture`、`group_subject`、`group_description`。 |
> | `text` | string | 否 | 用于主题或描述更新的文本值。 |
> | `updateSuccessful` | boolean | 否 | 设置更新是否成功。 |
> | `mimeType` | string | 否 | 头像更新的 MIME 类型。 |
> | `sha256` | string | 否 | 头像更新的 SHA-256 哈希值。 |
> | `errors` | object\[] | 否 | WhatsApp 针对该设置返回的错误。 |

> [accordion] whatsappGroup.contacts\[]
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `customerProfile` | object | 否 | WhatsApp 客户个人资料信息。 |
> | `waId` | string | 否 | WhatsApp 用户 ID。 |
> | `recipientUserId` | string | 否 | 业务范围用户 ID（Business-scoped user ID）。 |
> | `parentRecipientUserId` | string | 否 | 父级业务范围用户 ID（Parent business-scoped user ID）。 |

> [accordion] whatsappGroup.contacts\[].customerProfile
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `name` | string | 否 | WhatsApp 个人资料名称。 |
> | `username` | string | 否 | WhatsApp 用户名。 |

> [accordion] whatsappGroup.statuses\[]
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `id` | string | 否 | WhatsApp 消息 ID。 |
> | `status` | string | 否 | 消息状态。可选值：`sent`、`delivered`、`read`、`failed`、`expired`。 |
> | `timestamp` | integer (int64) | 否 | 表示消息状态更新时间的 Unix 时间戳。 |
> | `recipientId` | string | 否 | 接收群组 ID。 |
> | `recipientType` | string | 否 | 接收方类型。可选值：`group`。 |
> | `recipientParticipantId` | string | 否 | 接收成员的 WhatsApp 用户 ID。 |
> | `recipientUserId` | string | 否 | 接收成员的 Business-scoped 用户 ID。 |
> | `parentRecipientUserId` | string | 否 | 接收成员的父级 Business-scoped 用户 ID。 |
> | `conversation` | object | 否 | 群消息状态 Webhook 中包含的 WhatsApp 会话对象。 |
> | `pricing` | object | 否 | 群消息状态 Webhook 中包含的计费信息。 |
> | `errors` | object\[] | 否 | WhatsApp 返回的错误信息。 |

> [accordion] whatsappGroup.statuses\[].conversation
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `id` | string | 否 | 会话 ID。 |
> | `expirationTimestamp` | integer (int64) | 否 | 表示会话过期时间的 Unix 时间戳。 |
> | `origin` | object | 否 | 对象字段如下所示。 |

> [accordion] whatsappGroup.statuses\[].conversation.origin
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `type` | string | 否 | 会话发起类型。 |

> [accordion] whatsappGroup.statuses\[].pricing
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `billable` | boolean | 否 | 该消息是否计费。 |
> | `pricingModel` | string | 否 | 计费模式。 |
> | `type` | string | 否 | 计费类型。 |
> | `category` | string | 否 | Meta 报告的原始群组计费类别。YCloud 不在此 Webhook 字段中公开内部 MM Lite 映射。可选值：`group_marketing`、`group_utility`、`group_service`。 |

## 示例

以下 JSON 是发送至接收端的请求体。ID、电话号码及其他账户信息仅作示意。

> [accordion] WhatsApp 群成员更新事件
>
> 添加 WhatsApp 群成员时的示例载荷
>
> ```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": "120363345678901234@g.us",
>     "waId": "16315551111",
>     "recipientUserId": "US.1234",
>     "parentRecipientUserId": "US.parent123",
>     "customerProfile": {
>       "name": "John Doe",
>       "username": "john_doe"
>     },
>     "addedParticipants": [
>       {
>         "input": "US.1234",
>         "waId": "16315551111",
>         "recipientUserId": "US.1234",
>         "parentRecipientUserId": "US.parent123",
>         "customerProfile": {
>           "name": "John Doe",
>           "username": "john_doe"
>         }
>       }
>     ],
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] 成员已添加
>
> ```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"
>   }
> }
> ```

> [accordion] 加群请求已创建
>
> ```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"
>     }
>   }
> }
> ```

> [accordion] 移除成员失败
>
> ```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"
>   }
> }
> ```

验证签名并持久化接收事件后，请返回 `2xx` 响应。耗时任务建议异步处理。

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

有关场景演练，请参阅[带注解的示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-group-participants-update-webhook-examples)。


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