Mensaje de WhatsApp enviado y el cliente no lo recibe: causas y solución

Entender la cadena evita buscar en el lugar equivocado. Primero, tu sistema hace la llamada y la API la acepta (respuesta de éxito). Segundo, la instancia la pone en la cola, respetando el retraso configurado entre mensajes. Tercero, la sesión de WhatsApp la envía a los servidores de la plataforma (una palomita). Cuarto, el aparato del destinatario la recibe (dos palomitas) y luego la persona la lee.

Cada etapa tiene una causa típica de falla: datos errados en la primera, cola o desconexión en la segunda, restricción del número en la tercera y aparato o bloqueo del cliente en la cuarta. El glosario describe los estados de entrega.

Es la causa más frecuente. El número debe ir con código de país y solo dígitos, y algunos países tienen reglas propias de formato. Un teléfono fijo, una línea desactivada o un número mal digitado puede incluso ser aceptado por la API, pero no llegará a nadie.

Antes de las campañas y ante sospechas puntuales, verifica si el número tiene WhatsApp con el endpoint de verificación, que devuelve si cada número está registrado y su identificador. La herramienta de validar número hace lo mismo en la página. Limpiar la lista antes de enviar también mejora la reputación del número.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/chat/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"numbers":["5511999999999"]}'

Si la sesión se cayó, los mensajes no salen. Consulta el estado de la instancia: conectada, conectando o desconectada. Si está desconectada, hay que leer un nuevo código QR. Activa alertas de cambio de conexión en tu webhook para enterarte de inmediato y no por el cliente.

Los mensajes enviados durante la desconexión pueden no haber sido aceptados, así que conviene reenviar tras reconectar, con cuidado de no duplicar. Usa el historial de mensajes de la API para verificar qué salió de verdad antes de reenviar.

curl https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/instance/status \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

La instancia tiene un retraso mínimo y máximo entre mensajes, y las campañas usan intervalos aleatorios. En lotes grandes, el último mensaje puede tardar en salir, y quien mira temprano concluye que "no se fue". La respuesta del estado de la instancia muestra el retraso configurado.

Si el retraso está alto sin necesidad, ajústalo con cuidado: reducir demasiado el intervalo aumenta el riesgo de restricción. En campañas, sigue el avance por la carpeta del envío en vez de reenviar. Mira el envío masivo.

Si el cliente bloqueó tu número, el mensaje se queda con una sola palomita, sin entregar, y la plataforma no te avisa. Si su celular está sin internet o apagado, la segunda palomita aparece cuando vuelva. Una palomita por muchas horas y la segunda que nunca llega es el patrón clásico de bloqueo o aparato fuera de línea.

No insistas con reenvíos repetidos: aumentan las denuncias. Prueba un canal alternativo, como una llamada o un correo, y confirma con el cliente si puede ver tus mensajes. Quien acumule mensajes sin entrega repetidamente debe salir de la lista de envío.

Cuando WhatsApp limita el número, los mensajes pueden quedarse sin salir o salir solo a algunos contactos. El endpoint de límites informa cuántas conversaciones nuevas puede iniciar el número en este momento, lo que ayuda a distinguir una limitación de un error de integración.

Si la causa es una restricción, sigue el paso a paso del número bloqueado y revisa el comportamiento de envío con la matriz de riesgo. El uso por API no oficial no está previsto en los Términos de WhatsApp, y la decisión sobre la cuenta es de la plataforma.

1) Revisa el número: ¿tiene WhatsApp? ¿Formato y código de país correctos? 2) Revisa la instancia: ¿está conectada? 3) Revisa el historial: ¿el mensaje aparece en los mensajes de la instancia? 4) Revisa el webhook: ¿llegó el evento de estado? Usa el endpoint de entregas recientes y el de errores para ver si tu servidor respondió 2xx. 5) Revisa al destinatario: ¿te bloqueó, está sin internet o es un número que ya no responde?

Registrar el ID del mensaje devuelto por el envío permite cruzar todas las etapas. Si el problema es que el webhook no llega, mira la guía de recibir mensajes por webhook. Si el problema es general, la documentación de la API lista los endpoints de apoyo.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/message/find \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"chatid":"5511999999999@s.whatsapp.net","limit":20}'

curl "https://api.zapzapapi.com/api/v1/instances/SEU_INSTANCE_ID/webhook/deliveries?limit=20" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

Valida los números antes de las campañas, monitorea la conexión con alertas, registra el ID de cada envío, procesa el estado de entrega en el webhook (marcando las fallas en tu sistema) y crea una regla para sacar de la lista a quien acumule fallas. Para el cliente final, ofrece un canal alternativo cuando un mensaje sea crítico, como una cobranza o una confirmación.

Por último, desconfía de las métricas de "enviado" como prueba de entrega. Mide entregado, leído y respondido, y usa la respuesta como la señal más confiable de que la conversación existe.

A veces el mensaje sí llegó al cliente, pero tu sistema no registró el estado porque el webhook falló. En ese caso el panel interno muestra "no entregado" y el equipo reenvía, generando duplicados. Compara el historial de mensajes de la instancia con tu base antes de concluir que hubo una falla de entrega.

Usa el endpoint de prueba del webhook para validar la URL, mira las últimas entregas para ver el código HTTP que devolvió tu servidor y la lista de errores para encontrar timeouts. Si tu endpoint tarda, responde 2xx de inmediato y procesa después, en una cola.

En los grupos, el identificador termina en g.us y es distinto del número de una persona; usar el formato equivocado resulta en un mensaje que nunca llega. Para números de otros países, confirma el código de país y usa la verificación de números antes de enviar, porque cada país tiene reglas propias de formato.