小组 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 成功: 响应示例
group_create 失败: 响应示例
group_delete 失败: 响应示例
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 载荷样例：数据待补（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
否
整体失败 / 部分失败时返回的顶层错误数组
全部成功: 响应示例
部分失败: 响应示例
全部失败: 响应示例
群组状态变更（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: 响应示例
group_suspend_cleared: 响应示例
群消息状态（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: 响应示例
failed: 响应示例
群消息的 delivered / read 聚合回执的 JSON 载荷样例：数据待补（statuses[] 数组、计费类目 group_marketing / group_utility / group_service、PRICING_MODEL=PMP、IS_BILLABLE 等字段排列以镜像源资料描述为准；触发表述为多参与者单消息或多消息单参与者的聚合规则已在表格中说明，完整 JSON 待与上游对齐后补全）。
接收群组用户消息（上行）: 响应示例
接收不支持的群组消息（上行）: 响应示例
最后更新于