whatsapp.group.status_update

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.

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.

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

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. 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. `approval_required`: Los miembros nuevos deben ser aprobados antes de unirse. `auto_approve`: Los miembros nuevos pueden unirse sin aprobación.
`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.

whatsappGroup.customerProfile

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	No	Nombre de perfil de WhatsApp.
`username`	string	No	Nombre de usuario de WhatsApp.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

whatsappGroup.statuses[].conversation.origin

Parámetro	Tipo	Requerido	Descripción
`type`	string	No	Tipo de origen de la conversación.

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.

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

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

Grupo suspendido

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

Suspensión de grupo cancelada

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

Para ver tutoriales de escenarios paso a paso, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.group.status_update

Disparadores

Sintaxis

Parámetros

Envoltorio del evento

Payload del evento

whatsappGroup

Ejemplo

​Disparadores

​Sintaxis

​Parámetros

​Envoltorio del evento

​Payload del evento

​whatsappGroup

​Ejemplo

Disparadores

Sintaxis

Parámetros

Envoltorio del evento

Payload del evento

whatsappGroup

Ejemplo