whatsapp.group.participants_update

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.

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.

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

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. 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. `approval_required`: New members must be approved before joining. `auto_approve`: New members can join without approval.
`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.

whatsappGroup.customerProfile

Parameter	Type	Required	Description
`name`	string	No	WhatsApp profile name.
`username`	string	No	WhatsApp username.

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.

whatsappGroup.addedParticipants[].customerProfile

Parameter	Type	Required	Description
`name`	string	No	WhatsApp profile name.
`username`	string	No	WhatsApp username.

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.

whatsappGroup.removedParticipants[].customerProfile

Parameter	Type	Required	Description
`name`	string	No	WhatsApp profile name.
`username`	string	No	WhatsApp username.

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.

whatsappGroup.failedParticipants[].customerProfile

Parameter	Type	Required	Description
`name`	string	No	WhatsApp profile name.
`username`	string	No	WhatsApp username.

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.

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.

whatsappGroup.contacts[].customerProfile

Parameter	Type	Required	Description
`name`	string	No	WhatsApp profile name.
`username`	string	No	WhatsApp username.

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.

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.

whatsappGroup.statuses[].conversation.origin

Parameter	Type	Required	Description
`type`	string	No	Conversation origin type.

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.

WhatsApp group participants update event

Example payload when WhatsApp group participants are added

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

Participant Added

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

Join Request Created

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

Participant Removal Failed

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

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.group.participants_update

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappGroup

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappGroup

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappGroup

Example