Guías de instalación
La integración alojada widget.js es la opción sin compilación cuando quieres que ChattyBox mantenga la interfaz y el transporte. Si tu aplicación debe inicializar la misma interfaz desde código npm, usa mountWidget(). Si quieres controlar la interfaz, utiliza el SDK headless.
Antes de instalar
Completa primero el flujo de Primeros pasos: configura y extrae la fuente, revisa las páginas indexadas y verifica respuestas representativas en Test Chat.
Después, crea una clave segura para el navegador en Public Keys y restringe sus orígenes permitidos. Vuelve a Embed, selecciona esa clave, termina de personalizar el widget alojado y copia el snippet generado. Incluye la clave pública y la URL de la API de tu proyecto:
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
async
></script>
Para plataformas centradas en documentación, consulta las guías de chatbot de IA para MkDocs, chatbot de IA para VitePress y chatbot de IA para GitBook.
Sustituye YOUR_API_KEY por la clave pública del widget de tu panel. Mantén el valor de data-api-url exactamente como aparece en el panel. En producción, es una URL estable https://...convex.site/chat para la API pública del widget.
Qué debe contener el script
Usa atributos del script para los valores que deben estar disponibles antes de que el widget pueda iniciarse:
| Atributo | Obligatorio | Se utiliza para |
|---|---|---|
src | Sí | Cargar el JavaScript del widget de ChattyBox. |
data-api-key | Sí | Identificar la clave pública del widget de tu proyecto. |
data-api-url | Sí | Enviar las solicitudes del widget a la API de ChattyBox. |
data-locale | No | Forzar el idioma de la interfaz del widget en una página concreta. |
Usa los ajustes del panel para todo lo que deba gestionarse sin volver a desplegar el sitio:
- Colores, posición, icono, título y mensaje de bienvenida del widget.
- Modo de idioma predeterminado y si se permiten anulaciones mediante
data-locale. - Creación y eliminación de claves públicas, además de las restricciones de orígenes permitidos configuradas para el proyecto.
- Scraping, nuevo scraping, chat de prueba, Analytics y lagunas de contenido.
Si activas el bloqueo de configuración como código, el asistente, la fuente, el entorno de ejecución y los ajustes de widget compatibles provendrán de la configuración desplegada y no de los formularios del panel. Las claves públicas y los orígenes permitidos siguen siendo credenciales de configuración del proyecto, no valores del archivo de configuración.
HTML sencillo
Pega el snippet una vez cerca del final de body, justo antes de </body>. Funciona para HTML estático, sitios escritos a mano y plantillas que exponen un pie de página global.
<!doctype html>
<html lang="en">
<head>
<title>Example Site</title>
</head>
<body>
<main>
<!-- Page content -->
</main>
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
async
></script>
</body>
</html>
Next.js / Shell de aplicación React
En un sitio Next.js con App Router, añade el widget a app/layout.tsx con next/script para que se cargue una vez en toda la aplicación.
import Script from "next/script";
import type { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
strategy="afterInteractive"
/>
</body>
</html>
);
}
En una aplicación de una sola página de React, añade el script una sola vez en la shell de aplicación de nivel superior o en la plantilla HTML. No lo inyectes desde cada componente de ruta.
import { useEffect } from "react";
export function ChattyBoxWidget() {
useEffect(() => {
if (document.getElementById("chattybox-widget-script")) return;
const script = document.createElement("script");
script.id = "chattybox-widget-script";
script.src = "https://chattybox.ai/widget.js";
script.async = true;
script.setAttribute("data-api-key", "YOUR_API_KEY");
script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
script.setAttribute("data-chattybox-widget", "true");
document.body.appendChild(script);
}, []);
return null;
}
Docusaurus
En Docusaurus, crea o actualiza src/theme/Root.tsx para que el widget esté disponible en todas las páginas de documentación.
import React, { useEffect } from "react";
export default function Root({ children }: { children: React.ReactNode }) {
useEffect(() => {
if (document.getElementById("chattybox-widget-script")) return;
const script = document.createElement("script");
script.id = "chattybox-widget-script";
script.src = "https://chattybox.ai/widget.js";
script.async = true;
script.setAttribute("data-api-key", "YOUR_API_KEY");
script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
script.setAttribute("data-chattybox-widget", "true");
document.body.appendChild(script);
}, []);
return <>{children}</>;
}
Si tu sitio de Docusaurus tiene rutas traducidas, establece data-locale a partir del idioma de la página actual o usa el valor de <html lang> de la página.
Mantén el loader en la shell persistente de la aplicación. No lo vuelvas a crear ni lo elimines durante los cambios normales de ruta del cliente.
Interfaz personalizada
El widget alojado es opcional. Si quieres tener control total del renderizado, el estado de los mensajes y el diseño de interacción, utiliza el SDK de JavaScript con la misma clave pública de API del widget y la misma URL de API del widget.
CMS genérico/HTML personalizado
La mayoría de las plataformas CMS tienen un área de código personalizado global, un pie de página o una plantilla de tema. Añade allí el script para que todas las páginas públicas puedan cargar el widget.
Usa esta opción para Webflow, Framer, Squarespace, áreas de código personalizado de Wix, temas de Shopify, plantillas de HubSpot y plataformas CMS personalizadas que permitan editar HTML global.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
async
></script>
Antes de publicar, confirma que el CMS no elimine data-api-key, data-api-url ni async de los scripts personalizados.
Google Tag Manager
Usa Google Tag Manager cuando tu equipo ya gestione scripts de terceros mediante GTM.
- Abre tu contenedor de GTM.
- Crea una etiqueta nueva de tipo Custom HTML.
- Pega el snippet de ChattyBox.
- Usa un activador All Pages o uno más específico solo para las páginas donde deba mostrarse el widget.
- Previsualiza el contenedor, verifica que el widget se cargue y publícalo.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
async
></script>
Si tu sitio utiliza el modo de consentimiento o una política de consentimiento de etiquetas, asegúrate de que el widget pueda cargarse en las páginas donde los visitantes necesiten ayuda.
WordPress
ChattyBox no necesita un plugin de WordPress. Utiliza una de las ubicaciones de script que tu instalación de WordPress ya admita:
- Ajustes del tema que proporcionen scripts de encabezado o pie de página.
- Un tema hijo que controle la plantilla del pie de página.
- Un plugin de scripts de encabezado/pie de página.
- Google Tag Manager si tu sitio de WordPress ya lo utiliza.
Pega el snippet en una ubicación de pie de página global para que aparezca en las páginas, entradas, documentos y artículos de la base de conocimiento publicados donde deba estar disponible el chatbot.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="YOUR_WIDGET_API_URL"
async
></script>
Evita añadir el widget a páginas de wp-admin, checkout, cuenta o membresía privada, a menos que sean intencionadamente públicas y compatibles.
Verificación
Después de instalarlo, completa la lista de comprobación del lanzamiento antes de anunciar el chatbot:
- Abre una página pública en una ventana de incógnito.
- Confirma que aparece el launcher del widget.
- Abre el widget y haz una pregunta real de un cliente.
- Verifica que la respuesta incluya citas de fuentes.
- Comprueba en la consola del navegador si faltan
data-api-key,data-api-urlo si hay errores de clave/origen.