Webhook user_preferences de WhatsApp: cuando un cliente deja de recibir o reanuda los mensajes de marketing
El webhook user_preferences informa a una empresa de que un usuario de WhatsApp dejó de recibir o volvió a recibir sus mensajes de marketing desde el ajuste Ofertas y anuncios. Cada evento incluye la categoría marketing_messages, un valor stop o resume, una frase de detalle, el wa_id y el BSUID del usuario, y una marca de tiempo Unix. Las opciones Interesado y No interesado de ese mismo ajuste no lo activan.
easyCoexistence conecta el número de tu app de WhatsApp Business con la Cloud API de Meta mediante Coexistencia, así que tu IA y tus automatizaciones funcionan en el número que sigues usando en la app.
Valores que puede tomar una preferencia: stop y resume, ambos en la categoría marketing_messages.
El código del estado fallido para una plantilla de marketing enviada a un usuario que dejó de recibir tus mensajes de marketing.
Dónde envía Meta user_preferences: no es un campo que una WhatsApp Business Account o un número puedan anular.
El permiso que necesita una app para los webhooks distintos de messages y calls, incluido user_preferences.
¿Qué activa el webhook user_preferences?
Que un cliente abra Ofertas y anuncios en WhatsApp y elija dejar de recibir, o más tarde volver a recibir, mensajes de marketing de tu empresa. Esas dos acciones son los únicos disparadores. El mismo ajuste también permite marcar Interesado o No interesado, y esa valoración no envía ningún webhook, aunque No interesado puede reducir el límite de marketing por usuario entre tú y ese cliente, y abre una segunda pantalla que ofrece dejar de recibir por completo los mensajes de marketing. Solo si el cliente pulsa entonces la opción de dejar de recibirlos se activa user_preferences.
¿Qué contiene el payload?
Un array user_preferences junto a un array contacts, bajo el nombre de campo user_preferences. Aquí la marca de tiempo es un entero, mientras que los webhooks de estado la envían como cadena. wa_id se omite cuando el cliente usa un nombre de usuario y no se puede compartir su número de teléfono; user_id, cuando los ID de usuario con alcance de empresa no están habilitados para tu empresa, y parent_user_id, salvo que los BSUID padre estén activados. Este es el ejemplo de Meta para una reanudación:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824"
}
],
"user_preferences": [
{
"wa_id": "16505551234",
"user_id": "US.13491208655302741918",
"parent_user_id": "US.ENT.506847293015824",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1731705721
}
]
},
"field": "user_preferences"
}
]
}
]
}¿Qué debe hacer tu sistema con una detención?
Registrarla asociada al cliente y excluirlo de todos los envíos de marketing hasta que llegue una reanudación. El campo detail dice «User requested to stop marketing messages» o «User requested to resume marketing messages», pero lo que debe leer el código es value.
- Guarda la preferencia por BSUID y por número de teléfono, ya que cualquiera de los dos puede faltar en un evento concreto.
- Excluye al cliente de los envíos de plantillas de marketing; Meta los rechazaría de todos modos con 131050.
- Aplícala solo por cliente: Meta nunca aplica una preferencia a nivel de BSUID padre.
- Al reanudar, levanta la exclusión y conserva tu propio registro de consentimiento, como exige la política de consentimiento de Meta.
¿Qué pasa si user_preferences nunca llega a tu servidor?
Meta aplica la detención de todos modos, así que un webhook perdido te cuesta un envío fallido, no un incumplimiento de política. Cuando envías una plantilla de marketing a alguien que dejó de recibirlas, la API acepta la petición, no envía el mensaje y activa un webhook de estado con status failed, código 131050 y el título «Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business». Trata ese fallo exactamente igual que un evento de detención: regístralo y excluye a ese cliente de los siguientes envíos de marketing.
¿Cómo funciona esto en un número conectado mediante easyCoexistence?
user_preferences no está entre los campos para los que Meta permite anular el destino, así que Meta solo lo entrega al callback predeterminado de la app suscrita a la cuenta. En un número conectado mediante easyCoexistence, esa app es la de easyCoexistence, que hoy no está suscrita a user_preferences, así que el evento no llega ni a un destino directo ni a una Forward URL. El estado fallido 131050 sí llega, porque viaja por el campo messages.
Si tu IA envía plantillas de marketing con send_template, mantén la lista de detenciones en tu propio sistema y consúltala antes de enviar: easyCoexistence no la mantiene.
Errores comunes
- Tratar No interesado como una detención. No envía webhook ni detiene la entrega, aunque puede reducir el límite de marketing por usuario para ese cliente.
- Usar wa_id como única clave de las preferencias. Se omite en clientes con nombre de usuario cuyo número no se puede compartir; guarda también el BSUID.
- Aplicar una detención a todos los usuarios bajo un BSUID padre. Meta aplica las preferencias por usuario, nunca a nivel padre.
- Reintentar tras un 131050 en lugar de registrarlo como detención. Cada reintento falla de la misma manera.
Las plantillas de marketing que envías por esta vía salen desde tu propia WhatsApp Business Account, y los estados fallidos que indican que un cliente dejó de recibir tu marketing llegan a tu servidor directamente o como reenvíos firmados. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que añades números, con los primeros 3 días gratis.
Preguntas frecuentes
¿Una detención también bloquea las respuestas a los mensajes que me escribe el cliente?
La documentación de Meta indica que la detención abarca los mensajes de marketing, y el error que devuelve menciona los mensajes de marketing. Las respuestas a un cliente que te escribió son mensajes de servicio, una categoría distinta.
¿Bloquear a la empresa activa user_preferences?
No. El webhook solo se activa al detener o reanudar en el ajuste Ofertas y anuncios. Bloquear es una acción aparte y no se informa en este campo.
¿Una reanudación cuenta como consentimiento (opt-in)?
Significa que el cliente eligió volver a recibir tus mensajes de marketing. Tus propias obligaciones de consentimiento según la política de Meta siguen vigentes, así que guarda el registro de cómo y cuándo ese cliente aceptó recibir tus mensajes.
¿A qué campo de webhook me tengo que suscribir?
A user_preferences, en el App Dashboard, en WhatsApp > Configuration, dentro de la app suscrita a la WhatsApp Business Account. Es un campo distinto de messages y necesita el permiso whatsapp_business_management.
Sigue leyendo
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisVerificado el