> ## 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

> Occurs when WhatsApp group participants or join requests are updated.

Use `whatsapp.group.participants_update` to handle this event at your webhook endpoint.

## Triggers

Occurs when WhatsApp group participants or join requests are updated.

Subscribe to `whatsapp.group.participants_update` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Syntax

YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below.

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

## Parameters

Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Event envelope

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. |
| `type` | string | Yes | Always `whatsapp.group.participants_update`. |
| `apiVersion` | string | Yes | The API version used to render this event. |
| `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. |

### Event payload

| Parameter | Type | Required | Description |
| - | - | - | - |
| `whatsappGroup` | object | No | Event-specific `whatsappGroup` payload. |

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

#### whatsappGroup

| Parameter | Type | Required | Description |
| - | - | - | - |
| `wabaId` | string | No | WhatsApp Business Account ID. |
| `displayPhoneNumber` | string | No | The display phone number from WhatsApp webhook metadata. |
| `phoneNumberId` | string | No | WhatsApp phone number ID. |
| `field` | string | No | WhatsApp webhook field that produced the group event.Values: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`. |
| `type` | string | No | Specific WhatsApp group event type.Values: `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 | No | The request ID returned by an asynchronous group API operation. |
| `status` | string | No | WhatsApp group webhook status.Values: `created`, `failed`, `deleted`, `added`, `removed`, `left`, `requested`, `revoked`, `updated`, `suspended`, `suspend_cleared`, `sent`, `delivered`, `read`, `expired`. |
| `groupId` | string | No | WhatsApp group ID. |
| `messageId` | string | No | YCloud group-message ID. Present only when the status event is linked to a saved outbound group message. |
| `inviteLink` | string | No | The group invite link. |
| `reason` | string | No | The reason for a participant, join request, or removal event. |
| `initiatedBy` | string | No | Indicates who initiated a participant removal event.Values: `business`, `participant`. |
| `joinRequestId` | string | No | The join request ID. |
| `waId` | string | No | WhatsApp user ID for a single participant event. |
| `recipientUserId` | string | No | Business-scoped user ID for a single participant event. |
| `parentRecipientUserId` | string | No | Parent business-scoped user ID for a single participant event. |
| `customerProfile` | object | No | WhatsApp customer profile information. |
| `subject` | string | No | The group subject. |
| `description` | string | No | The group description. |
| `joinApprovalMode` | string | No | WhatsApp group join approval mode.<ul><li>`approval_required`: New members must be approved before joining.</li><li>`auto_approve`: New members can join without approval.</li></ul> |
| `addedParticipants` | object\[] | No | Participants added to the group. |
| `removedParticipants` | object\[] | No | Participants removed from the group. |
| `failedParticipants` | object\[] | No | Participants that failed to be added or removed. |
| `settings` | object\[] | No | Group setting update details. |
| `errors` | object\[] | No | Errors returned by WhatsApp. |
| `contacts` | object\[] | No | Contacts included in group message status webhooks. |
| `statuses` | object\[] | No | Group message status details. |
| `webhookTime` | string (date-time) | No | The time at which WhatsApp triggered this webhook. |
| `dedupeKey` | string | No | Idempotency key for deduplicating group webhook events. |

> [accordion] whatsappGroup.customerProfile
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | WhatsApp profile name. |
> | `username` | string | No | WhatsApp username. |

> [accordion] whatsappGroup.addedParticipants\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `input` | string | No | The original participant input. |
> | `waId` | string | No | WhatsApp user ID. |
> | `recipientUserId` | string | No | Business-scoped user ID. |
> | `parentRecipientUserId` | string | No | Parent business-scoped user ID. |
> | `customerProfile` | object | No | WhatsApp customer profile information. |
> | `errors` | object\[] | No | Errors returned by WhatsApp for this participant. |

> [accordion] whatsappGroup.addedParticipants\[].customerProfile
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | WhatsApp profile name. |
> | `username` | string | No | WhatsApp username. |

> [accordion] whatsappGroup.removedParticipants\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `input` | string | No | The original participant input. |
> | `waId` | string | No | WhatsApp user ID. |
> | `recipientUserId` | string | No | Business-scoped user ID. |
> | `parentRecipientUserId` | string | No | Parent business-scoped user ID. |
> | `customerProfile` | object | No | WhatsApp customer profile information. |
> | `errors` | object\[] | No | Errors returned by WhatsApp for this participant. |

> [accordion] whatsappGroup.removedParticipants\[].customerProfile
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | WhatsApp profile name. |
> | `username` | string | No | WhatsApp username. |

> [accordion] whatsappGroup.failedParticipants\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `input` | string | No | The original participant input. |
> | `waId` | string | No | WhatsApp user ID. |
> | `recipientUserId` | string | No | Business-scoped user ID. |
> | `parentRecipientUserId` | string | No | Parent business-scoped user ID. |
> | `customerProfile` | object | No | WhatsApp customer profile information. |
> | `errors` | object\[] | No | Errors returned by WhatsApp for this participant. |

> [accordion] whatsappGroup.failedParticipants\[].customerProfile
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | WhatsApp profile name. |
> | `username` | string | No | WhatsApp username. |

> [accordion] whatsappGroup.settings\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | Setting name.Values: `profile_picture`, `group_subject`, `group_description`. |
> | `text` | string | No | Text value for subject or description updates. |
> | `updateSuccessful` | boolean | No | Whether the setting update succeeded. |
> | `mimeType` | string | No | MIME type for profile picture updates. |
> | `sha256` | string | No | SHA-256 hash for profile picture updates. |
> | `errors` | object\[] | No | Errors returned by WhatsApp for this setting. |

> [accordion] whatsappGroup.contacts\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `customerProfile` | object | No | WhatsApp customer profile information. |
> | `waId` | string | No | WhatsApp user ID. |
> | `recipientUserId` | string | No | Business-scoped user ID. |
> | `parentRecipientUserId` | string | No | Parent business-scoped user ID. |

> [accordion] whatsappGroup.contacts\[].customerProfile
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | WhatsApp profile name. |
> | `username` | string | No | WhatsApp username. |

> [accordion] whatsappGroup.statuses\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | WhatsApp message ID. |
> | `status` | string | No | Message status.Values: `sent`, `delivered`, `read`, `failed`, `expired`. |
> | `timestamp` | integer (int64) | No | Unix timestamp indicating when the message status was updated. |
> | `recipientId` | string | No | Recipient group ID. |
> | `recipientType` | string | No | Recipient type.Values: `group`. |
> | `recipientParticipantId` | string | No | WhatsApp user ID of the recipient participant. |
> | `recipientUserId` | string | No | Business-scoped user ID of the recipient participant. |
> | `parentRecipientUserId` | string | No | Parent business-scoped user ID of the recipient participant. |
> | `conversation` | object | No | WhatsApp conversation object included in group message status webhooks. |
> | `pricing` | object | No | Pricing information included in group message status webhooks. |
> | `errors` | object\[] | No | Errors returned by WhatsApp. |

> [accordion] whatsappGroup.statuses\[].conversation
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | Conversation ID. |
> | `expirationTimestamp` | integer (int64) | No | Unix timestamp indicating when the conversation expires. |
> | `origin` | object | No | Object fields are listed below. |

> [accordion] whatsappGroup.statuses\[].conversation.origin
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `type` | string | No | Conversation origin type. |

> [accordion] whatsappGroup.statuses\[].pricing
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `billable` | boolean | No | Whether the message is billable. |
> | `pricingModel` | string | No | Pricing model. |
> | `type` | string | No | Pricing type. |
> | `category` | string | No | Raw group pricing category reported by Meta. YCloud does not expose the internal MM Lite mapping in this webhook field.Values: `group_marketing`, `group_utility`, `group_service`. |

## Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

> [accordion] WhatsApp group participants update event
>
> Example payload when WhatsApp group participants are added
>
> ```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] Participant Added
>
> ```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] Join Request Created
>
> ```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] Participant Removal Failed
>
> ```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"
>   }
> }
> ```

After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously.

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

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/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.