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

> Se produce cuando se actualiza el estado de suspensión de un grupo de WhatsApp.

Usa `whatsapp.group.status_update` para gestionar este evento en tu endpoint de webhook.

## Disparadores

Se produce cuando se actualiza el estado de suspensión de un grupo de WhatsApp.

Suscríbete a `whatsapp.group.status_update` cuando [configures tu endpoint de webhook](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Sintaxis

YCloud envía una solicitud HTTP `POST` a tu URL de webhook configurada. La siguiente estructura muestra una variante del payload. Los valores entre corchetes angulares son marcadores de posición; sus tipos se enumeran en **Parámetros**. Los campos opcionales y otras variantes se describen a continuación.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "whatsapp.group.status_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "webhookTime": "<WEBHOOK_TIME>"
  }
}
```

## Parámetros

Valida el encabezado HTTP `YCloud-Signature` antes de procesar el cuerpo JSON. Consulta la [validación de firma](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Envoltorio del evento

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `id` | string | Sí | ID único para el evento. Longitud mínima: `6`. Longitud máxima: `128`. |
| `type` | string | Sí | Siempre `whatsapp.group.status_update`. |
| `apiVersion` | string | Sí | La versión de la API utilizada para procesar este evento. |
| `createTime` | string (date-time) | Sí | La hora a la que se creó este evento, formateada en [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). Por ejemplo, `2022-06-01T12:00:00.000Z`. |

### Payload del evento

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `whatsappGroup` | object | No | Payload de `whatsappGroup` específico del evento. |

Los cuatro campos comunes del envoltorio son obligatorios. Los campos del payload dependen de la variante del evento. En cada tabla de objetos, **Obligatorio** aplica cuando su objeto principal está presente. Los campos opcionales pueden omitirse; un ejemplo no hace que un campo sea obligatorio.

#### whatsappGroup

| Parámetro | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `wabaId` | string | No | ID de la cuenta de WhatsApp Business. |
| `displayPhoneNumber` | string | No | El número de teléfono visible de los metadatos del webhook de WhatsApp. |
| `phoneNumberId` | string | No | ID del número de teléfono de WhatsApp. |
| `field` | string | No | Campo del webhook de WhatsApp que originó el evento del grupo.Valores: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`. |
| `type` | string | No | Tipo específico de evento de grupo de WhatsApp.Valores: `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 | El ID de solicitud devuelto por una operación asíncrona de la API para grupos. |
| `status` | string | No | Estado del webhook de grupos de WhatsApp.Valores: `created`, `failed`, `deleted`, `added`, `removed`, `left`, `requested`, `revoked`, `updated`, `suspended`, `suspend_cleared`, `sent`, `delivered`, `read`, `expired`. |
| `groupId` | string | No | ID del grupo de WhatsApp. |
| `messageId` | string | No | ID de mensaje grupal de YCloud. Solo está presente cuando el evento de estado está vinculado a un mensaje grupal saliente guardado. |
| `inviteLink` | string | No | El enlace de invitación al grupo. |
| `reason` | string | No | El motivo de un evento de participante, solicitud de unión o eliminación. |
| `initiatedBy` | string | No | Indica quién inició un evento de eliminación de participante.Valores: `business`, `participant`. |
| `joinRequestId` | string | No | El ID de la solicitud de unión. |
| `waId` | string | No | ID de usuario de WhatsApp para un evento de un solo participante. |
| `recipientUserId` | string | No | ID de usuario con ámbito comercial para un evento de un solo participante. |
| `parentRecipientUserId` | string | No | ID de usuario principal con ámbito comercial para un evento de un solo participante. |
| `customerProfile` | object | No | Información del perfil de cliente de WhatsApp. |
| `subject` | string | No | El asunto del grupo. |
| `description` | string | No | La descripción del grupo. |
| `joinApprovalMode` | string | No | Modo de aprobación de unión al grupo de WhatsApp.<ul><li>`approval_required`: Los miembros nuevos deben ser aprobados antes de unirse.</li><li>`auto_approve`: Los miembros nuevos pueden unirse sin aprobación.</li></ul> |
| `addedParticipants` | object\[] | No | Participantes añadidos al grupo. |
| `removedParticipants` | object\[] | No | Participantes eliminados del grupo. |
| `failedParticipants` | object\[] | No | Participantes que no se pudieron añadir o eliminar. |
| `settings` | object\[] | No | Detalles de la actualización de la configuración del grupo. |
| `errors` | object\[] | No | Errores devueltos por WhatsApp. |
| `contacts` | object\[] | No | Contactos incluidos en los webhooks de estado de mensajes grupales. |
| `statuses` | object\[] | No | Detalles del estado del mensaje grupal. |
| `webhookTime` | string (date-time) | No | La hora en que WhatsApp activó este webhook. |
| `dedupeKey` | string | No | Clave de idempotencia para desduplicar eventos de webhook grupales. |

> [accordion] whatsappGroup.customerProfile
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre de perfil de WhatsApp. |
> | `username` | string | No | Nombre de usuario de WhatsApp. |

> [accordion] whatsappGroup.addedParticipants\[]
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `input` | string | No | La entrada original del participante. |
> | `waId` | string | No | ID de usuario de WhatsApp. |
> | `recipientUserId` | string | No | ID de usuario con ámbito comercial. |
> | `parentRecipientUserId` | string | No | ID de usuario principal con ámbito comercial. |
> | `customerProfile` | object | No | Información del perfil de cliente de WhatsApp. |
> | `errors` | object\[] | No | Errores devueltos por WhatsApp para este participante. |

> [accordion] whatsappGroup.addedParticipants\[].customerProfile
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre de perfil de WhatsApp. |
> | `username` | string | No | Nombre de usuario de WhatsApp. |

> [accordion] whatsappGroup.removedParticipants\[]
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `input` | string | No | La entrada original del participante. |
> | `waId` | string | No | ID de usuario de WhatsApp. |
> | `recipientUserId` | string | No | ID de usuario en el ámbito del negocio. |
> | `parentRecipientUserId` | string | No | ID de usuario en el ámbito del negocio principal. |
> | `customerProfile` | object | No | Información del perfil de cliente de WhatsApp. |
> | `errors` | object\[] | No | Errores devueltos por WhatsApp para este participante. |

> [accordion] whatsappGroup.removedParticipants\[].customerProfile
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre de perfil de WhatsApp. |
> | `username` | string | No | Nombre de usuario de WhatsApp. |

> [accordion] whatsappGroup.failedParticipants\[]
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `input` | string | No | La entrada original del participante. |
> | `waId` | string | No | ID de usuario de WhatsApp. |
> | `recipientUserId` | string | No | ID de usuario en el ámbito del negocio. |
> | `parentRecipientUserId` | string | No | ID de usuario en el ámbito del negocio principal. |
> | `customerProfile` | object | No | Información del perfil de cliente de WhatsApp. |
> | `errors` | object\[] | No | Errores devueltos por WhatsApp para este participante. |

> [accordion] whatsappGroup.failedParticipants\[].customerProfile
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre de perfil de WhatsApp. |
> | `username` | string | No | Nombre de usuario de WhatsApp. |

> [accordion] whatsappGroup.settings\[]
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre del ajuste.Valores: `profile_picture`, `group_subject`, `group_description`. |
> | `text` | string | No | Valor de texto para actualizaciones de asunto o descripción. |
> | `updateSuccessful` | boolean | No | Indica si la actualización del ajuste se completó con éxito. |
> | `mimeType` | string | No | Tipo MIME para actualizaciones de la foto de perfil. |
> | `sha256` | string | No | Hash SHA-256 para actualizaciones de la foto de perfil. |
> | `errors` | object\[] | No | Errores devueltos por WhatsApp para este ajuste. |

> [accordion] whatsappGroup.contacts\[]
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `customerProfile` | object | No | Información del perfil de cliente de WhatsApp. |
> | `waId` | string | No | ID de usuario de WhatsApp. |
> | `recipientUserId` | string | No | ID de usuario en el ámbito del negocio. |
> | `parentRecipientUserId` | string | No | ID de usuario en el ámbito del negocio principal. |

> [accordion] whatsappGroup.contacts\[].customerProfile
>
> | Parámetro | Tipo | Obligatorio | Descripción |
> | - | - | - | - |
> | `name` | string | No | Nombre de perfil de WhatsApp. |
> | `username` | string | No | Nombre de usuario de WhatsApp. |

> [accordion] whatsappGroup.statuses\[]
>
> | Parámetro | Tipo | Requerido | Descripción |
> | - | - | - | - |
> | `id` | string | No | ID del mensaje de WhatsApp. |
> | `status` | string | No | Estado del mensaje.Valores: `sent`, `delivered`, `read`, `failed`, `expired`. |
> | `timestamp` | integer (int64) | No | Marca de tiempo Unix que indica cuándo se actualizó el estado del mensaje. |
> | `recipientId` | string | No | ID del grupo de destinatarios. |
> | `recipientType` | string | No | Tipo de destinatario.Valores: `group`. |
> | `recipientParticipantId` | string | No | ID de usuario de WhatsApp del participante destinatario. |
> | `recipientUserId` | string | No | ID de usuario con ámbito empresarial del participante destinatario. |
> | `parentRecipientUserId` | string | No | ID de usuario con ámbito empresarial principal del participante destinatario. |
> | `conversation` | object | No | Objeto de conversación de WhatsApp incluido en los webhooks de estado de mensajes de grupo. |
> | `pricing` | object | No | Información sobre precios incluida en los webhooks de estado de mensajes de grupo. |
> | `errors` | object\[] | No | Errores devueltos por WhatsApp. |

> [accordion] whatsappGroup.statuses\[].conversation
>
> | Parámetro | Tipo | Requerido | Descripción |
> | - | - | - | - |
> | `id` | string | No | ID de la conversación. |
> | `expirationTimestamp` | integer (int64) | No | Marca de tiempo Unix que indica cuándo caduca la conversación. |
> | `origin` | object | No | Los campos del objeto se detallan a continuación. |

> [accordion] whatsappGroup.statuses\[].conversation.origin
>
> | Parámetro | Tipo | Requerido | Descripción |
> | - | - | - | - |
> | `type` | string | No | Tipo de origen de la conversación. |

> [accordion] whatsappGroup.statuses\[].pricing
>
> | Parámetro | Tipo | Requerido | Descripción |
> | - | - | - | - |
> | `billable` | boolean | No | Indica si el mensaje es facturable. |
> | `pricingModel` | string | No | Modelo de precios. |
> | `type` | string | No | Tipo de precio. |
> | `category` | string | No | Categoría de precios de grupo sin procesar informada por Meta. YCloud no expone la asignación interna de MM Lite en este campo del webhook.Valores: `group_marketing`, `group_utility`, `group_service`. |

## Ejemplo

El siguiente JSON es el cuerpo entregado a tu receptor. Los ID, los números de teléfono y otros valores de la cuenta son ilustrativos.

> [accordion] Evento de actualización de estado de grupo de WhatsApp
>
> Carga útil de ejemplo cuando cambia el estado de suspensión de un grupo de WhatsApp
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_123",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend",
>     "status": "suspended",
>     "groupId": "120363345678901234@g.us",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Grupo suspendido
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_123",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend",
>     "status": "suspended",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

> [accordion] Suspensión de grupo cancelada
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "id": "evt_group_status_124",
>   "type": "whatsapp.group.status_update",
>   "apiVersion": "v2",
>   "createTime": "2026-05-13T00:00:00.000Z",
>   "whatsappGroup": {
>     "wabaId": "123456789012345",
>     "field": "group_status_update",
>     "type": "group_suspend_cleared",
>     "status": "suspend_cleared",
>     "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
>     "webhookTime": "2026-05-13T00:00:00.000Z"
>   }
> }
> ```

Tras verificar la firma y aceptar el evento de forma duradera, devuelve una respuesta `2xx`. Procesa el trabajo lento de forma asíncrona.

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

Para ver tutoriales de escenarios paso a paso, consulta los [ejemplos comentados](https://docs.ycloud.com/es/api-reference/guides/examples/webhook-examples/whatsapp-group-status-update-webhook-examples).


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