> 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/api-reference-en/whatsapp-business-api/webhook/group-webhook-events.md). # Group Webhook events This section covers event callbacks related to Group. To receive notifications of group metadata changes, enable the following fields in your WebHook subscription (each corresponds to the event types in the subsections below):`group_lifecycle_update`(group creation / deletion);`group_participants_update`(group member changes: join via invite link / request to join / cancel request / join request approved / removed / leave voluntarily);`group_settings_update`(group settings: topic / description / profile picture update);`group_status_update`(group suspended / suspension cleared). The events in this section all use the InnoPaas public envelope (`id`、`type`、`eventTime`、`body`) and the 5 InnoPaas event types in this section:`whatsapp_group_lifecycle_update`、`whatsapp_group_participants_update`、`whatsapp_group_settings_update`、`whatsapp_group_status_update`、`whatsapp_group_message_status_updated`。 **The public fields below apply to all events in this section (consistent with the common parameters above; only fields unique to group events or easily confused are listed here):** | **Field** | **Data type** | **Required** | **Description** | | ----------- | ------------- | ------------ | -------------------------------------------------------------- | | group\_id | String | Yes | Group ID, the group\_id returned by the Groups API | | type | String | Yes | Sub-event type, see each subsection | | timestamp | String | Yes | Event trigger time, UTC format yyyy-MM-dd'T'HH:mm:ss.SSS'Z' | | request\_id | String | No | Request ID, used for troubleshooting and correlating API calls | ## **Group lifecycle (whatsapp\_group\_lifecycle\_update)** This event is triggered when a group is created or deleted:`whatsapp_group_lifecycle_update`, corresponding subscription field `group_lifecycle_update`。`type` The fields distinguish sub-events:`group_create`(success / failure),`group_delete`(success / failure). | **Field** | **Data type** | **Required** | **Description** | | -------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | group\_id | String | Yes | Group ID | | type | String | Yes | Sub-event type, possible values:`group_create`、`group_delete` | | subject | String | No | Group topic;`returned when type=group_create`is returned;`returned when type=group_create`Topic used on failure | | invite\_link | String | No | Group invite link,`returned when type=group_create`and returned on success | | join\_approval\_mode | String | No | Group join approval mode:`auto_approve`(no approval required) /`approval_required`(approval required),`returned when type=group_create`and returned on success | | request\_id | String | No | Request ID | | timestamp | String | Yes | Event trigger time | | errors | Array | No | Error array returned on failure (structure same as the errors in the upstream message) | **group\_create success:** Response example ```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 failed:** Response example ```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 failed:** Response example ```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 succeeded** JSON payload example: data to be added (the successful create/delete payloads are missing key fields for verification; they will be completed after alignment with upstream; see above for the successful create payload). ## **Group participant changes (whatsapp\_group\_participants\_update)** This event is triggered when group members undergo the following changes:`whatsapp_group_participants_update`, corresponding subscription field `group_participants_update`Common sub-events: users join the group via invite link (`reason=invite_link`); users submit a join request (`reason=join_request`,`group_request_type=group_join_request_created`); users revoke a join request (`group_request_type=group_join_request_revoked`); one or more join requests approved (`reason=invite_link`,`type=group_participants_add`,`added_participants[]`); remove group members:`type=group_participants_remove`, may partially succeed / fully succeed / fully fail; group members leave voluntarily:`initiated_by` and `removed_participants[].wa_id` point to the departing member. | **Field** | **Data type** | **Required** | **Description** | | --------------------- | ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | group\_id | String | Yes | Group ID | | type | String | Yes | Sub-event type, possible values:`group_participants_add`、`group_participants_remove`etc. | | reason | String | No | Trigger reason, for example`invite_link`(join via invite link / join request approved) | | group\_request\_type | String | No | Join request type:`group_join_request_created`(requested),`group_join_request_revoked`(revoked) | | added\_participants | Array | No | List of added members, each item`{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}` | | removed\_participants | Array | No | List of removed members, each item`{"input": "phone_or_id", "wa_id": "WHATSAPP_USER_ID"}`; when leaving voluntarily`initiated_by`and the`wa_id`both point to the departing member | | initiated\_by | String | No | WhatsApp user ID that initiated this change (removal / leave scenario) | | request\_id | String | No | Request ID | | timestamp | String | Yes | Event trigger time | | errors | Array | No | Error array returned on failure | **Join request approved (bulk multiple members):** Response example ```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 payload example for other sub-events (users joining via invite link, join/cancel request, member removal success / partial failure / failure, member leaving voluntarily): data to be added (`type` The values and field order follow the mirrored source documentation; the complete JSON will be added after alignment with upstream; the trigger conditions and field definitions are based on the table above). ## **Group settings update (whatsapp\_group\_settings\_update)** This event is triggered when group settings (topic / description / profile picture) are updated:`whatsapp_group_settings_update`, corresponding subscription field `group_settings_update`。`update_successful` This field indicates whether this update was successful; on failure it is accompanied by the `errors` array. The overall update may succeed / partially fail / completely fail. | **Field** | **Data type** | **Required** | **Description** | | ------------------ | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | group\_id | String | Yes | Group ID | | type | String | Yes | Fixed value:`group_settings_update` | | profile\_picture | Object | No | Profile picture update result:`mime_type`(e.g. image/jpeg),`sha256`(returned on success),`update_successful`(Boolean),`errors`(returned only on failure) | | group\_subject | Object | No | Topic update result:`text`、`update_successful`(Boolean),`errors`(returned only on failure) | | group\_description | Object | No | Description update result:`text`、`update_successful`(Boolean),`errors`(returned only on failure) | | request\_id | String | No | Request ID | | timestamp | String | Yes | Event trigger time | | errors | Array | No | Top-level error array returned when the update overall fails / partially fails | **All successful:** Response example ```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 } } } ``` **Partial failure:** Response example ```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" } } ] } } ``` **Complete failure:** Response example ```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 } } } ``` ## **Group status changes (whatsapp\_group\_status\_update)** This event is triggered when a group you manage is suspended or unsuspended:`whatsapp_group_status_update`, corresponding subscription field `group_status_update`。`type` The fields distinguish sub-events:`group_suspend`(suspended),`group_suspend_cleared`(suspension cleared). | **Field** | **Data type** | **Required** | **Description** | | --------- | ------------- | ------------ | ----------------------------------------------------------------------- | | group\_id | String | Yes | Group ID | | type | String | Yes | Sub-event type, possible values:`group_suspend`、`group_suspend_cleared` | | timestamp | String | Yes | Event trigger time | **group\_suspend:** Response example ```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:** Response example ```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" } } ``` ## **Group message status (whatsapp\_group\_message\_status\_updated)** When sending a group message, this event is triggered according to the message lifecycle (sent / send failed / delivered / read):`whatsapp_group_message_status_updated`, corresponding to `whatsapp_message_status_updated` under the event `recipient_type=group` subset. This event is also used for**aggregation**receipts: receipts of the same message and same status type within a close time window are merged; each receipt only relates to**single message + single group + single status type**. Billing categories are `group_marketing` / `group_utility` / `group_service`,`PRICING_MODEL` is `PMP`,`IS_BILLABLE` indicates whether it is billable. Note: inbound receipts for receiving group user messages still go through `whatsapp_mo_message_received`, only in `message` object does it additionally carry the `group_id` field, and `from` points to the sending participant. | **Field** | **Data type** | **Required** | **Description** | | -------------------------- | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | String | Yes | Message Id | | accountName | String | Yes | API account | | wabaId | String | Yes | Waba Id | | wamid | String | Yes | Group message ID | | status | String | Yes | Sending status:`sent`、`failed`、`delivered`、`read` | | recipient\_id | String | Yes | Group ID (distinguished from one-to-one receipts`sendPhone`) | | recipient\_type | String | Yes | Fixed value:`group` | | recipient\_participant\_id | String | No | The WhatsApp number of the group member corresponding to a single receipt (when aggregated, the same receipt may include multiple members; see the note in the field table for recipient\_participant\_ids) | | conversation | JSON | No | Conversation info, present when status=delivered; includes`id`、`initiateType`、`expireAt` | | errorData | JSON | No | Error info, present when status=failed; includes`errorCode`、`errorMessage` | | billable | Boolean | Yes | Whether billable: true / false | | category | String | Yes | Group message type:`group_marketing`、`group_utility`、`group_service` | | price | String | Yes | Unit price, keep 5 decimal places | | currency | String | Yes | Currency | | pricing\_model | String | No | Fixed value:`PMP` | | is\_billable | Boolean | No | Whether billable (synonymous with`billable`and the naming follows the upstream field) | | conversation\_category | String | No | Billing category (with`category`and the naming follows the upstream field) | | uid | String | No | customer batch number | **sent:** Response example ```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:** Response example ```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" } } } ``` JSON payload example for aggregated delivered / read receipts for group messages: data to be added (`statuses[]` array, billing category `group_marketing` / `group_utility` / `group_service`、`PRICING_MODEL=PMP`、`IS_BILLABLE` etc. The field arrangement follows the mirrored source documentation; the aggregation rules for multiple participants for one message or multiple messages for one participant are described in the table; the complete JSON will be added after alignment with upstream). **Receiving group user message (inbound):** Response example ```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" } } } ``` **Receiving unsupported group message (inbound):** Response example ```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" } ] } ```