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

> Occurs when WhatsApp group settings are updated, including successful and failed results.

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

## Triggers

Occurs when WhatsApp group settings are updated, including successful and failed results.

Subscribe to `whatsapp.group.settings_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.settings_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "requestId": "<REQUEST_ID>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "subject": "<SUBJECT>",
    "description": "<DESCRIPTION>",
    "settings": [
      {
        "name": "<NAME>",
        "text": "<TEXT>",
        "updateSuccessful": "<UPDATE_SUCCESSFUL_VALUE>"
      }
    ],
    "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.settings_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 settings update event
>
> Example payload when WhatsApp group settings are updated
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_settings_123",
>   "type": "whatsapp.group.settings_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_settings_update",
>     "type": "group_settings_update",
>     "requestId": "REQ_2",
>     "status": "updated",
>     "groupId": "120363345678901234@g.us",
>     "subject": "Updated Purchase Inquiry",
>     "description": "Updated group description.",
>     "settings": [
>       {
>         "name": "group_subject",
>         "text": "Updated Purchase Inquiry",
>         "updateSuccessful": true
>       },
>       {
>         "name": "group_description",
>         "text": "Updated group description.",
>         "updateSuccessful": true
>       }
>     ],
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Settings Updated
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_settings_123",
>   "type": "whatsapp.group.settings_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_settings_update",
>     "type": "group_settings_update",
>     "requestId": "REQ_2",
>     "status": "updated",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "subject": "Updated Purchase Inquiry",
>     "description": "Updated group description.",
>     "settings": [
>       {
>         "name": "group_subject",
>         "text": "Updated Purchase Inquiry",
>         "updateSuccessful": true
>       },
>       {
>         "name": "group_description",
>         "text": "Updated group description.",
>         "updateSuccessful": true
>       }
>     ],
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Settings Update Failed
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_settings_124",
>   "type": "whatsapp.group.settings_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_settings_update",
>     "type": "group_settings_update",
>     "requestId": "REQ_SETTINGS",
>     "status": "failed",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "subject": "New subject",
>     "settings": [
>       {
>         "name": "group_subject",
>         "text": "New subject",
>         "updateSuccessful": false,
>         "errors": [
>           {
>             "code": 131201,
>             "title": "Invalid group subject"
>           }
>         ]
>       }
>     ],
>     "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-settings-update-webhook-examples).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.