Eventos de Webhooks de Meta

Esta guía documenta cómo procesamos automáticamente la información que llega a través de los webhooks de Meta (WhatsApp Business Cloud API). El sistema está diseñado para traducir toda respuesta a español, mantener tus bases de datos actualizadas y notificar de manera oportuna a los administradores del Workspace.

1. Alertas de Cuenta (account_alerts)

Informa sobre notificaciones críticas a nivel global de la cuenta de WhatsApp Business relacionadas principalmente con facturación o suspensiones del servicio.

• Principales motivos notificados por Meta:
  • INCREASED_CAPABILITIES_ELIGIBILITY_FAILED: Indica que el límite de mensajes no se puede aumentar debido a la actividad de mensajes anterior.
  • prepaid_zero_balance: Indica que el saldo prepago está agotado o bajo.
  • Suspensión de cuenta por falta de pago.
  • Alertas sobre límites de envío de mensajes.
• Acción: Dependiendo de la severidad proveída por Meta (Crítica o Advertencia), se envía una Alerta In-App y un Correo Electrónico a los propietarios y administradores del Workspace para que puedan tomar acciones sobre la facturación o los límites alcanzados en su Business Manager. Además, guardamos el registro de la última alerta recibida.

2. Actualizaciones de Cuenta (account_updates)

Cambios importantes en los permisos y estados de las cuentas de WhatsApp Business (WABA).

1. DISABLE_UPDATE (Baneo / Reactivación) — En caso de baneo, Meta deshabilita la cuenta de inmediato.

   • Acción: Se notifica a los administradores de la situación (Crítica). Automáticamente extraemos y procesamos la fecha del baneo al español para facilitar su lectura, y se desactiva el registro del WABA en el sistema.

2. ACCOUNT_VIOLATION (Infracciones de Política) — Meta detectó contenido que viola sus normativas (Ej. Armas, Adultos, Fraude, Spam).

   • Acción: Se extrae el tipo y descripción específica del reporte, se traduce al español y se genera una notificación de Advertencia. Se actualiza la base de datos de WABA con el estado detallado de infracción.

3. VERIFIED_ACCOUNT / REJECTED_ACCOUNT — Cambios en la verificación de tu negocio.

   • Acción: Actualizamos nuestro registro del estatus oficial de la empresa. Si el negocio es "Rechazado", alertamos a los administradores (Crítico).

3. Preferencias de Usuario (user_preferences)

Este webhook se activa automáticamente cuando un usuario final decide optar por no recibir mensajes o restringir la comunicación a través de interfaces nativas en la aplicación de WhatsApp (por ejemplo, al bloquear o tocar botones de darse de baja/opt-out interactivos).

• Eventos (opt_out):
  • Acción: Capturamos el evento silenciosamente buscando la referencia del cliente en nuestra base de datos para marcar su estado de suscripción a campañas como opted_out. Esto garantiza que respetaremos de forma automatizada las preferencias de privacidad y políticas de usuario, evadiendo el envío no deseado de campañas sin llenarte de alertas manuales.

4. Calidad del Teléfono (phone_number_quality_updates)

Detecta el reporte masivo o baja calidad por parte de los destinatarios. Puedes revisar las calidades (Verde, Amarillo, Rojo).

• Yellow / Warning: Se envían únicamente notificaciones dentro de la app a administradores y propietarios.
• Red / Critical: Se envían Notificaciones In-App + Correos Electrónicos. En ambos casos, el estatus base de la calidad se ajusta en Firestore (la colección Channels).

5. Calidad de Plantilla (template_quality_update)

Meta envía esta notificación de sistema cuando la calificación de calidad integral de una plantilla cambia, usualmente como resultado de retroalimentación de los usuarios, la tasa de bloqueos y la frecuencia de rebotes de los mensajes recibidos a través de la misma.

• Detección Rápida: Identificamos puntajes de calidad en estado Medio (Amarillo) o Bajo (Rojo). Las plantillas en rojo están en riesgo crítico o pausadas.
• Traducción con IA: Empleamos Inteligencia Artificial para traducir a español la justificación de Meta y de esa forma facilitar su comprensión a todo el equipo de ventas o soporte.
• Acción: Actualizamos la calificación general en el área del contenido de la plantilla en el Workspace y generamos la alerta unificada para el administrador.

6. Estado de Plantilla (template_status_update)

Te notifica cada vez que se emite un fallo al respecto del ciclo de vida de una de tus plantillas y describe si tu plantilla solicitada fue aprobada, si sufrió infracciones políticas continuas y si ha sido pausada o inhabilitada.

• Eventos Positivos (APPROVED, REINSTATED):

  • La plantilla enviada al Business Manager es aprobada y está apta para usar, o se le ha levantado una penalización previa.
  • Acción: Refrescamos la colección de plantillas con su estatus vigente de Activo y enviamos una notificación en plataforma a nivel Informativo.

• Eventos Restrictivos (REJECTED, DISABLED, FLAGGED, PAUSED, LOCKED, PENDING_DELETION):

  • La plantilla sufre una falla por incumplir las Guías de Meta, fue muy reportada por los usuarios o tiene errores de revisión recurrentes.
  • Acción: Extraemos los campos exactos de rejection_info (razones y recomendaciones de corrección). Utilizamos una tarea prioritaria con Inteligencia Artificial para traducir al español la información técnica desde la API, enviando reportes críticos para que tú o tu equipo corrijan su estructura y contenido lo antes posible. La advertencia es Multi-Canal (Notificaciones Push in-app y Correo).