whatsapp.group.participants_update

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

Desencadenadores

Se produce cuando se actualizan los participantes de un grupo de WhatsApp o las solicitudes para unirse. Suscríbete a whatsapp.group.participants_update cuando configures tu webhook endpoint.

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 indican en Parámetros. Los campos opcionales y otras variantes se describen a continuación.

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

Parámetros

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

Envoltura 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.participants_update`.
`apiVersion`	string	Sí	La versión de la API utilizada para procesar este evento.
`createTime`	string (date-time)	Sí	Fecha y hora en 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 de la envoltura son obligatorios. Los campos del payload dependen de la variante del evento. En cada tabla de objetos, Obligatorio se aplica cuando su objeto primario está presente. Los campos opcionales se pueden omitir; una muestra de 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 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 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. 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 del evento de participante, solicitud de unión o eliminación.
`initiatedBy`	string	No	Indica quién inició el evento de eliminación de un 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 empresarial para un evento de un solo participante.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito empresarial 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 para unirse al grupo de WhatsApp. `approval_required`: Los nuevos miembros deben aprobarse 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 de mensajes grupales.
`statuses`	object[]	No	Detalles del estado del mensaje grupal.
`webhookTime`	string (date-time)	No	La hora en la que WhatsApp activó este webhook.
`dedupeKey`	string	No	Clave de idempotencia para deduplicar 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 empresarial.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito empresarial.
`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 con ámbito comercial.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito comercial.
`customerProfile`	object	No	Información del perfil del 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 con ámbito comercial.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito comercial.
`customerProfile`	object	No	Información del perfil del 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ó correctamente.
`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 este ajuste.

whatsappGroup.contacts[]

Parámetro	Tipo	Obligatorio	Descripción
`customerProfile`	object	No	Información del perfil del cliente de WhatsApp.
`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.

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	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 con ámbito empresarial del participante destinatario.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito empresarial del participante destinatario.
`conversation`	object	No	Objeto de conversación de WhatsApp incluido en los webhooks de estado de mensajes grupales.
`pricing`	object	No	Información sobre precios incluida en los webhooks de estado de mensajes grupales.
`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 caduca 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	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 grupales original notificada 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 corresponde al cuerpo entregado a tu receptor. Los ID, números de teléfono y otros valores de cuenta son solo ilustrativos.

Evento de actualización de participantes de grupo de WhatsApp

Ejemplo de carga útil cuando se agregan participantes a un grupo de WhatsApp

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

Participante agregado

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

Solicitud de unión creada

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

Error al eliminar participante

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

Después de 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 descripciones detalladas de distintos escenarios, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.group.participants_update

Desencadenadores

Sintaxis

Parámetros

Envoltura del evento

Payload del evento

whatsappGroup

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Envoltura del evento

​Payload del evento

​whatsappGroup

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Envoltura del evento

Payload del evento

whatsappGroup

Ejemplo