whatsapp.group.settings_update

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

Desencadenadores

Se produce cuando se actualiza la configuración de un grupo de WhatsApp, incluidos los resultados correctos y fallidos. Suscríbete a whatsapp.group.settings_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.settings_update",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappGroup": {
    "wabaId": "<WABA_ID>",
    "field": "<FIELD>",
    "type": "<TYPE>",
    "requestId": "<REQUEST_ID>",
    "status": "<STATUS>",
    "groupId": "<GROUP_ID>",
    "subject": "<SUBJECT>",
    "description": "<DESCRIPTION>",
    "settings": [
      {
        "name": "<NAME>",
        "text": "<TEXT>",
        "updateSuccessful": "<UPDATE_SUCCESSFUL_VALUE>"
      }
    ],
    "webhookTime": "<WEBHOOK_TIME>"
  }
}

Parámetros

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

Envoltorio 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.settings_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 envoltorio son obligatorios. Los campos de la carga útil dependen de la variante del evento. En cada tabla de objetos, Obligatorio se aplica cuando su objeto superior 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 procedente 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 del grupo. Valores: `group_lifecycle_update`, `group_participants_update`, `group_settings_update`, `group_status_update`, `messages`.
`type`	string	No	Tipo específico de evento del 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 para grupos.
`status`	string	No	Estado del webhook del grupo 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 del mensaje de grupo 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 para unirse 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 para unirse.
`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 miembros nuevos deben aprobarse 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 ni 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 del mensaje de grupo.
`statuses`	object[]	No	Detalles del estado del mensaje de grupo.
`webhookTime`	string (date-time)	No	La hora a la que WhatsApp activó este webhook.
`dedupeKey`	string	No	Clave de idempotencia para desduplicar eventos de webhook de grupo.

whatsappGroup.customerProfile

Parámetro	Tipo	Requerido	Descripción
`name`	string	No	Nombre de 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 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	Requerido	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	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.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	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.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 realizó 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 de cliente de WhatsApp.
`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.

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 de 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 de empresa del participante destinatario.
`parentRecipientUserId`	string	No	ID de usuario principal con ámbito de empresa 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 de precios incluida en los webhooks de estado de mensajes grupales.
`errors`	object[]	No	Errores devueltos por WhatsApp.

whatsappGroup.statuses[].conversation

Parámetro	Tipo	Requerido	Descripción
`id`	string	No	ID de conversación.
`expirationTimestamp`	integer (int64)	No	Marca de tiempo Unix que indica cuándo vence la conversación.
`origin`	object	No	Los campos del objeto se indican 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 precios.
`category`	string	No	Categoría de precios grupal sin procesar reportada por Meta. YCloud no expone el mapeo interno de MM Lite en este campo de 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 de ajustes de grupo de WhatsApp

Carga útil de ejemplo cuando se actualizan los ajustes de un grupo de WhatsApp

{
  "id": "evt_group_settings_123",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_2",
    "status": "updated",
    "groupId": "120363345678901234@g.us",
    "subject": "Updated Purchase Inquiry",
    "description": "Updated group description.",
    "settings": [
      {
        "name": "group_subject",
        "text": "Updated Purchase Inquiry",
        "updateSuccessful": true
      },
      {
        "name": "group_description",
        "text": "Updated group description.",
        "updateSuccessful": true
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

Ajustes actualizados

{
  "id": "evt_group_settings_123",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_2",
    "status": "updated",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "Updated Purchase Inquiry",
    "description": "Updated group description.",
    "settings": [
      {
        "name": "group_subject",
        "text": "Updated Purchase Inquiry",
        "updateSuccessful": true
      },
      {
        "name": "group_description",
        "text": "Updated group description.",
        "updateSuccessful": true
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

Error al actualizar los ajustes

{
  "id": "evt_group_settings_124",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_SETTINGS",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "New subject",
    "settings": [
      {
        "name": "group_subject",
        "text": "New subject",
        "updateSuccessful": false,
        "errors": [
          {
            "code": 131201,
            "title": "Invalid group subject"
          }
        ]
      }
    ],
    "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 situaciones, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.group.settings_update

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

whatsappGroup

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Envoltorio del evento

​Carga útil del evento

​whatsappGroup

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Carga útil del evento

whatsappGroup

Ejemplo