:::note Estado de versión
El loader alojado widget.js del código fuente actual de este repositorio es la v16. Esto no garantiza que la versión desplegada sea la v16: comprueba el loader que se sirve realmente antes de confiar en estos comportamientos. El SDK npm publicado 0.1.4 tiene una versión distinta de la del loader alojado.
:::
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 Probar chatbot antes de dedicar tiempo a la presentación. Consulta Primeros pasos para ver la secuencia completa.
Configurar el widget alojado
- Ve a tu panel y selecciona tu proyecto.
- Abre Personalizar → Apariencia para modificar el aspecto, la marca y los ajustes de Idioma del widget.
- Comprueba el estado del guardado automático. Corrige los errores de validación o vuelve a intentar guardar los cambios fallidos antes de probar el widget instalado.
El código de instalación y las claves públicas se gestionan en Instalar. Cuando tengas todo listo para instalarlo:
- Abre Instalar → Claves y dominios para revisar o crear una clave pública para el navegador y comprobar sus ajustes de origen.
- En Instalar → Instalación en el sitio web, selecciona una clave adecuada y copia el fragmento generado. Al preparar la instalación para un sitio web, la clave puede quedar ya restringida al origen exacto que hayas indicado. Las claves creadas sin restricciones funcionan desde cualquier origen: comprueba la clave seleccionada antes de usarla en staging o localhost.
- Si quieres, activa restricciones de origen exactas como protección adicional. Un origen incluye esquema, host y puerto; estas restricciones no autentican a los visitantes.
- 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>
Los cambios de presentación guardados en el panel se aplican en la próxima inicialización del widget; las páginas ya abiertas no se actualizan en tiempo real. Comprueba el estado del guardado automático antes de recargar. La vista previa del panel es una maqueta, no el widget alojado.
Personalización visual
El editor del panel permite ajustar los colores, la posición, el icono y el texto admitidos del widget sin modificar el código del sitio. Comprueba el resultado en el widget alojado, ya que la vista previa y el loader no son idénticos.
Controles del panel
-
Color de acento – Elige el color principal de tu marca. Se aplica al botón de apertura, los elementos destacados y los mensajes de los usuarios.
-
Posición del widget – Elige dónde aparece el widget en la pantalla.
-
Título del encabezado – Define el título que aparece en la parte superior de la ventana de chat.
-
Mensaje de bienvenida – Personaliza el primer mensaje que ven los visitantes al abrir el chat.
-
Marca de ChattyBox – Los planes Starter y superiores pueden ocultar el pie «Desarrollado por ChattyBox». La marca debe permanecer activada en el plan Free.
El editor también incluye los controles Fondo del widget y Color del texto, además de opciones para el icono del widget: robot predeterminado, emoji, URL de imagen o imagen subida. El control Tamaño del icono solo aparece al elegir una URL de imagen o subir una imagen. Las imágenes subidas deben ocupar como máximo 512 KiB y usar un tipo MIME admitido (PNG, JPEG, WebP, SVG, GIF o ICO). En el código fuente actual del loader alojado v16, iconSize ajusta el tamaño del botón de apertura y del icono. Comprueba la versión del loader que se sirve realmente antes de confiar en este comportamiento.
En los proyectos bloqueados por configuración, la apariencia y el idioma se gestionan mediante config-as-code. Los proyectos con los permisos necesarios pueden guardar por separado la preferencia de marca. Comprueba el estado del guardado automático y, después, recarga la página instalada para verificar los cambios.
Valores predeterminados de la configuración
La tabla muestra los valores que devuelve el código fuente actual cuando la solicitud pública de configuración del widget se completa correctamente y no hay ningún valor personalizado. No garantiza la versión desplegada; comprueba el loader que se sirve realmente antes de confiar en comportamientos específicos de su versión.
| Campo | Valor predeterminado |
|---|---|
enabled | true, salvo que el widget esté desactivado en el proyecto |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; se admiten las cuatro esquinas |
iconType, iconSize | default, medium; el loader alojado v16 del código fuente actual usa este tamaño para el botón de apertura y el icono |
iconEmoji, iconUrl | 💬, null |
headerTitle | Chat with us (valor predeterminado de la API) |
welcomeMessage | Hi! 👋 How can I help you today? (valor predeterminado de la API) |
showBranding | true; siempre activado en los proyectos Free |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (valores predeterminados) |
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 activas una restricción de origen para una clave pública, mantén sus orígenes exactos sincronizados con los sitios donde está instalado el widget. La coincidencia incluye el esquema, el host y el puerto. Las claves para el navegador son públicas; las restricciones de origen son una protección adicional opcional, no un método de autenticación de visitantes.
Usa los atributos del script para establecer los valores iniciales que el widget necesita al cargar la página:
data-api-keyidentifica la clave pública del widget.data-api-urlindica al widget dónde enviar las solicitudes. En producción es una URL establehttps://...convex.site/chatde tu panel.data-localeestablece el idioma inicial de la interfaz si el proyecto permite overrides de script. El loader del código fuente actual también observa cambios posteriores en este atributo.- En el código fuente actual del loader alojado v16,
data-colorydata-positionreemplazan el color de acento y la posición guardados tras una carga correcta de la configuración; estos atributos pueden ocultar cambios posteriores del panel. Es preferible usar los valores del panel y comprobar el loader que se sirve realmente antes de confiar en este comportamiento. data-debug="true"activa los diagnósticos de consola; está desactivado de forma predeterminada.
Errores de carga
En el código fuente actual del loader alojado v16, si falla la solicitud de configuración o la respuesta no es válida, el widget no está disponible y no se muestra ninguna interfaz alternativa. Una respuesta de configuración correcta con enabled: false también impide que se muestre. La API de chat rechaza con HTTP 403 las solicitudes a un widget desactivado, incluidas las del SDK. Comprueba la versión del loader que se sirve realmente antes de confiar en este comportamiento.
Un fallo al cargar las traducciones es distinto: solo ocurre después de que la configuración se haya cargado correctamente. En ese caso, el widget puede mostrarse con sus etiquetas integradas en inglés. Las claves que falten en un catálogo también usan los valores predeterminados en inglés.
Cuando funciona sin un SDK expuesto en la página, el loader alojado v16 del código fuente actual solicita la configuración con Authorization: Bearer y solo vuelve a intentarlo una vez con la clave en el parámetro de consulta apiKey después de HTTP 400. El SDK publicado 0.1.4 aplica ese mismo fallback limitado a la configuración únicamente si la página expone window.ChattyboxSDK. El loader v16 reintenta por separado las solicitudes GET de configuración y traducciones durante el inicio cuando el error permite reintentos. Los mensajes de chat usan el transporte propio del loader alojado. Al montar con el SDK, la versión publicada 0.1.4 solo comparte opciones idénticas y rechaza cambios en la clave, el endpoint, la URL del script, el locale o la opción de depuración hasta que se hayan eliminado todos los handles correspondientes. Comprueba la versión del loader que se sirve realmente antes de confiar en el comportamiento del código fuente actual.
Para los mensajes nuevos, el loader alojado del código fuente actual v16 intenta enviar el origen y la ruta de la página HTTP(S) actual para la analítica de Disparadores populares. No comprueba si la página es pública. Si el contexto no es válido o es demasiado largo, se omite; los reintentos conservan el contexto de la solicitud inicial. Se eliminan los parámetros de consulta, los fragmentos y las credenciales, pero las rutas pueden contener identificadores sensibles. No instales el widget en rutas sensibles solo porque se eliminan los parámetros de consulta.
El widget también respeta prefers-reduced-motion, incluye un campo de mensaje etiquetado y anuncios en vivo, y permite acceder a las citas desde Fuentes mediante el teclado.
El loader también puede enviar errores de inicialización, configuración, traducción o chat a /widget-error mediante beacon o fetch. Estos informes incluyen detalles de error limitados, el locale, la versión y el origen y la ruta de la página. No hace falta activar el modo de depuración para enviarlos. Comprueba la versión del loader que se sirve realmente antes de confiar en estos comportamientos.
El chat devuelve respuestas JSON completas, no transmite tokens. En el código fuente alojado v16, cada mensaje recibe una clave de idempotencia que se reutiliza en los reintentos de transporte, de modo que se puede repetir una respuesta ya procesada sin volver a procesar el mensaje. El loader realiza como máximo 10 intentos automáticos ante errores de red, interrupciones del cuerpo de la respuesta pese a una respuesta HTTP correcta, HTTP 429, HTTP 5xx y respuestas 409 con una cabecera Retry-After legible. No programa otro intento si el retraso excedería el presupuesto de 30 segundos; este presupuesto no es un timeout estricto para una solicitud que ya está en curso. CORS puede ocultar Retry-After. sendMessage() headless no reintenta automáticamente. Comprueba la versión desplegada del loader antes de confiar en estos reintentos.
El estado de la conversación permanece en la memoria de la instancia del widget y se pierde al recargar o reinicializar; los mensajes que ya se hayan guardado en el servidor pueden permanecer allí. Las fuentes se deduplican y se limitan a tres entradas visibles; las respuestas de respaldo pueden no incluir fuentes.
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 solo en páginas concretas, aplica este CSS únicamente en esas páginas; si lo aplicas globalmente, el widget se ocultará en todas partes:
.chattybox-widget {
display: none;
}
Ocultarlo con CSS no detiene la inicialización, las solicitudes a la API ni los informes de errores; tampoco es un mecanismo de consentimiento o privacidad. El loader no decide si hay consentimiento: inserta el script solo después de obtener el consentimiento necesario e impide volver a insertarlo tras retirar el consentimiento o en rutas excluidas.
Para los cambios de ruta del lado del cliente o la retirada del consentimiento, el código fuente actual del loader alojado v16 ofrece window.ChattyBox.destroy(). El SDK npm 0.1.4 cuenta los handles de montaje como referencias: llama a remove() en todos los handles correspondientes para indicar el desmontaje final. Comprueba que el loader desplegado admita el desmontaje; quitar únicamente la etiqueta <script> no basta. El desmontaje elimina la interfaz y los estilos que controla, y cancela el trabajo pendiente, pero no puede deshacer las solicitudes que el servidor ya haya procesado.
Controles del navegador
En el código fuente actual del loader alojado v16, window.ChattyBox está disponible durante el inicio con status: 'loading' y destroy(). Tras la inicialización, comprueba window.ChattyBox?.status === 'ready' antes de llamar a open(), close(), toggle() o sendMessage(text). destroy() elimina el widget y sus estilos, cancela el trabajo en curso y borra la variable global; no puede deshacer las solicitudes que el servidor ya haya procesado. close() solo cierra el panel de chat; el botón de apertura permanece visible. sendMessage(text) devuelve una promesa de operación de la interfaz, no una promesa con la respuesta; se ignoran los envíos mientras se procesa otro mensaje. Esta variable global es distinta de los constructores del SDK en window.ChattyboxSDK. Comprueba la versión desplegada del loader antes de confiar en este comportamiento.
Temas claro y oscuro controlados por el sitio (código fuente actual)
El flujo de config-as-code del código fuente actual admite paletas opcionales en widget.theme.light y widget.theme.dark. Cada una acepta primaryColor, backgroundColor y textColor como colores hexadecimales de seis dígitos; los colores omitidos heredan los valores de widget.theme. Las configuraciones existentes con un solo tema siguen funcionando sin cambios. Esta función requiere el CLI y el backend del código fuente actual, además del loader alojado v16; el CLI/la configuración publicados en 0.3.1 aún no aceptan estos campos. No des por hecho que el loader desplegado sea la v16.
Antes de ejecutar el script del loader, establece data-theme="light" o data-theme="dark" para seleccionar la paleta inicial. Después, conecta el selector de tu sitio a la API del navegador:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
El widget actualiza sus estilos sin restablecer los mensajes, las fuentes, el borrador ni una solicitud pendiente. El tema no puede activar ni desactivar el widget ni eliminar la atribución de marca. Tu sitio se encarga de guardar la preferencia y gestionar el tema del sistema operativo; el widget solo selecciona la paleta configurada.
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 del código fuente actual resuelve el locale de la interfaz según el modo fijo o automático del proyecto. El loader alojado v16 observa los cambios en <html lang> y en el atributo data-locale del script, y actualiza las etiquetas sin reiniciar la conversación, el borrador ni un reintento pendiente. La navegación por sí sola no cambia el idioma: actualiza uno de esos atributos cuando corresponda. Los cambios de configuración en el panel requieren volver a inicializar el widget. Comprueba la versión del loader que se sirve realmente antes de confiar en este comportamiento.
Idiomas admitidos oficialmente
El widget tiene catálogos de traducción para 14 idiomas, todos de izquierda a derecha. Los catálogos traducen las etiquetas de la interfaz propias del producto, no los textos redactados por el proyecto ni las respuestas generadas por IA. Si falla la carga de las traducciones después de cargar correctamente la configuración, se mantienen las etiquetas integradas en inglés.
| 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 El loader alojado del código fuente actual envía el locale de la interfaz resuelto junto con las solicitudes de chat. El backend detecta el idioma de la pregunta e intenta adaptar la recuperación y la generación. Una señal reconocida del idioma de la pregunta tiene prioridad sobre el locale de la interfaz para los mensajes fallback propios del producto; si la detección no es concluyente o se basa únicamente en la heurística de inglés basada en caracteres ASCII, el locale de la interfaz puede determinar su idioma. Un mensaje fallback configurado por el proyecto se muestra tal cual; el locale no traduce las respuestas generadas por IA. El idioma y la calidad de las respuestas dependen del contenido indexado y del modelo configurado. Comprueba la versión del loader publicada antes de confiar en el comportamiento de la v16. :::
Cómo funciona la detección de idioma
El widget utiliza un sistema de detección en cascada:
- Override de script permitido – Un
data-localecompatible tiene prioridad siallowLocaleOverrideno esfalse, incluso en modo fijo. - Modo fijo – Sin un override permitido y compatible, usa
defaultLocalee ignora el idioma de la página y del navegador. - Modo automático – Prueba
<html lang>,navigator.language, cada valor denavigator.languages, el valor heredadouserLanguagey, por último,defaultLocale; elige el primer idioma compatible. - Normalización – La comparación no distingue mayúsculas y minúsculas, y los locales regionales reconocidos (por ejemplo,
fr-CA) se reducen al idioma base compatible. Se omiten los candidatos no compatibles; si ninguno lo es, se usa inglés. Los valores predeterminados son el modo automático, inglés y overrides de script permitidos.
Los títulos personalizados y los mensajes de bienvenida redactados por el proyecto se muestran tal cual; no se traducen automáticamente. Los títulos y mensajes de bienvenida predeterminados previstos en el código fuente actual usan etiquetas localizadas. Si falla la carga de traducciones, se mantienen las etiquetas integradas en inglés.
Anulación manual del idioma
Para solicitar un idioma concreto, activa Permitir anulación por script y añade data-locale al script del 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:
- Detección automática – usa el idioma de la página antes que el del navegador.
- Fijo – usa el idioma predeterminado configurado, salvo que se permita un override del script.
- Permitir anulación por script – permite o no la anulación mediante el atributo
data-locale.
Accede a estos ajustes en tu panel → Proyecto → Personalizar → Apariencia → Idioma. Comprueba el estado del guardado automático y corrige los errores antes de probar el widget.
Coincidencia del idioma del contenido
Para ofrecer una buena experiencia multilingüe, indexa contenido útil en los idiomas de tus visitantes:
- Extrae todas las versiones lingüísticas de tu documentación mediante el archivo
sitemap.xml. - El scraper intenta detectar el idioma; revisa el contenido y las citas.
- 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. - Comprueba el modo del proyecto y el permiso de override – El modo fijo y los overrides desactivados pueden ignorar deliberadamente el idioma del navegador o
data-locale. - Verifica el idioma del navegador – Comprueba que el idioma preferido del navegador esté configurado correctamente.
- Comprueba el
langdel 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 y las solicitudes – Solo los 14 códigos enumerados arriba tienen catálogos. Si falla la carga del catálogo después de cargar correctamente la configuración, se usan las etiquetas integradas en inglés; si falla la carga de la configuración, el widget no está disponible.
Prácticas recomendadas
- Configura
<html lang>en tus páginas – Ayuda con la accesibilidad y la detección del widget. - Prueba con
data-localedurante el desarrollo – Verifica que cada idioma se muestre correctamente. - Extrae todas las versiones lingüísticas – Usa
sitemap.xmlpara descubrirlas y verifica las páginas indexadas. - Revisa preguntas reales – Examina las conversaciones para detectar lagunas de contenido específicas de cada idioma; el panel no ofrece actualmente un informe de distribución de idiomas del widget.