whatsapp.group.participants_update

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

触发条件

在 WhatsApp 群组成员或加群请求发生更新时触发。在配置您的 Webhook 端点时订阅 whatsapp.group.participants_update。

语法

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

{
  "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 请求头。请参阅签名验证。

事件信封

参数	类型	必需	说明
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.group.participants_update`。
`apiVersion`	string	是	用于渲染此事件的 API 版本。
`createTime`	string (date-time)	是	此事件的创建时间，格式为 RFC 3339。例如 `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 群组加入审批模式。 `approval_required`：新成员加入前必须经过批准。 `auto_approve`：新成员无需批准即可加入。
`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 事件进行去重的幂等键。

whatsappGroup.customerProfile

参数	类型	是否必填	描述
`name`	string	否	WhatsApp 个人资料名称。
`username`	string	否	WhatsApp 用户名。

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 针对该参与者返回的错误。

whatsappGroup.addedParticipants[].customerProfile

参数	类型	必填	描述
`name`	string	否	WhatsApp 个人资料名称。
`username`	string	否	WhatsApp 用户名。

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 针对该成员返回的错误。

whatsappGroup.removedParticipants[].customerProfile

参数	类型	是否必填	说明
`name`	string	否	WhatsApp 个人资料名称。
`username`	string	否	WhatsApp 用户名。

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 针对该成员返回的错误。

whatsappGroup.failedParticipants[].customerProfile

参数	类型	是否必填	说明
`name`	string	否	WhatsApp 个人资料名称。
`username`	string	否	WhatsApp 用户名。

whatsappGroup.settings[]

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

whatsappGroup.contacts[]

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

whatsappGroup.contacts[].customerProfile

参数	类型	是否必填	说明
`name`	string	否	WhatsApp 个人资料名称。
`username`	string	否	WhatsApp 用户名。

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 返回的错误信息。

whatsappGroup.statuses[].conversation

参数	类型	必填	说明
`id`	string	否	会话 ID。
`expirationTimestamp`	integer (int64)	否	表示会话过期时间的 Unix 时间戳。
`origin`	object	否	对象字段如下所示。

whatsappGroup.statuses[].conversation.origin

参数	类型	必填	说明
`type`	string	否	会话发起类型。

whatsappGroup.statuses[].pricing

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

示例

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

WhatsApp 群成员更新事件

添加 WhatsApp 群成员时的示例载荷

{
  "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"
  }
}

成员已添加

{
  "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"
  }
}

加群请求已创建

{
  "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"
    }
  }
}

移除成员失败

{
  "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/1.1 200 OK

有关场景演练，请参阅带注解的示例。

开始使用

指南

接口

Webhook reference

whatsapp.group.participants_update

触发条件

语法

参数

事件信封

事件有效负载

whatsappGroup

示例

​触发条件

​语法

​参数

​事件信封

​事件有效负载

​whatsappGroup

​示例

触发条件

语法

参数

事件信封

事件有效负载

whatsappGroup

示例