WhatsApp Business API: Errores Comunes y Solución de Problemas

Esta guía proporciona soluciones para los errores más frecuentes de integración, plantillas y mensajería que se encuentran al usar WhatsApp Business API con WhatsTeam.

Errores de Integración y Configuración

Este número está registrado en una cuenta de WhatsApp existente

Este error ocurre si tu número de teléfono ya está vinculado a otro proveedor de WhatsApp Business API o a la aplicación móvil estándar de WhatsApp/WhatsApp Business.

• Si usas otro proveedor de API: Sigue nuestra guía de migración para transferir tu número a WhatsTeam.
• Si usas la aplicación móvil: Debes desconectar formalmente el número de la aplicación antes de poder usarlo con Cloud API. Ten en cuenta que esto eliminará tu historial de chats local a menos que tengas una copia de seguridad.
• ¿Sigues atascado? Contacta a nuestro equipo de soporte en support@whats.team con tu ID de WhatsApp Business Account y número de teléfono para asistencia manual.

No se pudo enviar el código o error 500 en consola

Si no recibes un código de verificación o ves un "Error Interno del Servidor 500" durante el registro:

1. Revisa la consola: Revisa la consola de desarrollador de tu navegador. A menudo, estos son errores de validación de Meta respecto a la configuración de tu perfil de negocio (por ejemplo, descripción demasiado larga).
2. Prueba el flujo de primera vez: Si estabas intentando una migración, prueba la ruta de "Configuración por primera vez", ya que la cuenta puede haberse creado parcialmente.
3. Espera y reintenta: Los servidores de Meta a veces experimentan retrasos transitorios. Espera de 5 a 10 minutos antes de solicitar un nuevo código.

Acceso a WhatsApp Business Account no compartido

Esto ocurre cuando la conexión entre tu Meta Business Account y WhatsTeam no ha sido completamente autorizada o los permisos fueron revocados.

• Resolución: Vuelve a ejecutar el proceso de Embedded Signup y asegúrate de que todas las casillas de permisos estén seleccionadas.

Solicitud get no soportada o ID inválido

Error: "El objeto con ID XXX no existe..." Esto generalmente ocurre cuando se ingresa un ID de Business Manager en lugar de un ID de WhatsApp Business Account (WABA). Verifica que estés usando el ID de WABA que se encuentra en tu Configuración de Meta Business bajo 'Cuentas de WhatsApp'.

No se puede migrar el número de teléfono

Error: "No se puede migrar el número de teléfono. La cuenta de WhatsApp en la que este número está registrado no está configurada correctamente."

1. Verifica que el número esté completamente aprobado en tu Meta Business Suite.
2. Asegúrate de que el número ya no esté activo en ningún dispositivo móvil.
3. Toma una captura de pantalla del número verificado en tu panel de Meta y envíala a nuestro equipo de soporte si el problema persiste.

No se puede crear el certificado (Conflicto de 2FA)

WhatsApp no puede generar un certificado de seguridad si la Autenticación de Dos Factores (2FA) está habilitada en el número de teléfono dentro de la aplicación móvil. Desactiva 2FA en los ajustes de tu aplicación WhatsApp antes de intentar conectar a WhatsTeam.

Por favor asegúrate de autorizar completamente el acceso

Este mensaje normalmente aparece si hay un retraso de sincronización entre la aprobación de Meta y nuestra plataforma.

• Resolución: Actualiza tu navegador y espera de 2 a 5 minutos para que los permisos se propaguen entre sistemas.

WABA ya usa un método de pago

Esto sucede cuando un número fue previamente provisionado por un proveedor externo que adjuntó su propio método de pago. Debes completar el proceso de migración para mover el número bajo tu propia Meta Business Account y estructura de pago.

Problemas con Plantillas de Mensajes

Las plantillas no aparecen en el panel

Si tus plantillas aprobadas de Meta no aparecen en WhatsTeam:

• Solo Texto Plano: Asegúrate de que la plantilla no use tipos de medios no soportados o elementos interactivos complejos que aún no se soporten en la vista actual.
• Coincidencia de Idioma: Verifica que el idioma de la plantilla coincida con la configuración de idioma de tu cuenta.
• Estado de Sincronización: La aprobación de Meta puede tomar hasta 24 horas. Si ya está aprobada en Meta, intenta actualizar tu conexión en el panel.

Formato de variables (marcadores de posición numéricos)

WhatsApp Cloud API requiere marcadores de posición numéricos (por ejemplo, {{1}}, {{2}}) en el cuerpo de la plantilla.

• Incorrecto: Hola {{nombre}}, tu pedido {{id_pedido}} está listo.
• Correcto: Hola {{1}}, tu pedido {{2}} está listo. Luego puedes mapear estas variables numéricas a atributos de usuario dentro de WhatsTeam al enviar el mensaje.

Prevenir la reclasificación a "Marketing"

Meta puede reclasificar automáticamente las plantillas de "Utilidad" o "Servicio" como "Marketing" si contienen lenguaje promocional.

• Consejo: Mantén tu lenguaje neutral, evita emojis en actualizaciones transaccionales y sé muy específico sobre el propósito del servicio al enviar para aprobación.

Problemas de Entrega de Mensajes

Mensaje no entregable / Receptor no compatible

Esto generalmente significa que la cuenta de WhatsApp del destinatario no puede recibir el mensaje.

• Causas: El número no está en WhatsApp, el usuario no ha aceptado los últimos Términos de Servicio o está usando una versión extremadamente desactualizada de la aplicación.
• Solución: Pide al usuario (por SMS o correo electrónico) que te envíe un mensaje primero para "preparar" la conversación y asegurarse de que su aplicación esté actualizada.

Límites de frecuencia de mensajería

Si un mensaje falla debido a "límites de frecuencia", Meta ha limitado la cantidad de plantillas de marketing que este usuario específico puede recibir en un período corto para prevenir spam.

• Acción: Espera 24 horas antes de intentar reenviar. Consulta la documentación de Meta para más detalles.

La ventana de conversación de 24 horas

WhatsApp aplica una ventana de servicio de 24 horas. Solo puedes enviar mensajes de formato libre si el usuario ha respondido en las últimas 24 horas.

• Si la ventana está cerrada: Debes enviar un Mensaje de Plantilla pre-aprobado para recontactar al usuario. Una vez que responda, la ventana de 24 horas para chat de formato libre se reabre.

Tipo de medio no soportado

Si una imagen o documento no se envía:

• Verifica que el tamaño del archivo esté dentro de los límites de Meta.
• Asegúrate de que el formato del archivo (por ejemplo, .jpg, .pdf, .mp4) sea compatible con la plataforma de WhatsApp.

El destinatario es parte de un experimento de WhatsApp

Ocasionalmente, Meta realiza experimentos donde ciertos mensajes de marketing no pueden ser entregados a usuarios específicos. Si ves un error que menciona un "experimento", intenta enviar un tipo de mensaje diferente o reenvía más tarde.

Cuenta restringida o bloqueada

Si recibes un error indicando que la "Cuenta está bloqueada", tu WABA puede haber sido suspendida por violaciones de políticas.

• Resolución: Revisa la Bandeja de Soporte de Meta Business Suite para cualquier notificación sobre aplicación de políticas y sigue sus instrucciones para apelar o resolver la restricción.

¿Sigues Teniendo Problemas?

Si tu problema no está cubierto aquí, nuestro equipo de soporte está listo para ayudar. Contáctanos en support@whats.team.