Mensajes fantasma en WhatsApp API: causas y diagnóstico

Que WhatsApp Cloud API acepte una solicitud no demuestra que el mensaje haya llegado. Para comprobar la entrega debes guardar el identificador del mensaje y conciliar los estados que llegan al webhook. «Mensajes fantasma» es el nombre que damos a un problema de observabilidad: el panel muestra éxito mientras recepción no sabe qué recibió la clienta.

Esta es la revisión del caso publicado en agosto de 2026 sobre El Mago del Color, el salón de Bogotá cuyo sistema construimos. Conservamos la experiencia y las capturas históricas, distinguiendo lo observado, las sospechas de entonces y las reglas actuales. No es un incidente que estemos atribuyendo hoy a todas las cuentas de WhatsApp.

1 · Qué ocurrió en el caso y qué no pudimos dar por probado

El relato de implementación registra una clienta que informó no haber recibido los cuatro mensajes que el panel daba por enviados. Al escribir ella de nuevo, la entrada funcionó. La revisión posterior planteó que una campaña manual de alrededor de 50 mensajes también podía estar afectada.

Ese segundo alcance era una sospecha, no una entrega fallida demostrada para cada destinataria. Sin trazabilidad individual no se puede concluir que nadie recibió la campaña ni reconstruir una tasa de entrega. La lección fue corregir el panel para que no confundiera la aceptación de una solicitud con el resultado final.

El historial técnico local sitúa el trabajo sobre la ventana y los estados en julio de 2026. Otro incidente documentado a comienzos de agosto afectó durante tres días a los envíos de plantillas y se relacionó en esa cuenta con un problema de pagos. Son antecedentes de esa operación; revisar el código local no comprueba el estado actual de la cuenta.

2 · Aceptado, enviado, entregado y leído no son lo mismo

La colección oficial de Meta describe el objeto de estados, su identificador y los errores de entrega. Una solicitud también puede fallar de forma inmediata. No todos los rechazos ocurren después de un HTTP 200 y la ausencia de un estado no demuestra por sí sola un fallo del destinatario.

Un panel útil distingue esas etapas y muestra hora, último estado conocido y error. Para un evento comercial, la comprobación sigue en la agenda o el pago: leer un mensaje no completa una cita.

3 · La ventana de 24 horas: el reloj parte de la clienta

En WhatsApp Business Platform, cada mensaje del usuario abre o renueva una ventana de atención de 24 horas. Dentro se puede responder sin plantilla; fuera necesitas una plantilla aprobada. Enviar una plantilla no reinicia la ventana de texto libre: la respuesta del usuario sí lo hace. La política oficial establece esta distinción y las responsabilidades sobre permisos y bajas.

La implementación revisada registra el último mensaje entrante y evita tratar un envío fuera de ventana como una comunicación confirmada. Su código maneja, entre otros, el error 131047 como un fallo relacionado con esa ventana. Para diagnosticar otro sistema, revisa el payload concreto y el catálogo vigente de errores de Meta; no deduzcas la causa solo por un texto del panel.

El recorrido de alta, la verificación y la aprobación de plantillas son procesos separados. La guía de aprobación de WhatsApp API los explica; este caso se concentra en el seguimiento después de intentar enviar.

4 · Un problema de cuenta necesita una alerta distinta

En el incidente de agosto, el código 131042 se investigó como un problema de pago de la cuenta. El relato registró indicadores generales favorables mientras fallaban las plantillas. Eso no convierte dicho código en prueba universal de una factura impaga: hay que revisar el detalle del error, facturación y elegibilidad de la cuenta afectada.

La arquitectura local separa fallos individuales de incidentes de cuenta y guarda una alerta en el panel. WhatsApp es una vía adicional de aviso; no debe ser la única cuando ese mismo canal está fallando.

También importa cómo se cierra la alerta. El módulo revisado considera entregas posteriores y antigüedad del incidente. Una alerta atenuada o cerrada por tiempo no prueba que el canal volvió a funcionar: conserva la incertidumbre y verifica un envío autorizado antes de dar por resuelto el problema. No hace falta contactar clientas para probar; puedes usar destinatarios de prueba habilitados.

5 · Plantillas con voz de marca y estado comprobado

Esta plantilla pertenece a la implementación histórica descrita. Su texto se conserva sin cambios; que aparezca aprobada en una captura de agosto no confirma su estado actual ni garantiza la aprobación o entrega de una copia en otra cuenta.

El permiso para contactar, la categoría, el idioma, las variables y la disponibilidad de la plantilla se comprueban antes del envío. La aprobación no sustituye el consentimiento ni elimina los límites del canal. Diseña una salida clara y procesa también las bajas que lleguen por escrito o por otros medios.

En este sistema se usa el botón «No quiero más promos». Lo importante es que la integración reconozca esa acción y la solicitud de baja, no que todos los negocios copien una etiqueta literal. Mantener una correspondencia estable entre botones, identificadores y lógica evita errores; el texto visible puede cambiar según el diseño.

6 · Guardar un borrador hasta que la persona responda

El código local incluye una cola para el mensaje que el equipo quiere dejar preparado cuando la ventana está cerrada. La interfaz puede ofrecer una plantilla de contacto y guardar el texto para intentar enviarlo cuando entre una respuesta válida. No permite enviar texto libre fuera de ventana ni garantiza que la persona responda.

• Un borrador pendiente por conversación: el último reemplaza al anterior.
• Caducidad de siete días: es una regla de esta implementación, no un plazo impuesto por Meta.
• Reclamación transaccional: un proceso toma el borrador para evitar que varios eventos lo procesen a la vez.
• Baja antes de continuar: si la respuesta solicita dejar de recibir mensajes, el borrador se cancela.
• Continuidad humana: el flujo contempla pausar el agente tras procesar el mensaje del equipo.

El registro histórico describe una prueba de ocho intentos concurrentes en la que uno ganó la reclamación. Eso comprueba el escenario probado, no una garantía de entrega exactamente una vez de extremo a extremo. La base de datos y una API externa no forman una única transacción: fallos, reintentos y estados posteriores requieren conciliación. La documentación de transacciones de Firestore explica el alcance de esa operación en la base.

Incluso una función interna llamada wasDelivered debe interpretarse por su lógica: un filtro de ventana o un resultado de envío no reemplaza un estado delivered del webhook. La interfaz debe comunicar qué se ha comprobado realmente.

7 · Cuando la propia alerta confundió aprobación con error

El caso también documentó una notificación cuyo texto decía «reportó error» al anunciar un cambio de plantilla que era favorable. Se conserva el ejemplo histórico para mostrar el problema de redacción y severidad; no es una alerta activa.

Una plantilla para errores no sirve para cualquier noticia. Distingue aprobación, rechazo y avisos informativos. Si el canal disponible obliga a usar un mensaje que cambia el sentido, muestra el evento correctamente en el panel y usa otra vía adecuada. Un aviso fuera de WhatsApp sigue necesitando permisos y configuración.

8 · Crear y revisar una plantilla: recorrido histórico de agosto

Las capturas siguientes documentan la interfaz usada entonces. Nombres de menús, avisos y opciones pueden cambiar; revisa la cuenta actual y la documentación enlazada. Para preparar activos y pruebas, usa el checklist de WhatsApp API.

1. Revisar plantillas y avisos

Comprueba categoría, estado y notificaciones de recategorización. El plazo o posibilidad de revisión se consulta en el aviso vigente; esta captura no establece un plazo universal de apelación. Un aviso para compartir datos tampoco obliga a activar esa opción para completar este diagnóstico.

2. Elegir finalidad, nombre e idioma

Selecciona la categoría que corresponda al contenido. Verifica que nombre, variante de idioma y parámetros coincidan con la solicitud real. No uses contenido promocional como si fuera un simple aviso de servicio.

3. Preparar variables y revisar la vista previa

En aquella sesión se observó un problema al escribir las llaves manualmente en el editor. No significa que toda variable escrita a mano sea inválida en todas las interfaces o APIs. Usa el control disponible, verifica sintaxis y espacios y aporta ejemplos ficticios cuando se soliciten; evita datos reales en las muestras.

4. Comprobar salida y contenido aprobado

Prueba que la acción de baja actualiza el estado de contacto y detiene los envíos correspondientes. El nombre de la plantilla o una marca verde en una captura no sustituyen esa prueba.

5. Enviar a revisión y verificar el estado posterior

El registro de agosto indica que dos de las tres plantillas se aprobaron en minutos. Es el tiempo observado en ese caso; no se ofrece como plazo de Meta ni como resultado de seguir estas instrucciones. Antes de usar una plantilla revisa su estado, categoría y disponibilidad reales.

9 · Checklist de diagnóstico para tu integración

1. Guarda identificador, fecha, tipo de mensaje y resultado inicial, con acceso restringido.
2. Comprueba que llegan los eventos statuses y se correlacionan con el mensaje correcto.
3. Separa enviado, entregado, leído, fallido y sin confirmación; conserva errores y tiempos.
4. Revisa último mensaje entrante, permisos, plantilla, idioma y variables.
5. Distingue un fallo puntual de un posible incidente de cuenta, sin extrapolar a toda la base.
6. Configura alertas comprensibles y una vía de consulta independiente del canal afectado.
7. Prueba expiración, baja, concurrencia y reintentos con datos ficticios y destinatarios autorizados.

La meta no es prometer que todos los mensajes llegarán: es saber qué pasó, actuar sobre fallos y no marcar como realizada una acción sin la evidencia correspondiente. Si automatizas reservas, conecta también la confirmación de agenda y el seguimiento de inasistencias del salón.

Consulta el proyecto Luna WhatsApp o cuéntanos qué estado muestra tu integración. Comparte una descripción o registros anonimizados; no envíes tokens, números de clientas ni conversaciones privadas. El diagnóstico distingue configuración pendiente, lógica del panel y trazabilidad de entrega.