whatsapp.group.lifecycle_update

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

Activadores

Ocurre cuando se crea o elimina un grupo de WhatsApp, incluidos los resultados correctos y fallidos. Suscríbete a whatsapp.group.lifecycle_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 de la carga útil. Los valores entre corchetes angulares son marcadores de posición; sus tipos se indican en Parámetros. Los campos opcionales y otras variantes se describen a continuación.

{
  "id": "<ID>",
  "type": "whatsapp.group.lifecycle_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "displayPhoneNumber": "<DISPLAY_PHONE_NUMBER>",
    "phoneNumberId": "<PHONE_NUMBER_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "requestId": "<REQUEST_ID>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "inviteLink": "<INVITE_LINK>",
    "subject": "<SUBJECT>",
    "description": "<DESCRIPTION>",
    "joinApprovalMode": "<JOIN_APPROVAL_MODE>",
    "webhookTime": "<WEBHOOK_TIME>",
    "dedupeKey": "<DEDUPE_KEY>"
  }
}

Parámetros

Valida el encabezado HTTP YCloud-Signature antes de procesar el cuerpo JSON. Consulta validación de firmas.

Sobre del evento

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único del evento. Longitud mínima: `6`. Longitud máxima: `128`.
`type`	string	Sí	Siempre `whatsapp.group.lifecycle_update`.
`apiVersion`	string	Sí	La versión de la API utilizada para generar este evento.
`createTime`	string (date-time)	Sí	La fecha y hora en que se creó este evento, formateada en RFC 3339. Por ejemplo, `2022-06-01T12:00:00.000Z`.

Carga útil del evento

Parámetro	Tipo	Obligatorio	Descripción
`whatsappGroup`	object	No	Carga útil de `whatsappGroup` específica del evento.

Los cuatro campos comunes del sobre son obligatorios. Los campos de la carga útil 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 generó el evento de grupo. Valores: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`.
`type`	string	No	Tipo de evento de grupo de WhatsApp específico. 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 asincrónica de la API de 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. Presente solo cuando el evento de estado está vinculado a un mensaje grupal de salida 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 participante único.
`recipientUserId`	string	No	ID de usuario en el ámbito del negocio para un evento de participante único.
`parentRecipientUserId`	string	No	ID de usuario en el ámbito del negocio principal para un evento de participante único.
`customerProfile`	object	No	Información del perfil del 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 nuevos miembros deben ser aprobados antes de unirse. `auto_approve`: Los nuevos miembros 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 pudieron añadirse o eliminarse.
`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 del mensaje grupal.
`statuses`	object[]	No	Detalles del estado del mensaje grupal.
`webhookTime`	string (date-time)	No	La fecha y hora en la que WhatsApp activó este webhook.
`dedupeKey`	string	No	Clave de idempotencia para deduplicar eventos de webhook del grupo.

whatsappGroup.customerProfile

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

whatsappGroup.addedParticipants[]

Parámetro	Tipo	Requerido	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 del cliente de WhatsApp.
`errors`	object[]	No	Errores devueltos por WhatsApp para este participante.

whatsappGroup.addedParticipants[].customerProfile

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

whatsappGroup.removedParticipants[]

Parámetro	Tipo	Requerido	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 de la empresa.
`parentRecipientUserId`	string	No	ID de usuario principal en el ámbito de la empresa.
`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	Requerido	Descripción
`name`	string	No	Nombre de perfil de WhatsApp.
`username`	string	No	Nombre de usuario de WhatsApp.

whatsappGroup.failedParticipants[]

Parámetro	Tipo	Requerido	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 de la empresa.
`parentRecipientUserId`	string	No	ID de usuario principal en el ámbito de la empresa.
`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	Requerido	Descripción
`name`	string	No	Nombre de perfil de WhatsApp.
`username`	string	No	Nombre de usuario de WhatsApp.

whatsappGroup.settings[]

Parámetro	Tipo	Requerido	Descripción
`name`	string	No	Nombre de la configuración. 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 de la configuración se realizó con éxito.
`mimeType`	string	No	Tipo MIME para actualizaciones de foto de perfil.
`sha256`	string	No	Hash SHA-256 para actualizaciones de foto de perfil.
`errors`	object[]	No	Errores devueltos por WhatsApp para esta configuración.

whatsappGroup.contacts[]

Parámetro	Tipo	Requerido	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 de la empresa.
`parentRecipientUserId`	string	No	ID de usuario principal en el ámbito de la empresa.

whatsappGroup.contacts[].customerProfile

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

whatsappGroup.statuses[]

Parámetro	Tipo	Obligatorio	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 destinatario.
`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 específico del negocio del participante destinatario.
`parentRecipientUserId`	string	No	ID de usuario principal específico del negocio 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	Obligatorio	Descripción
`id`	string	No	ID de la conversación.
`expirationTimestamp`	integer (int64)	No	Marca de tiempo Unix que indica cuándo expira la conversación.
`origin`	object	No	Los campos del objeto se detallan a continuación.

whatsappGroup.statuses[].conversation.origin

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

whatsappGroup.statuses[].pricing

Parámetro	Tipo	Obligatorio	Descripción
`billable`	boolean	No	Si el mensaje es facturable o no.
`pricingModel`	string	No	Modelo de precios.
`type`	string	No	Tipo de precio.
`category`	string	No	Categoría de precios en bruto para grupos reportada por Meta. YCloud no expone el mapeo interno 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, números de teléfono y otros valores de cuenta son ilustrativos.

Evento de actualización del ciclo de vida del grupo de WhatsApp

Ejemplo de payload cuando se crea un grupo de WhatsApp

{
  "id": "evt_group_lifecycle_123",
  "type": "whatsapp.group.lifecycle_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "displayPhoneNumber": "16315551111",
    "phoneNumberId": "1234567890123456",
    "field": "group_lifecycle_update",
    "type": "group_create",
    "requestId": "REQ_1",
    "status": "created",
    "groupId": "120363345678901234@g.us",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
    "subject": "New Purchase Inquiry",
    "description": "Group for purchase inquiries.",
    "joinApprovalMode": "auto_approve",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "dedupeKey": "123456789012345|REQ_1|group_lifecycle_update|group_create|created"
  }
}

Grupo creado

{
  "id": "evt_group_lifecycle_123",
  "type": "whatsapp.group.lifecycle_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "displayPhoneNumber": "16315551111",
    "phoneNumberId": "1234567890123456",
    "field": "group_lifecycle_update",
    "type": "group_create",
    "requestId": "REQ_1",
    "status": "created",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
    "subject": "New Purchase Inquiry",
    "description": "Group for purchase inquiries.",
    "joinApprovalMode": "auto_approve",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "dedupeKey": "123456789012345|REQ_1|group_lifecycle_update|group_create|created"
  }
}

Grupo eliminado

{
  "id": "evt_group_lifecycle_124",
  "type": "whatsapp.group.lifecycle_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_lifecycle_update",
    "type": "group_delete",
    "requestId": "REQ_DELETE",
    "status": "deleted",
    "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 las tareas lentas de forma asíncrona.

HTTP/1.1 200 OK

Para ver guías paso a paso de escenarios, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.group.lifecycle_update

Activadores

Sintaxis

Parámetros

Sobre del evento

Carga útil del evento

whatsappGroup

Ejemplo

​Activadores

​Sintaxis

​Parámetros

​Sobre del evento

​Carga útil del evento

​whatsappGroup

​Ejemplo

Activadores

Sintaxis

Parámetros

Sobre del evento

Carga útil del evento

whatsappGroup

Ejemplo