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. Restringe sus orígenes permitidos a los dominios previstos del sitio web.
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 de presentación del widget guardados en el panel se aplican sin tener que sustituir el snippet en tu sitio.

---

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

Los cambios realizados en el panel se aplican al instante. No necesitas actualizar el código de inserción en tu sitio.

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 fuerza opcionalmente un idioma concreto de la interfaz del widget para esa página.

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

Si necesitas ocultar el widget en determinadas páginas, puedes hacerlo con CSS:

.chattybox-widget {
  display: none;
}

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 de ChattyBox se adapta automáticamente a las preferencias lingüísticas de tus visitantes y ofrece una experiencia localizada a usuarios de todo el mundo.

Idiomas admitidos oficialmente

La interfaz del widget (botones, etiquetas y mensajes del sistema) es compatible oficialmente con 14 idiomas:

Idioma	Código	Interfaz del widget	Calidad de las respuestas de IA
Inglés	en	Compatibilidad completa	Excelente
Francés	fr	Compatibilidad completa	Alta
Alemán	de	Compatibilidad completa	Alta
Español	es	Compatibilidad completa	Alta
Italiano	it	Compatibilidad completa	Alta
Neerlandés	nl	Compatibilidad completa	Alta
Portugués	pt	Compatibilidad completa	Alta
Polaco	pl	Compatibilidad completa	Alta
Sueco	sv	Compatibilidad completa	Alta
Indonesio	id	Compatibilidad completa	Media
Estonio	et	Compatibilidad completa	Media
Finés	fi	Compatibilidad completa	Media
Galés	cy	Compatibilidad completa	Media
Checo	cs	Compatibilidad completa	Media

:::note Compatibilidad lingüística ampliada Aunque admitimos oficialmente 14 idiomas para la interfaz del widget, la IA subyacente puede entender y responder en más de 100 idiomas. Sin embargo, no podemos garantizar respuestas de alta calidad en idiomas que no estén en nuestra lista oficial. :::

Cómo funciona la detección de idioma

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

1. Atributo data-locale – Tiene la máxima prioridad. Configúralo en el código de inserción para forzar un idioma concreto.
2. Atributo <html lang> de la página – El widget comprueba el idioma declarado de tu página.
3. Idioma del navegador (navigator.language) – Utiliza las preferencias del navegador del visitante.
4. Fallback predeterminado – Inglés si no se detecta ningún idioma.

Anulación manual del idioma

Para forzar que el widget se muestre en un idioma concreto independientemente de los ajustes del navegador, añade el atributo data-locale:

<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 conseguir una experiencia coherente. :::

Ajustes de idioma del panel

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

• Auto-detect (recomendado) – Coincide automáticamente con el idioma del navegador del visitante.
• Fixed Language – Fuerza que el widget se muestre siempre en un idioma concreto.
• 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 ofrecer la mejor experiencia multilingüe, tu chatbot debe responder en el mismo idioma que la pregunta del usuario. Para conseguirlo:

1. Extrae todas las versiones lingüísticas de tu documentación mediante el archivo sitemap.xml.
2. El scraper etiquetará automáticamente el contenido con su idioma.
3. El sistema RAG recuperará la versión lingüística adecuada según la consulta.

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 e indexar automáticamente todas las versiones lingüísticas de tu contenido.

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 – Asegúrate de que todas las versiones lingüísticas estén indexadas.
• Usa sitemap.xml – Así el scraper encontrará todas las URL /de/, /fr/, etc.
• 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 idiomas enumerados arriba tienen traducciones de interfaz garantizadas.

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 una indexación multilingüe completa.
4. Supervisa la distribución de idiomas – Consulta Analytics para saber qué idiomas utilizan más tus visitantes.