Errores frecuentes de la API de Meta
Lo que más tiempo hace perder, con el síntoma primero — que es como se llega al problema en la práctica.
«El webhook no se verifica»
| Causa | Cómo se distingue |
|---|---|
El token del panel no es el del .env | Comprueba los dos caracter a caracter |
La API no se reinició tras editar el .env | La configuración se lee al arrancar |
| El certificado no es válido desde fuera | curl desde otra red, no desde la misma PC |
| La URL tiene una errata | Meta no dice cuál falló, sólo que falló |
«Todo funcionó ayer y hoy no llega nada»
Casi siempre el token de acceso caducó. El token de prueba dura 24 horas y es el que se copia por defecto del panel. Hace falta un token permanente de usuario del sistema.
Segundo sospechoso: el número entró en calidad baja por reportes de spam. Se ve en el panel de WhatsApp, en la calidad del número.
«El mensaje sale pero no llega»
- El destinatario no tiene WhatsApp en ese número.
- El destinatario bloqueó el número de la empresa.
- Estás en modo de desarrollo y el número no está en la lista de destinatarios de prueba. Este es el más traicionero: la API responde con éxito y el mensaje no llega a ninguna parte.
«Error 131047 / Re-engagement message»
La ventana de 24 horas está cerrada y se intentó texto libre. Ver Ventana de 24 horas.
«Error 132000 / Number of parameters does not match»
La plantilla espera un número de variables distinto del que se envió. Pasa al editar la plantilla en Meta sin actualizar la del CRM. Ver CP-18 Número de variables incorrecto.
«Error 132001 / Template name does not exist»
El nombre de la plantilla en el CRM no coincide con el de Meta, o está en un
idioma distinto. El par (nombre, idioma) tiene que ser exacto.
«La imagen se veía y ahora está rota»
Las URL de medios de Meta caducan a los pocos minutos. Hay que descargar el archivo al recibir el webhook, no guardar el enlace. Ver CP-07 Imagen entrante como evidencia.
«Los mensajes llegan duplicados»
Meta reintenta si no recibe un 200 lo bastante rápido. Si el endpoint tarda o devuelve error, reintenta durante horas. Ver CP-03 Reintento de Meta no duplica.
«El cliente aparece como desconocido aunque está registrado»
Formato del teléfono. Meta manda 51999888777, la base puede tener
+51 999 888 777. Ver CP-08 Número en formato inesperado.
Dónde mirar cuando nada de lo anterior encaja
-- Últimos eventos recibidos, con su error si lo hubo
SELECT provider, event_type, signature_ok, processed_at, error, received_at
FROM webhook_events ORDER BY received_at DESC LIMIT 20;
-- Mensajes que fallaron, con el motivo de Meta
SELECT created_at, status, error_code, error_message, body
FROM messages WHERE status = 'fallido' ORDER BY created_at DESC LIMIT 20;Si webhook_events está vacío, el problema está antes del CRM: Meta no
está llegando. Si tiene filas pero processed_at es nulo, el problema está
dentro.