whatsapp.user.preferences

Usa whatsapp.user.preferences para gestionar este evento en tu endpoint de webhook.

Disparadores

Se produce cuando un usuario de WhatsApp deja de recibir mensajes de marketing o reanuda su recepción. Suscríbete a whatsapp.user.preferences cuando configures tu endpoint de webhook.

Sintaxis

YCloud envía una solicitud HTTP POST a la URL de webhook que hayas configurado. La siguiente estructura muestra una variante de la carga útil. 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.user.preferences",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappUserPreference": {
    "wabaId": "<WABA_ID>",
    "businessPhoneNumber": "<BUSINESS_PHONE_NUMBER>",
    "businessPhoneId": "<BUSINESS_PHONE_ID>",
    "contactName": "<CONTACT_NAME>",
    "contactPhoneNumber": "<CONTACT_PHONE_NUMBER>",
    "userId": "<USER_ID>",
    "parentUserId": "<PARENT_USER_ID>",
    "detail": "<DETAIL>",
    "category": "<CATEGORY>",
    "value": "<VALUE>",
    "timestamp": "<TIMESTAMP>"
  }
}

Parámetros

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

Sobre 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.user.preferences`.
`apiVersion`	string	Sí	Versión de la API utilizada para procesar este evento.
`createTime`	string (date-time)	Sí	Hora a la que se creó este evento, con formato según RFC 3339. Por ejemplo, `2022-06-01T12:00:00.000Z`.

Carga útil del evento

Parámetro	Tipo	Obligatorio	Descripción
`whatsappUserPreference`	object	No	Carga útil de `whatsappUserPreference` 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 se aplica cuando su objeto principal está presente. Los campos opcionales pueden omitirse; que aparezcan en un ejemplo no hace que sean obligatorios.

whatsappUserPreference

Parámetro	Tipo	Obligatorio	Descripción
`wabaId`	string	No	ID de la cuenta de WhatsApp Business.
`businessPhoneNumber`	string	No	Número de teléfono en formato E.164.
`businessPhoneId`	string	No	ID del número de teléfono.
`contactName`	string	No	Nombre de usuario de WhatsApp.
`contactPhoneNumber`	string	No	Número de teléfono del usuario de WhatsApp. Número de teléfono en formato E.164.
`userId`	string	No	El ID de usuario con alcance empresarial (BSUID) del usuario de WhatsApp.
`parentUserId`	string	No	El ID de usuario principal con alcance empresarial del usuario de WhatsApp. Se omite cuando los BSUID principales no están habilitados.
`detail`	string	No	Descripción de la preferencia de mensajes de marketing.
`category`	string	No	Categoría de preferencia informada por WhatsApp, por ejemplo `marketing_messages`.
`value`	string	No	Preferencia de mensajes de marketing.
`timestamp`	string	No	Marca de tiempo Unix que indica cuándo se activó el webhook.

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.

{
  "id": "evt_example_whatsapp_user_preferences",
  "type": "whatsapp.user.preferences",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappUserPreference": {
    "wabaId": "whatsapp-business-account-id",
    "businessPhoneNumber": "+12025550123",
    "businessPhoneId": "1234567890123456",
    "contactName": "Example customer",
    "contactPhoneNumber": "+12025550124",
    "userId": "US.13491208655302741918",
    "parentUserId": "US.ENT.11815799212886844830",
    "detail": "User requested to stop marketing messages",
    "category": "marketing_messages",
    "value": "stop",
    "timestamp": "1779796800000"
  }
}

Tras verificar la firma y aceptar de forma duradera el evento, devuelve una respuesta 2xx. Procesa las tareas lentas de forma asíncrona.

HTTP/1.1 200 OK

Para ver análisis detallados de situaciones hipotéticas, consulta los ejemplos anotados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.user.preferences

Disparadores

Sintaxis

Parámetros

Sobre del evento

Carga útil del evento

whatsappUserPreference

Ejemplo

​Disparadores

​Sintaxis

​Parámetros

​Sobre del evento

​Carga útil del evento

​whatsappUserPreference

​Ejemplo

Disparadores

Sintaxis

Parámetros

Sobre del evento

Carga útil del evento

whatsappUserPreference

Ejemplo