> For the complete documentation index, see [llms.txt](https://docs.innopaas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.innopaas.com/api-reference/whatsapp-business-api/webhook/xiao-zu-webhook-shi-jian.md). # 小组 Webhook 事件 本节覆盖小组（Group）相关的事件回调。为接收小组元数据变更通知，需在 WebHook 订阅中开启以下字段（每条对应下方小节的事件类型）：`group_lifecycle_update`（群组创建 / 删除）；`group_participants_update`（群组成员变更：邀请链接加入 / 申请加入 / 取消申请 / 加入请求被批准 / 移除 / 主动退出）；`group_settings_update`（群组设置：主题 / 描述 / 头像更新）；`group_status_update`（群组暂停 / 解除暂停）。本节事件统一使用 InnoPaas 公共信封（`id`、`type`、`eventTime`、`body`）与本节 5 个 InnoPaas 事件类型：`whatsapp_group_lifecycle_update`、`whatsapp_group_participants_update`、`whatsapp_group_settings_update`、`whatsapp_group_status_update`、`whatsapp_group_message_status_updated`。 **下方公共字段适用于本节所有事件（与上文公共参数一致，此处仅列出小组事件特有或易混淆的字段）：** | **字段** | **数据类型** | **是否必填** | **描述** | | ----------- | -------- | -------- | ------------------------------------------ | | group\_id | String | 是 | 小组 ID，调用 Groups API 返回的 group\_id | | type | String | 是 | 子事件类型，详见各小节 | | timestamp | String | 是 | 事件触发时间，UTC 格式 yyyy-MM-dd'T'HH:mm:ss.SSS'Z' | | request\_id | String | 否 | 请求 ID，便于排查与关联 API 调用 | ## **群组生命周期（​whatsapp\_group\_lifecycle\_update​）** 当群组被创建或被删除时触发该事件：`whatsapp_group_lifecycle_update`，对应订阅字段 `group_lifecycle_update`。`type` 字段区分子事件：`group_create`（创建成功 / 失败）、`group_delete`（删除成功 / 失败）。 | **字段** | **数据类型** | **是否必填** | **描述** | | -------------------- | -------- | -------- | ---------------------------------------------------------------------------------- | | group\_id | String | 是 | 小组 ID | | type | String | 是 | 子事件类型，可选值：`group_create`、`group_delete` | | subject | String | 否 | 群组主题；`type=group_create`时返回；`type=group_create`失败时返回失败时使用的主题 | | invite\_link | String | 否 | 群组邀请链接，`type=group_create`且创建成功时返回 | | join\_approval\_mode | String | 否 | 群组加入审批模式：`auto_approve`（无需审批）/`approval_required`（需审批），`type=group_create`且创建成功时返回 | | request\_id | String | 否 | 请求 ID | | timestamp | String | 是 | 事件触发时间 | | errors | Array | 否 | 失败时返回的错误数组（结构同上行消息的 errors） | **group\_create 成功:** 响应示例 ```json { "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22", "type": "whatsapp_group_lifecycle_update", "eventTime": "2026-09-03T08:00:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_create", "subject": "test invite link", "invite_link": "https://chat.whatsapp.com/LINK_ID", "join_approval_mode": "auto_approve", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:00:00.000Z" } } ``` **group\_create 失败:** 响应示例 ```json { "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22", "type": "whatsapp_group_lifecycle_update", "eventTime": "2026-09-03T08:00:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_create", "subject": "GROUP_SUBJECT", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:00:00.000Z", "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "title": "ERROR_TITLE", "error_data": { "details": "ERROR_DETAILS" } } ] } } ``` **group\_delete 失败:** 响应示例 ```json { "id": "6f1d2c44-1a4b-4b1e-9d2c-7a8b1f0e3c22", "type": "whatsapp_group_lifecycle_update", "eventTime": "2026-09-03T08:00:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_delete", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:00:00.000Z", "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "title": "ERROR_TITLE", "error_data": { "details": "ERROR_DETAILS" } } ] } } ``` **group\_delete 成功** 的 JSON 载荷样例：数据待补（创建/删除成功载荷缺关键字段以确认，待与上游对齐后补全；创建成功载荷见上）。 ## **群组成员变更（​whatsapp\_group\_participants\_update​）** 当群组成员发生以下变化时触发该事件：`whatsapp_group_participants_update`，对应订阅字段 `group_participants_update`。常见子事件：用户通过邀请链接加入群组（`reason=invite_link`）；用户提交加入请求（`reason=join_request`，`group_request_type=group_join_request_created`）；用户取消加入请求（`group_request_type=group_join_request_revoked`）；一个或多个加入请求被批准（`reason=invite_link`，`type=group_participants_add`，`added_participants[]`）；移除群成员：`type=group_participants_remove`，可能部分成功 / 全部成功 / 全部失败；群成员主动退出：`initiated_by` 与 `removed_participants[].wa_id` 指向退出者。 | **字段** | **数据类型** | **是否必填** | **描述** | | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------ | | group\_id | String | 是 | 小组 ID | | type | String | 是 | 子事件类型，可选值：`group_participants_add`、`group_participants_remove`等 | | reason | String | 否 | 触发原因，例如`invite_link`（通过邀请链接加入 / 加入请求被批准） | | group\_request\_type | String | 否 | 加入请求类型：`group_join_request_created`（已申请）、`group_join_request_revoked`（已撤销） | | added\_participants | Array | 否 | 新增成员列表，每项`{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}` | | removed\_participants | Array | 否 | 移除成员列表，每项`{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}`；主动退出时`initiated_by`与本列表的`wa_id`均指向退出者 | | initiated\_by | String | 否 | 发起本次变更的 WhatsApp 用户 ID（移除 / 退出场景） | | request\_id | String | 否 | 请求 ID | | timestamp | String | 是 | 事件触发时间 | | errors | Array | 否 | 失败时返回的错误数组 | **加入请求被批准（多成员批量）:** 响应示例 ```json { "id": "7a2e3b55-2c5c-4c2f-ae3d-8b9c2a1f4d33", "type": "whatsapp_group_participants_update", "eventTime": "2026-09-03T08:10:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_participants_add", "reason": "invite_link", "timestamp": 1783558600, "added_participants": [ { "input": "WHATSAPP_USER_PHONE_NUMBER", "wa_id": "WHATSAPP_USER_ID" } ] } } ``` 其他子事件（用户通过邀请链接加入、加入 / 取消加入请求、成员移除成功 / 部分失败 / 失败、成员主动退出）的 JSON 载荷样例：数据待补（`type` 取值与字段排列顺序以镜像源资料描述为准，完整 JSON 待与上游对齐后补全；触发条件与字段定义以上方表格为准）。 ## **群组设置更新（​whatsapp\_group\_settings\_update​）** 当群组设置（主题 / 描述 / 头像）被更新时触发该事件：`whatsapp_group_settings_update`，对应订阅字段 `group_settings_update`。`update_successful` 字段标识本次更新是否成功；失败时附带 `errors` 数组。整体可成功 / 部分失败 / 全部失败。 | **字段** | **数据类型** | **是否必填** | **描述** | | ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------ | | group\_id | String | 是 | 小组 ID | | type | String | 是 | 固定值：`group_settings_update` | | profile\_picture | Object | 否 | 头像更新结果：`mime_type`（如 image/jpeg）、`sha256`（更新成功时返回）、`update_successful`（Boolean）、`errors`（仅失败时返回） | | group\_subject | Object | 否 | 主题更新结果：`text`、`update_successful`（Boolean）、`errors`（仅失败时返回） | | group\_description | Object | 否 | 描述更新结果：`text`、`update_successful`（Boolean）、`errors`（仅失败时返回） | | request\_id | String | 否 | 请求 ID | | timestamp | String | 是 | 事件触发时间 | | errors | Array | 否 | 整体失败 / 部分失败时返回的顶层错误数组 | **全部成功:** 响应示例 ```json { "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44", "type": "whatsapp_group_settings_update", "eventTime": "2026-09-03T08:20:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_settings_update", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:20:00.000Z", "profile_picture": { "mime_type": "image/jpeg", "update_successful": true, "sha256": "PHOTO_HASH" }, "group_subject": { "text": "Test Subject", "update_successful": true }, "group_description": { "text": "Test Description", "update_successful": true } } } ``` **部分失败:** 响应示例 ```json { "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44", "type": "whatsapp_group_settings_update", "eventTime": "2026-09-03T08:20:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_settings_update", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:20:00.000Z", "profile_picture": { "mime_type": "image/jpeg", "update_successful": true, "sha256": "PHOTO_HASH" }, "group_subject": { "text": "Test Subject", "update_successful": false, "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "title": "ERROR_TITLE", "error_data": { "details": "ERROR_DETAILS" } } ] }, "group_description": { "text": "Test Description", "update_successful": false, "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "title": "ERROR_TITLE", "error_data": { "details": "ERROR_DETAILS" } } ] }, "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "error_data": { "details": "ERROR_DETAILS" } } ] } } ``` **全部失败:** 响应示例 ```json { "id": "8b3f4c66-3d6d-4d30-bf4e-9c0d3b2a5e44", "type": "whatsapp_group_settings_update", "eventTime": "2026-09-03T08:20:00.000Z", "body": { "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "type": "group_settings_update", "request_id": "REQUEST_ID", "timestamp": "2026-09-03T08:20:00.000Z", "profile_picture": { "mime_type": "image/jpeg", "sha256": "PHOTO_HASH", "update_successful": false, "errors": [ { "code": "ERROR_CODE", "message": "ERROR_MESSAGE", "title": "ERROR_TITLE", "error_data": { "details": "ERROR_DETAILS" } } ] }, "group_subject": { "text": "Test Subject", "update_successful": false } } } ``` ## **群组状态变更（​whatsapp\_group\_status\_update​）** 当您管理的群组被暂停或解除暂停时触发该事件：`whatsapp_group_status_update`，对应订阅字段 `group_status_update`。`type` 字段区分子事件：`group_suspend`（被暂停）、`group_suspend_cleared`（解除暂停）。 | **字段** | **数据类型** | **是否必填** | **描述** | | --------- | -------- | -------- | ------------------------------------------------- | | group\_id | String | 是 | 小组 ID | | type | String | 是 | 子事件类型，可选值：`group_suspend`、`group_suspend_cleared` | | timestamp | String | 是 | 事件触发时间 | **group\_suspend:** 响应示例 ```json { "id": "9c4a5d77-4e7e-4e41-c05f-ad1e4c3b6f55", "type": "whatsapp_group_status_update", "eventTime": "2026-09-03T08:30:00.000Z", "body": { "type": "group_suspend", "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "timestamp": "2026-09-03T08:30:00.000Z" } } ``` **group\_suspend\_cleared:** 响应示例 ```json { "id": "9c4a5d77-4e7e-4e41-c05f-ad1e4c3b6f55", "type": "whatsapp_group_status_update", "eventTime": "2026-09-03T08:35:00.000Z", "body": { "type": "group_suspend_cleared", "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "timestamp": "2026-09-03T08:35:00.000Z" } } ``` ## **群消息状态（​whatsapp\_group\_message\_status\_updated​）** 当发送群组消息时，按消息生命周期（已发送 / 发送失败 / 已送达 / 已读）触发该事件：`whatsapp_group_message_status_updated`，对应 `whatsapp_message_status_updated` 事件下 `recipient_type=group` 的子集。本事件也用于**聚合**回执：相同消息同一状态类型在接近时间内合并；每个回执只关联​**单条消息 + 单个群组 + 单种状态类型**​。计费类目为 `group_marketing` / `group_utility` / `group_service`，`PRICING_MODEL` 为 `PMP`，`IS_BILLABLE` 标识是否计费。 注：接收群组用户消息的上行回执仍走 `whatsapp_mo_message_received`，仅在 `message` 对象中额外携带 `group_id` 字段，且 `from` 指向发送参与者。 | **字段** | **数据类型** | **是否必填** | **描述** | | -------------------------- | -------- | -------- | -------------------------------------------------------------------------- | | id | String | 是 | Message Id | | accountName | String | 是 | API 账号 | | wabaId | String | 是 | Waba Id | | wamid | String | 是 | 群消息 ID | | status | String | 是 | 发送状态：`sent`、`failed`、`delivered`、`read` | | recipient\_id | String | 是 | 群组 ID（与单人回执`sendPhone`区分） | | recipient\_type | String | 是 | 固定值：`group` | | recipient\_participant\_id | String | 否 | 单个回执对应的群成员 WhatsApp 号码（聚合时同回执可包含多成员，详见 字段表 recipient\_participant\_ids 备注） | | conversation | JSON | 否 | 会话信息，status=delivered 时有值；含`id`、`initiateType`、`expireAt` | | errorData | JSON | 否 | 错误信息，status=failed 时有值；含`errorCode`、`errorMessage` | | billable | Boolean | 是 | 是否计费：true / false | | category | String | 是 | 群消息类型：`group_marketing`、`group_utility`、`group_service` | | price | String | 是 | 单价，保留 5 位小数 | | currency | String | 是 | 货币 | | pricing\_model | String | 否 | 固定值：`PMP` | | is\_billable | Boolean | 否 | 是否计费（与`billable`同义，命名沿用上游字段） | | conversation\_category | String | 否 | 计费类目（与`category`同义，命名沿用上游字段） | | uid | String | 否 | 客户批次号 | **sent:** 响应示例 ```json { "id": "ad5b6e88-5f8f-4f52-d160-be2f5d4c7066", "type": "whatsapp_group_message_status_updated", "eventTime": "2026-09-03T08:40:00.000Z", "body": { "id": "356139161272397824", "accountName": "IW123456", "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID", "wamid": "wamid.BgNODYxN...", "status": "sent", "recipient_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "recipient_type": "group", "recipient_participant_id": "WHATSAPP_USER_PHONE_NUMBER", "uid": "2002302023002010121", "currency": "USD" } } ``` **failed:** 响应示例 ```json { "id": "ad5b6e88-5f8f-4f52-d160-be2f5d4c7066", "type": "whatsapp_group_message_status_updated", "eventTime": "2026-09-03T08:40:00.000Z", "body": { "id": "356139161272397824", "accountName": "IW123456", "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID", "wamid": "wamid.BgNODYxN...", "status": "failed", "recipient_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "recipient_type": "group", "recipient_participant_id": "WHATSAPP_USER_PHONE_NUMBER", "uid": "2002302023002010121", "currency": "USD", "errorData": { "errorCode": "ERROR_CODE", "errorMessage": "ERROR_MESSAGE" } } } ``` 群消息的 delivered / read 聚合回执的 JSON 载荷样例：数据待补（`statuses[]` 数组、计费类目 `group_marketing` / `group_utility` / `group_service`、`PRICING_MODEL=PMP`、`IS_BILLABLE` 等字段排列以镜像源资料描述为准；触发表述为多参与者单消息或多消息单参与者的聚合规则已在表格中说明，完整 JSON 待与上游对齐后补全）。 **接收群组用户消息（上行）:** 响应示例 ```json { "id": "be6c7f99-6a90-5063-e271-cf3f6e5d8177", "type": "whatsapp_mo_message_received", "eventTime": "2026-09-03T08:50:00.000Z", "body": { "id": "63f5d602367ea403f8175a6c", "accountName": "IW123456", "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID", "wamid": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "from": "WHATSAPP_USER_PHONE_NUMBER", "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "customerProfile": { "name": "Jack" }, "to": "BUSINESS-PHONE-NUMBER", "sendTime": "2026-09-03T08:50:00.000Z", "type": "text", "text": { "body": "MESSAGE_BODY" } } } ``` **接收不支持的群组消息（上行）:** 响应示例 ```json { "id": "be6c7f99-6a90-5063-e271-cf3f6e5d8177", "type": "whatsapp_mo_message_received", "eventTime": "2026-09-03T08:50:00.000Z", "body": { "id": "63f5d602367ea403f8175a6c", "accountName": "IW123456", "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID", "wamid": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA", "from": "WHATSAPP_USER_PHONE_NUMBER", "group_id": "Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD", "customerProfile": { "name": "Jack" }, "to": "BUSINESS-PHONE-NUMBER", "sendTime": "2026-09-03T08:50:00.000Z", "type": "unknown", "errors": [ { "code": 130501, "details": "Group message types are not currently supported", "title": "Unsupported group message type" } ] } ```