:::note Estado de versión El SDK npm publicado 0.1.4 con widget.js v15 admite teardown mediante remove() o window.ChattyBox.destroy(): elimina UI/estilos y cancela inicialización, reintentos y chats pendientes. El chat v15 hace como máximo 10 intentos dentro de un presupuesto de programación de 30 s, no un timeout estricto por solicitud. sendMessage() headless no reintenta automáticamente. :::

Personalización del widget alojado

Personaliza la interfaz lista para usar que carga https://chattybox.ai/widget.js. Consulta las Guías de instalación para ver ejemplos canónicos de instalación en frameworks y plataformas.

Antes de personalizar

Crea el proyecto, indexa su contenido y verifica respuestas representativas en Test Chat antes de dedicar tiempo a la presentación. Consulta Primeros pasos para ver la secuencia completa.

Configurar el widget alojado

1. Ve a tu panel y selecciona tu proyecto.
2. Abre la pestaña Embed.
3. Previsualiza y guarda el aspecto y el comportamiento lingüístico del widget.

La pestaña Embed controla la presentación y genera el código de instalación, pero las claves públicas se gestionan por separado. Cuando estés listo para instalarlo:

1. Abre Public Keys y crea una clave para el navegador.
2. Si lo desea, active la restricción opcional y añada los orígenes exactos previstos.
3. Vuelve a Embed, selecciona la clave y copia el snippet generado.
4. Sigue las Guías de instalación correspondientes a tu plataforma.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

consejo

Los cambios guardados se aplican en la próxima inicialización; recargue la página. Las páginas ya abiertas no se actualizan en vivo.

---

Personalización visual

ChattyBox incluye un editor visual totalmente integrado. Puedes ajustar el aspecto y la sensación del widget para que encaje perfectamente con tu marca sin tocar código.

Controles del panel

1. Accent Color – Elige el color principal de tu marca. Afecta al launcher, los resaltados principales y los mensajes del usuario.

2. Position – Elige dónde aparece el widget en la pantalla.

3. Header Title – Define el título que aparece en la parte superior de la ventana de chat.

4. Welcome Message – Personaliza el primer mensaje que ven los visitantes al abrir el chat.

nota

Guarde los cambios y recargue para verificarlos. La vista previa es una maqueta; en proyectos bloqueados, apariencia e idioma se gestionan como código, salvo la preferencia de branding permitida por el plan.

Opciones avanzadas

Ajustes del panel frente a atributos del script

La mayor parte del comportamiento del widget debe gestionarse desde el panel para que no tengas que volver a desplegar el sitio por cambios sencillos.

Usa el panel para colores, posición, icono, título del encabezado, mensaje de bienvenida, idiomas predeterminados, gestión de claves públicas, scraping y Analytics.

Si tu proyecto utiliza restricciones de origen para las claves públicas, mantén esas restricciones sincronizadas con los dominios donde está instalado el widget.

Usa atributos del script solo para valores que el widget necesita al cargar la página:

• data-api-key identifica la clave pública del widget.
• data-api-url indica al widget dónde enviar las solicitudes. En producción es una URL estable https://...convex.site/chat de tu panel.
• data-locale solicita un idioma al iniciar solo si el proyecto permite overrides de script.
• data-color y data-position reemplazan color/posición guardados; data-debug="true" activa diagnósticos.

Si el widget no aparece después de instalarlo, consulta la solución de problemas.

Para ver ejemplos específicos de cada plataforma, empieza por Docusaurus, MkDocs, VitePress, WordPress o GitBook.

Ocultar el widget en páginas concretas

Para ocultarlo visualmente en páginas concretas, puedes usar CSS:

.chattybox-widget {
  display: none;
}

Ocultarlo con CSS no detiene inicialización, solicitudes ni informes de error. Excluya el script si no debe cargarse; para las transiciones de ruta o la retirada del consentimiento, el widget.js v15 alojado ofrece window.ChattyBox.destroy() y el SDK publicado 0.1.4 ofrece remove() para el mismo teardown.

Integraciones personalizadas

¿Necesitas una configuración más específica que la del widget alojado? Crea tu propia interfaz con el SDK de JavaScript o contacta con support@chattybox.ai para recibir ayuda de arquitectura.

Compatibilidad multilingüe

El widget resuelve su idioma de interfaz al iniciarse según el modo fixed o auto del proyecto; no observa cambios de ruta ni de idioma después.

Idiomas admitidos oficialmente

El widget tiene catálogos de traducción para 14 idiomas. La existencia de un catálogo no significa que todas las cadenas visibles o accesibles estén traducidas ni garantiza la calidad de las respuestas.

Idioma	Código
Inglés	en
Francés	fr
Alemán	de
Español	es
Italiano	it
Neerlandés	nl
Portugués	pt
Polaco	pl
Sueco	sv
Indonesio	id
Estonio	et
Finés	fi
Galés	cy
Checo	cs

:::note Idioma de interfaz y respuestas Los catálogos de interfaz no garantizan el idioma ni la calidad de la respuesta. El backend detecta la pregunta y depende del contenido indexado y del modelo. :::

Cómo funciona la detección de idioma

El widget utiliza un sistema de detección en cascada:

1. Override permitido – data-locale gana solo si allowLocaleOverride no es falso, incluso en modo fixed.
2. Fixed – sin override permitido, usa defaultLocale.
3. Auto – usa <html lang>, después idioma del navegador y después defaultLocale.
4. Los valores regionales admitidos se reducen a su código base; un valor no admitido se convierte directamente en inglés, sin probar el siguiente candidato.

Anulación manual del idioma

Para solicitar un idioma concreto, active Allow Script Override y añada data-locale antes de cargar el loader:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

:::tip Caso de uso Esto resulta especialmente útil si tienes un sitio web multilingüe en el que cada versión tiene su propia URL (por ejemplo, /de/, /fr/). Configura data-locale para que coincida con el idioma de cada página y comprueba la interfaz renderizada. :::

Ajustes de idioma del panel

El panel de la aplicación permite configurar las preferencias lingüísticas del widget por proyecto:

• Auto-detect – usa el idioma de la página antes que el del navegador.
• Fixed Language – usa el valor predeterminado salvo override permitido.
• Allow Script Override – Activa o desactiva la anulación mediante el atributo data-locale.

Accede a estos ajustes en tu panel → Proyecto → pestaña Embed → sección Widget Language.

Coincidencia del idioma del contenido

Para una buena experiencia multilingüe, indexe contenido útil en los idiomas de sus visitantes:

1. Extrae todas las versiones lingüísticas de tu documentación mediante el archivo sitemap.xml.
2. El scraper intenta detectar el idioma; revise contenido y citas.
3. La recuperación intenta preferir el idioma de la pregunta, pero puede usar otro contenido indexado.

Configuración en el panel de la aplicación: al configurar el scraping, utiliza la URL de tu sitemap.xml (por ejemplo, https://yourdocs.com/sitemap.xml) para descubrir versiones lingüísticas y luego verifica las páginas indexadas. Los sitemaps no omiten los límites de rastreo ni las exclusiones.

Solución de problemas

El widget sigue apareciendo en inglés

• Actualización completa como diagnóstico – Recarga con Ctrl+F5 o Cmd+Shift+R y comprueba después las solicitudes del widget y de traducción en el panel de red del navegador.
• Comprueba data-locale – Verifica que el atributo esté configurado correctamente con un código de idioma compatible.
• Verifica el idioma del navegador – Comprueba que el idioma preferido del navegador esté configurado correctamente.
• Comprueba el lang del HTML de la página – Asegúrate de que la página contiene <html lang="de"> (o el código correspondiente).

Las fuentes aparecen en el idioma equivocado

• Vuelve a extraer el contenido – Comprueba que las versiones lingüísticas deseadas estén indexadas.
• Usa sitemap.xml – Confirma que las URL deseadas se hayan indexado realmente; los límites de rastreo y las exclusiones pueden omitirlas.
• Comprueba el idioma de la consulta – La IA intenta adaptar el idioma de la respuesta al idioma de la consulta.

Faltan traducciones

• Comprueba los idiomas admitidos – Solo los 14 códigos enumerados arriba tienen catálogos; las etiquetas faltantes pueden usar el fallback en inglés.

Prácticas recomendadas

1. Configura <html lang> en tus páginas – Ayuda con la accesibilidad y la detección del widget.
2. Prueba con data-locale durante el desarrollo – Verifica que cada idioma se muestre correctamente.
3. Extrae todas las versiones lingüísticas – Usa sitemap.xml para descubrirlas y verifica las páginas indexadas.
4. Revise preguntas reales – el dashboard no ofrece actualmente una distribución de idiomas del widget.