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

> Se produce cuando se actualizan los participantes de un grupo de WhatsApp o las solicitudes para unirse.

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](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 indican 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.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](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

### 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](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 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.<ul><li>`approval_required`: Los nuevos miembros deben aprobarse antes de unirse.</li><li>`auto_approve`: Los nuevos miembros 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 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. |

> [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 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. |

> [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 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. |

> [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 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. |

> [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ó 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. |

> [accordion] 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. |

> [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 | 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. |

> [accordion] 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. |

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

> [accordion] 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.

> [accordion] Evento de actualización de participantes de grupo de WhatsApp
>
> Ejemplo de carga útil cuando se agregan participantes a un grupo de WhatsApp
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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"
>   }
> }
> ```

> [accordion] Participante agregado
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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"
>   }
> }
> ```

> [accordion] Solicitud de unión creada
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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"
>     }
>   }
> }
> ```

> [accordion] Error al eliminar participante
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

Para ver descripciones detalladas de distintos escenarios, consulta los [ejemplos comentados](https://docs.ycloud.com/es/api-reference/guides/examples/webhook-examples/whatsapp-group-participants-update-webhook-examples).


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