Actualizado el 29/10/2026
Cuando la API de WhatsApp acepta el mensaje pero este no llega, la respuesta está en el webhook de estado: o el mensaje se quedó en sent (salió de los servidores de Meta, pero no llegó al dispositivo) o terminó en failed con un código de error. En el primer caso, las causas más comunes son un cliente desconectado, un cliente que bloqueó tu número o un país con restricciones; en el segundo, el código indica qué pasó y si conviene reenviar. Meta solo cobra los mensajes entregados, así que un mensaje que no llegó no aparece en la factura.
Este checklist parte del síntoma que ves en tu sistema y llega a la acción. Para la referencia completa de códigos, consulta la guía de errores de la API de WhatsApp.
Paso 1: confirma que la API aceptó el mensaje
Antes de hablar de entrega, revisa la respuesta síncrona del envío. Si la llamada devolvió un objeto error, el mensaje ni siquiera salió: el problema es de token, parámetro, plantilla o límite de llamadas, no de entrega. Si devolvió 200 con un wamid, el mensaje fue aceptado:
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "5215512345678", "wa_id": "5215512345678" }],
"messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5..." }]
}Guarda ese wamid. Con él relacionas cada evento de estado con el mensaje original. Si no está en tu base de datos, el diagnóstico se vuelve adivinanza.
Paso 2: lee el estado en el webhook
A partir de aquí, todo llega por el webhook messages, en el arreglo statuses. La referencia de estados de Meta define cinco valores:
| Estado | Qué dice Meta | Qué significa para el diagnóstico |
|---|---|---|
sent | El mensaje salió de los servidores de Meta | Aceptado y despachado, pero aún no está en el dispositivo |
delivered | Entregado en el dispositivo del usuario | Llegó; desde aquí es cobrable |
read | Mostrado en un chat abierto en el dispositivo | Leído (solo cuenta como leído si fue entregado) |
played | Primera reproducción de un mensaje de voz | Solo para notas de voz |
failed | Falla al enviar o entregar | Revisa el arreglo errors |
Dos detalles evitan falsas alarmas. Primero, si el usuario lee el mensaje de inmediato, Meta puede no enviar el delivered, porque el read ya implica la entrega. Así que «no recibí delivered» no significa «no se entregó» cuando hay un read. Segundo, si no llega ningún webhook, el problema es otro: revisa la configuración en la guía de webhooks de la API de WhatsApp antes de culpar a la entrega.
El artículo sobre estado de mensajes por webhook muestra cómo guardar estos eventos. Aquí nos enfocamos en qué hacer cuando revelan un problema.
¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →
Paso 3: mensaje detenido en sent
Es el caso más confuso: no hay error, pero tampoco delivered. La página de soporte de la Cloud API enumera las causas más comunes:
- El cliente no se conectó. Meta retiene los mensajes para usuarios desconectados durante una ventana de 30 días. Si el dispositivo no se conecta en ese plazo, el mensaje no se entrega.
- El cliente bloqueó el número de la empresa, u otro número comercial de la misma empresa.
- El cliente está en un país restringido o sancionado.
Meta advierte que en muchos de estos casos no revela la causa exacta. Por eso la acción es la misma para los tres: confirmar por otro canal (correo, SMS, llamada) que la persona puede escribir a tu número, que no bloqueó a la empresa y que tiene la app actualizada.
Lo que no debes hacer: reenviar el mismo mensaje cada hora. Si hubo un bloqueo, reenviar no cambia el resultado.
Paso 4: failed con código de error
Cuando la entrega falla, el evento trae el arreglo errors, con code, title, message y error_data.details. La tabla cubre los códigos que más aparecen en casos de «lo envié y no llegó», según la tabla de códigos de error de Meta:
| Síntoma en el webhook | Causa | Acción |
|---|---|---|
failed 131026 | No se pudo entregar: número sin WhatsApp, usuario que no aceptó los términos actuales o versión antigua de la app | Confirmar el número por otro canal; no reenviar en bucle. Ver error 131026 |
failed 131047 | Pasaron más de 24 horas desde la última respuesta del cliente | Enviar una plantilla. Ver error 131047 |
failed 131049 | Marketing no entregado para mantener una interacción saludable (límite por usuario) | Esperar al menos 24 horas antes de reenviar |
failed 131050 | El usuario dejó de recibir marketing de tu empresa | No reenviar; tratarlo como baja |
failed 130472 | No enviado porque el usuario forma parte de un experimento de Meta | No reenviar; ver error 130472 |
failed 131042 | Problema con el método de pago | Revisar la facturación de la cuenta |
failed 131048 | Envío restringido: muchos mensajes anteriores bloqueados o marcados como spam | Revisar la calidad en el WhatsApp Manager |
failed 131056 | Demasiados mensajes al mismo destinatario en poco tiempo | Esperar y reintentar solo para ese contacto |
failed 131000 | Error desconocido | Reintentar; si persiste, abrir un ticket |
sent sin delivered durante días | Cliente desconectado, bloqueo o país restringido | Confirmar por otro canal |
delivered y failed para el mismo mensaje | Cliente con varios dispositivos: llegó a uno y falló en otro | Considerarlo entregado |
Códigos que dependen del destinatario
El 131026 es el «no entregado» genérico. Meta cita tres causas y no dice cuál ocurrió: el número no es de WhatsApp, la persona no aceptó los Términos del servicio y la Política de privacidad más recientes, o usa una versión antigua de la app. La recomendación oficial es pedir al usuario, por otro canal, que confirme que puede escribir a tu número, acepte los términos y actualice la aplicación.
El 131050 es decisión del usuario: dejó de recibir marketing de tu empresa. Meta indica no reenviar y sugiere suscribirse al webhook user_preferences para saber cuándo el usuario deja de aceptar o vuelve a aceptar marketing.
Códigos de marketing
El 131049 es el límite por usuario de plantillas de marketing. Meta dice que, si sospechas de este límite, esperes al menos 24 horas antes de reenviar, porque hacerlo antes devuelve el mismo error. Lo explicamos a fondo en el límite de marketing por usuario.
El 130472 viene de un experimento de Meta que retiene el marketing para un porcentaje muy pequeño de usuarios. No es un fallo de tu código y no hay forma de evitarlo.
Códigos de tu cuenta
El 131042 apunta al método de pago. Meta menciona como causas comunes una línea de crédito por encima del límite, una cuenta de pago no vinculada, una línea de crédito inactiva, zona horaria o moneda sin configurar y una solicitud «en nombre de» (On Behalf Of) pendiente o rechazada.
El 131048 es una señal de calidad: el número tiene restricciones porque muchos mensajes anteriores fueron bloqueados o denunciados como spam. Antes de reenviar, revisa el contenido y el origen de tu base. La guía de calidad del número explica cómo monitorearla.
Paso 5: descarta el límite de mensajes y el método de pago
Hay dos causas que están por encima del mensaje y afectan todo a la vez.
Límite de mensajes del portafolio. La documentación de límites lo define como el número máximo de destinatarios únicos que puedes alcanzar fuera de la ventana de atención en 24 horas móviles. Los portafolios nuevos empiezan en 250. El límite es de todo el portafolio, así que un número puede consumir la capacidad de todos. Si los problemas de entrega empezaron en medio de una campaña grande, compara el volumen del día con tu límite actual en el WhatsApp Manager.
Método de pago. Según la página de precios, desde el 1 de octubre de 2026 cada número tiene 1.000 mensajes de servicio gratuitos al mes. Sin método de pago, Meta deja de entregar mensajes de servicio una vez agotada esa franquicia. Si las respuestas de atención dejaron de llegar a fin de mes, empieza por aquí.
Un clasificador sencillo en el webhook
Este fragmento en Node.js separa los casos para que tu equipo no tenga que abrir JSON en cada reclamo. Guarda el último estado, maneja el conflicto delivered + failed y devuelve una acción:
// Acción por código de error (tabla de códigos de Meta)
const ACCION = {
131026: 'confirmar_por_otro_canal',
131047: 'enviar_plantilla',
131049: 'reenviar_tras_24h',
131050: 'baja_marketing',
130472: 'no_reenviar',
131042: 'revisar_pago',
131048: 'revisar_calidad',
131056: 'esperar_y_reenviar',
131000: 'reintentar'
};
async function onStatus(st, db) {
const msg = await db.findByWamid(st.id);
if (!msg) return;
if (st.status === 'failed') {
// Si ya hubo delivered, el mensaje llegó al menos a un dispositivo
if (msg.deliveredAt) return;
const err = (st.errors || [])[0] || {};
await db.update(st.id, {
status: 'failed',
errorCode: err.code,
errorDetails: err.error_data?.details,
action: ACCION[err.code] || 'revision_manual'
});
return;
}
const patch = { status: st.status };
if (st.status === 'delivered' || st.status === 'read') patch.deliveredAt = st.timestamp;
await db.update(st.id, patch);
}Agrega una tarea diaria que liste los mensajes en sent por más de 48 horas. Son los candidatos a «cliente desconectado o bloqueo», y la acción para ellos es el contacto por otro canal, no el reenvío.
¿Se cobra un mensaje no entregado?
No. La página de precios de Meta dice que la empresa solo paga cuando el mensaje se entrega. Los mensajes en failed, o detenidos en sent, no se cobran. La página del experimento del 130472 también lo dice: Meta no envía el mensaje y no lo cobra.
Aun así, las fallas tienen un costo indirecto: mucho 131026 indica una base desactualizada, y muchas denuncias llevan al 131048.
Cómo diagnosticar con Vectalk
Vectalk es un proxy de la Cloud API oficial, así que los eventos de estado llegan a tu webhook en el mismo formato de Meta, con los mismos códigos de esta tabla. Además del webhook, puedes consultar el historial por la API:
curl --request GET \
--url 'https://apis.vectalk.com.br/api/messages?status=failed&direction=outbound&from=2026-10-01&to=2026-10-29' \
--header 'Authorization: Bearer TU_TOKEN'El endpoint Listar Mensajes acepta los filtros status (sent, delivered, read, failed, pending), direction, un rango de fechas y messageId (el wamid), útil para investigar un reclamo puntual. En Vectalk, solo los mensajes entregados se descuentan del saldo prepago, y los cargos de Meta pasan por la línea de crédito de Vectalk, sin que registres una tarjeta en Meta. Para empezar, crea tu cuenta en apps.vectalk.com.br/register. El panorama completo está en la guía de la API oficial de WhatsApp.
Preguntas frecuentes
¿Por qué mi mensaje se queda en «sent»?
Porque salió de los servidores de Meta pero no llegó al dispositivo. Según Meta, las causas más comunes son un cliente que no se conectó durante los 30 días en que se retiene el mensaje, un bloqueo del número de la empresa y un país restringido o sancionado.
Recibí «delivered» y «failed» para el mismo mensaje. ¿Cuál vale?
El delivered. Meta explica que ocurre cuando el cliente usa WhatsApp en varios dispositivos y el mensaje llega a uno y falla en otro. Delivered significa que llegó al menos a un dispositivo.
¿La API avisa cuando un cliente me bloquea?
La página de soporte menciona el bloqueo como causa de mensaje enviado y no entregado, y dice que Meta muchas veces no revela la causa. No cuentes con un código específico: trata un sent prolongado como señal y confirma por otro canal.
¿Pago por mensajes que no se entregaron?
No. Meta solo cobra los mensajes entregados. Un mensaje en failed o detenido en sent no se cobra.
¿Debo reenviar automáticamente cuando hay error?
Solo en errores temporales, como 131000 y 131056, y con espera entre intentos. Para 131026, 131050 y 130472, reenviar no sirve. Para 131049, espera al menos 24 horas.
Fuentes oficiales consultadas el 29/10/2026: Códigos de error de la WhatsApp Cloud API, Soporte de la WhatsApp Cloud API, Referencia del webhook de estado, Experimentos, Límites de mensajes, Precios, Listar Mensajes en la documentación de Vectalk.
Pon a funcionar el WhatsApp oficial de tu empresa
Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.