Este artículo cubre los errores que puedes encontrar al usar la API pública de WhatsApp, cómo las calificaciones de calidad y los niveles de mensajería afectan tu capacidad de envío, y qué puedes resolver tú frente a lo que requiere acción de Meta o del soporte de Aircall.
Referencia de errores
| Error | Qué significa | Qué hacer |
|---|---|---|
| 403 | La cuenta está en Essentials, no tiene un complemento activo de WhatsApp o la función no está habilitada | Confirma el estado del plan y del complemento en el Panel de control de Aircall. Contacta con el soporte de Aircall para comprobar que la función está disponible en tu plan. |
| 400 — line not configured | La línea no se ha registrado para el uso de la API pública | Llama primero a POST /v1/numbers/{id}/messages/configuration. |
| 400 — template not approved | La plantilla que se está enviando no está en estado APPROVED en Meta | Comprueba el estado de la plantilla en Meta Business Manager. Aircall no puede resolver esto. |
| 63016 — 24-hour window expired | El envío devuelve una respuesta 200, pero tu webhook recibe una devolución de llamada con un error cuando se envía texto de formato libre fuera de la ventana de conversación | Usa una plantilla aprobada para volver a iniciar una conversación con tu cliente. Consulta la sección de la ventana de 24 horas en el artículo Primeros pasos con la API pública de WhatsApp . |
| 400 — WABA not configured | La línea de WhatsApp no tiene configurada una WABA (WhatsApp Business Account) | Contacta con el soporte de Aircall. Este es un problema de configuración de la línea. |
| 400 — line OFFLINE or BLOCKED | La línea no está en un estado de envío activo | Comprueba el endpoint de estado de la línea. Si está BLOCKED, contacta con el soporte de Aircall. |
| 429 | Se superó el límite del nivel de mensajería: se alcanzó el límite diario de conversaciones | Límite impuesto por Meta. Se restablece cada 24 horas. Aircall no puede anularlo. |
| 131048 | Límite de tasa de spam de Meta: los envíos desde este número están restringidos por Meta | Revisa la calidad de tu mensajería y ponte en contacto con Meta Business Support. Aircall no puede anular esto. |
| 131045 | Error de registro del número de teléfono con un proveedor externo | Contacta con el soporte de Aircall |
| 131000 | Error desconocido de Meta | Si el error persiste, contacta con el soporte de Aircall con tu ID de empresa, ID de línea, la carga útil completa del error y una marca de tiempo. |
La ventana de conversación de 24 horas
La ventana de conversación de WhatsApp es una regla de Meta, no una configuración de Aircall. Controla cuándo se pueden enviar mensajes de texto de formato libre.
- Se abre una ventana de 24 horas cuando un cliente envía un mensaje a tu número o cuando responde a uno de tus mensajes.
- Dentro de esa ventana, puedes enviar texto de formato libre.
- Una vez que la ventana se cierra, solo puedes enviar una plantilla aprobada para reiniciar la conversación.
Importante: Intentar enviar texto de formato libre fuera de una ventana abierta devolverá un error a tu webhook. La solución es siempre enviar primero una plantilla aprobada. Aircall no puede anular ni ampliar la ventana.
Calificación de calidad
Meta asigna a cada línea de WhatsApp una calificación de calidad en función de cómo responden los destinatarios a los mensajes de ese número. Si los destinatarios bloquean o reportan tu número con frecuencia, la calificación empeora.
- GREEN: línea en buen estado, sin restricciones de envío.
- YELLOW: la calidad está empeorando, a menudo porque los clientes están reportando tus mensajes como spam o bloqueando tu número. Revisa la calidad de la plantilla y considera reducir el volumen de envío.
- RED: Meta ha restringido esta línea. Es posible que los envíos fallen. Ponte en contacto con Meta Business Support.
Importante: Meta establece y controla las calificaciones de calidad. Aircall no puede cambiarlas. Mejorar tu calificación requiere mejores plantillas, listas de contactos más limpias y confirmación de consentimiento por parte de los destinatarios.
Niveles de mensajería
Meta limita el número de conversaciones iniciadas por la empresa que una línea puede comenzar por período de 24 horas. Este es el nivel de mensajería. Los niveles aumentan automáticamente a medida que Meta gana confianza en la calidad y los patrones de envío de un número. No existe un proceso manual para solicitar un aumento de nivel.
| Nivel | Conversaciones por 24 horas | Tipo de cuenta habitual |
|---|---|---|
| TIER_250 | 250 | Líneas nuevas o no verificadas |
| TIER_1K | 1,000 | Empresas verificadas estándar |
| TIER_10K | 10,000 | Remitentes establecidos y de alta calidad |
| TIER_100K | 100,000 | Empresas verificadas de alto volumen |
Nota: Si tu integración devuelve un error 429, se ha alcanzado el límite diario del nivel. El límite se restablece cada 24 horas. Incorpora lógica de reintento en tu integración para este caso.
Lo que puedes y no puedes controlar
Algunas limitaciones las establece Meta y no pueden ser cambiadas por Aircall ni por ti.
Aircall no puede anular lo siguiente:
- Calificaciones de calidad
- Límites del nivel de mensajería
- Desbloquear un número que Meta ha restringido
- Aprobar o rechazar plantillas de mensajes de WhatsApp
- La ventana de conversación de 24 horas
Contacta con el soporte de Aircall para:
- Comprobación o activación del estado de la función
- Errores de WABA no configurada (400)
- Líneas que están OFFLINE o BLOCKED
- Errores de registro de números de teléfono (131045)
- Errores desconocidos persistentes (131000): proporciona tu ID de empresa, ID de línea, la carga útil completa del error y la marca de tiempo
Ponte en contacto directamente con Meta Business Support para:
- Restricciones por tasa de spam (131048)
- Deterioro de la calificación de calidad
- Líneas bloqueadas por completo por Meta
Preguntas frecuentes
Mis llamadas a la API devuelven un 403 aunque tenemos un complemento de WhatsApp. ¿Qué ocurre?
Un 403 también puede significar que la función todavía no está habilitada para tu cuenta, o que tu plan es Essentials. Contacta con el soporte de Aircall para confirmar que se cumplen todas las condiciones de elegibilidad: plan Pro o superior, complemento activo de WhatsApp y que la línea esté registrada.
¿Puedo enviar un mensaje a un cliente que nunca nos ha enviado un mensaje primero?
Sí, usa una plantilla aprobada. Las plantillas aprobadas se pueden enviar fuera de la ventana de 24 horas para iniciar el contacto. Los mensajes de texto de formato libre requieren una ventana de conversación abierta, lo que significa que el cliente debe haberte enviado un mensaje o haber respondido en las últimas 24 horas.
¿Por qué mi línea muestra una calificación de calidad YELLOW o RED?
Meta reduce las calificaciones de calidad cuando los destinatarios bloquean o reportan mensajes de tu número. Esto suele deberse al envío de mensajes no solicitados, al uso de plantillas de baja calidad o al envío de mensajes a contactos que no han dado su consentimiento. Aircall no puede cambiar esta calificación. Mejora tus prácticas de mensajería y deja pasar tiempo para que la calificación se recupere de forma natural.
¿Con qué rapidez se restablecen los límites del nivel de mensajería?
Cada 24 horas desde el momento en que se alcanzó el límite. Si recibes un error 429, espera 24 horas antes de volver a intentarlo. Los niveles aumentan automáticamente con el tiempo a medida que Meta gana confianza en la calidad de tus envíos.
Queremos que HubSpot o Salesforce envíen mensajes de WhatsApp automáticamente. ¿Por dónde empezamos?
Empieza con el artículo de primeros pasos enlazado a continuación. Una vez que tu línea esté registrada, tu equipo de CRM o RevOps puede crear flujos de trabajo que llamen a POST /v1/messages/whatsapp/send cuando cambien las etapas de los acuerdos, los contratos estén listos u otros eventos desencadenantes se activen.
Estado de Aircall
Ayuda para iniciar sesión