Saltar al contenido principal

Solución de problemas

Utilice esta página cuando el widget esté instalado pero no se comporte como se esperaba.

El widget no aparece​

Primero verifique la consola del navegador. ChattyBox informa que faltan atributos requeridos allí.

Causas comunes:

  • El script no está presente ni en HTML desplegado ni en DOM vivo.
  • El script se agregó a la plantilla, diseño, contenedor del administrador de etiquetas o área de código CMS incorrectos.
  • El script está detrás de una regla de consentimiento o un activador del administrador de etiquetas que no se activó.
  • El componente que monta el loader nunca se ejecuta en esa ruta.
  • Una política de seguridad de contenido bloquea https://chattybox.ai/widget.js.
  • CSS u otro widget se superpone al iniciador.
  • La configuración implementada tiene widget.enabled: false.

Solución más pequeña:

  1. Abra la página pública implementada en una ventana de incógnito.
  2. Busque chattybox.ai/widget.js en el código fuente de la página y el panel Elements del navegador; un loader insertado por el SDK o por JavaScript puede aparecer solo en el DOM activo.
  3. Confirme que el script aparece una vez e incluye data-api-key y data-api-url.
  4. Mueva el script al pie de página global, al diseño de la aplicación, a la raíz Docusaurus o al activador GTM Todas las páginas si falta.

En proyectos gestionados mediante configuración, widget.enabled: false impide que se inicialice el widget alojado y hace que las solicitudes públicas POST /chat respondan con 403 Widget is disabled, incluidas las del SDK headless. Cambie ese ajuste mediante el flujo de implementación de configuración, no rotando la clave pública. Quitar el script después de la inicialización no elimina el widget ya renderizado.

Falta data-api-url​

El widget sale antes de tiempo cuando falta data-api-url.

Utilice el fragmento completo del panel o agregue el atributo requerido:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Use la URL de API que aparece en su panel en vez de adivinarla. En producción, se espera una URL estable con el formato https://...convex.site/chat.

Error genérico 401 Invalid API key​

Por seguridad, los endpoints de la API del widget devuelven la misma respuesta genérica 401 Invalid API key para una clave pública desconocida, caducada o rechazada por el origen. No se base en esa respuesta para identificar la causa.

Causas comunes:

  • La clave del widget público se copió incorrectamente.
  • La clave se eliminó, caducó o se copió desde una implementación de backend distinta de la URL de API.
  • El proyecto o el propietario de la clave está en proceso de eliminación.
  • La restricción opcional de origen está activada para la clave, pero no incluye el origen actual del sitio.

Correcciones:

  1. Abra el proyecto en el panel ChattyBox.
  2. Abra Instalar → Instalación en el sitio web, introduzca la URL del sitio y copie un fragmento apto si hay uno disponible.
  3. En Claves y dominios de la misma página, seleccione Editar orígenes para la clave del fragmento instalado. Si está activado Restringir esta clave a orígenes específicos, añada el origen exacto que sirve la página o desactive la restricción opcional. Deben coincidir el esquema, el nombre de host y el puerto: https://example.com, https://preview.example.com y http://localhost:3000 son orígenes distintos. No hace falta crear entradas separadas para las rutas.
  4. Vuelva a implementar o publicar el sitio y pruébelo nuevamente en una ventana de incógnito.

Una clave válida de otro chatbot en el mismo backend normalmente selecciona ese chatbot en lugar de producir un 401; revise el proyecto si las respuestas no guardan relación. Los nombres de claves como «production» y «staging» no imponen entornos. Si Origin está presente, la API HTTP usa ese encabezado; solo recurre al origen de Referer si falta Origin. Si Origin está presente pero no está permitido, un valor permitido de Referer no lo sustituye. Una clave restringida rechaza cualquier solicitud cuyo origen seleccionado esté ausente, sea inválido o no esté permitido. Las restricciones de origen no sustituyen la autenticación de visitantes.

Límites de mensajes o de solicitudes​

Consulte Cuenta y facturación en /settings/account para comprobar el uso de mensajes, el plan y los presupuestos PAYG opcionales de Pro/Business. Tanto el chat de prueba como el chat público consumen la asignación de mensajes compartida del propietario. Eliminar conversaciones o crear otra clave no restablece esa asignación.

Los errores de asignación mensual y los límites de solicitudes a corto plazo son distintos. Ante respuestas HTTP 429, respete Retry-After cuando se incluya, en vez de reintentar repetidamente. Si se alcanza el límite mensual de mensajes, espere a que se restablezca la asignación o ajuste el plan o el presupuesto PAYG que corresponda. Conversaciones → Historial contiene el historial de conversaciones, no una consola de errores por solicitud; revise los errores HTTP en el panel Network del navegador.

Idioma incorrecto​

Primero revise Personalizar → Apariencia, donde están los ajustes de idioma del widget. El widget alojado en el código fuente actual elige el idioma de la interfaz en este orden:

  1. data-locale, solo si está activado Permitir anulación por script.
  2. En modo Fijo, el idioma predeterminado.
  3. En modo Detección automática, <html lang>, los candidatos de idioma del navegador y, por último, el idioma predeterminado.

Se omiten los candidatos de locale no admitidos. Se usa inglés como último recurso si ningún candidato es compatible; el idioma predeterminado inicial es inglés.

Correcciones:

  • Para la detección automática, elija Detección automática y elimine un data-locale incorrecto o desactive los overrides de script.
  • Establezca <html lang="de">, <html lang="fr"> o el código de idioma correspondiente en páginas localizadas.
  • Para forzar el idioma configurado, elija Fijo y desactive Permitir anulación por script. Si los overrides están permitidos, data-locale sigue teniendo prioridad sobre el modo Fijo.
  • Compruebe que se hayan guardado los ajustes, vuelva a inicializar el widget instalado para aplicar los cambios de configuración del panel y pruebe otra vez. En el código fuente actual, el loader alojado widget.js v16 puede actualizar las etiquetas propias del producto cuando un cambio en <html lang> o en el data-locale del loader modifica el locale resuelto. Compruebe la versión del loader implementado antes de depender de las actualizaciones en vivo; este comportamiento del loader alojado es independiente del SDK npm publicado 0.1.4. Un locale proporcionado a mountWidget() se convierte en data-locale y sigue la misma política del proyecto.
  • Si el widget no está disponible, compruebe la solicitud /widget-config y la clave pública. En el código fuente actual, el widget alojado widget.js v16 permanece no disponible si falla la obtención de la configuración, en vez de iniciarse con los ajustes predeterminados. Compruebe la versión del loader implementado antes de confiar en este comportamiento.
  • Vuelva a indexar cada versión de idioma necesaria si las respuestas recuperan o citan contenido en el idioma equivocado. El generador detecta el idioma a partir de la pregunta, independientemente del idioma de la interfaz del widget; el idioma fijo del widget no impone el idioma de la respuesta ni traduce el contenido fuente. Si no se ha configurado un assistant.fallbackMessage personalizado, el mensaje integrado de respaldo cuando falta contenido usa el idioma detectado de la pregunta cuando puede determinarse; si la detección es incierta, usa el idioma de la interfaz del widget y recurre al inglés solo como último recurso.

Sin citas ni respuestas débiles​

ChattyBox usa el contenido fuente recuperado para generar respuestas. La falta de citas o las respuestas débiles pueden deberse a contenido fuente ausente o inadecuado, problemas de recuperación o fallos de generación; por sí solas no identifican la causa. Un chatbot RAG basado en fuentes se beneficia de contenido fuente recuperado y claro, pero una cita por sí sola no verifica una respuesta. Compare cada afirmación importante con la página citada.

Correcciones:

  • Haga la misma pregunta en el chat de prueba del panel y compare las páginas citadas.
  • Asegúrese de que la página de origen sea pública y esté incluida en el rastreo.
  • Agregue títulos claros, ejemplos, preguntas frecuentes y texto de respuesta directa a la página de origen.
  • Evite depender de capturas, vídeos, marcado oculto excluido, contenido disponible solo mediante JavaScript o iframes como única fuente.
  • Vuelva a rastrear la página actualizada cuando lo permita el cooldown, espere a que termine el trabajo de embeddings y vuelva a probar.
  • Revise los avisos Indexado parcialmente: no se conserva el texto que supera el límite de 512 KiB por página. Divida las páginas fuente largas en vez de reconstruir repetidamente el mismo texto truncado.
  • Procure que cada pregunta sea clara y autónoma. El generador puede recibir hasta 12 mensajes guardados recientes, con un máximo de 2.000 caracteres cada uno; no recibe la transcripción completa de la conversación.

Persona añade instrucciones específicas del sitio a las reglas de fundamentación integradas; no puede aportar contenido indexado que falte ni sustituir el mensaje de respaldo para contexto ausente o brechas de contenido cuando se activa. El detector de brechas de contenido es heurístico y puede no detectar todas las respuestas sin respaldo. Ese mensaje se configura por separado con assistant.fallbackMessage en la configuración como código.

Páginas no raspadas o con contenido obsoleto​

Causas comunes:

  • La página no aparece en el mapa del sitio enviado.
  • El modo URL manual no incluía la página.
  • La página bloquea las solicitudes HTTP habituales, requiere autenticación, devuelve una página CAPTCHA/error o redirige a un destino bloqueado.
  • El contenido de la página cambió después del último raspado.
  • El contenido solo se renderiza con JavaScript o está fuera de la raíz de contenido semántico seleccionada.
  • Las URL seleccionadas superan la asignación de páginas, se agotó el presupuesto mensual de actualizaciones o una regla de inclusión/exclusión las filtró.

Correcciones:

  1. Confirme que la página se abra públicamente en una ventana privada del navegador.
  2. Utilice el modo de mapa del sitio para una cobertura amplia o URL manuales para un conjunto seleccionado.
  3. Envíe la URL canónica en lugar de una URL de seguimiento, una URL de redireccionamiento o una URL de inicio de sesión.
  4. Vuelva a rastrear después de publicar cambios cuando haya pasado el cooldown: al menos siete días desde la creación del último trabajo en Free o 24 horas en planes de pago, incluso si ese trabajo falló.
  5. En Conocimiento → Páginas, despliegue Historial de importaciones cuando haya trabajos y seleccione uno en Trabajos de scraping. Compare sus cifras guardadas/seleccionadas y la lista Páginas con las URL esperadas. Completado puede incluir URL omitidas o fallidas; Completado con advertencias señala específicamente texto de página conservado de forma parcial, no todos los fallos de rastreo. La interfaz no ofrece una lista completa de fallos por URL.

ChattyBox puede leer robots.txt para descubrir declaraciones de sitemap del mismo origen, pero no aplica sus directivas de rastreo. No trate robots.txt como un control de acceso. ChattyBox sigue las redirecciones HTTP seguras, así que una redirección por sí sola no es un fallo. No elimine las protecciones de acceso ni publique contenido privado para que pueda rastrearse.

Si se quitó una URL del sitio o de la selección de fuentes, es posible que todavía se use la página almacenada. Elimínela también de Conocimiento → Páginas, además de excluirla de futuras búsquedas. Reconstruir índice usa el texto almacenado, no vuelve a obtener el contenido de la web; tiene su propio periodo de espera según el plan y consume parte del presupuesto mensual de actualizaciones.

Configuración no guarda​

Los cambios en los detalles del chatbot y en los ajustes de las fuentes se guardan automáticamente. Compruebe el estado del guardado y resuelva los errores de validación o vuelva a intentar los cambios que no se hayan guardado antes de continuar. El panel exige una URL del sitio guardada incluso si introduce URL manuales. El descubrimiento y el guardado automático no inician una importación: revise las páginas seleccionadas e inicie la importación explícitamente.

Si el proyecto tiene Config locked, la configuración debe implementarse mediante el flujo de CLI. El bloqueo es irreversible; se rechazan los cambios de Persona, los ajustes de rastreo, Scrape Now, la eliminación de contenido y la reconstrucción del índice, aunque los controles sigan visibles. Solo la preferencia de marca permanece editable desde el panel para la configuración del widget alojado, según el plan. Las claves públicas del widget y los tokens de implementación son credenciales distintas.

Si falta un proyecto o se deniega el acceso, confirme que inició sesión como su propietario. Una clave del widget, un token de implementación o pertenecer a una organización no concede permisos de propietario en el panel. En Conversaciones, Analítica y Preguntas sin responder están incluidas en Pro y Business; las vistas no disponibles muestran un aviso para mejorar el plan. Historial está disponible en todos los planes.

Todavía atascado​

Recopile estos detalles antes de contactar al soporte:

  • La URL de la página pública donde debería aparecer el widget.
  • Una captura de pantalla o copia de cualquier error de la consola del navegador.
  • Si la página usa HTML, Next.js, Docusaurus, WordPress, CMS o Google Tag Manager.
  • Si el fragmento incluye data-api-key y data-api-url.
  • Una pregunta de prueba que debería funcionar y la página fuente que la responde.