Guías de instalación

:::note Estado de versión El SDK npm publicado 0.1.4 permite retirar sus montajes con remove(). Tras inicializar el widget alojado widget.js v15, también puede destruirse con window.ChattyBox.destroy(). :::

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 e importa la fuente, revisa las páginas indexadas y verifica respuestas representativas en Probar chatbot.

En Instalar, prepara una instalación para tu sitio web o gestiona una clave segura para el navegador en Claves y dominios. Revisa los orígenes de la clave: una clave preparada para el dominio de un sitio web puede estar ya restringida a ese origen, mientras que las claves creadas sin restricciones funcionan en varios orígenes. En Editar orígenes puedes activar restricciones opcionales y añadir los orígenes de producción, vista previa, staging y localhost que necesites. Cuando están activadas, la coincidencia es exacta por esquema, nombre de host y puerto: https://example.com, https://preview.example.com y http://localhost:3000 son entradas independientes. En Instalación en el sitio web, selecciona la clave y copia el fragmento generado, que incluye la clave pública y la URL de la API del proyecto:

Introduce primero una URL de sitio web HTTP(S). El selector solo muestra claves no caducadas que no tienen restricciones o están permitidas para el origen de esa URL. Para seleccionar una clave restringida, introduce un origen permitido; usa Gestionar claves y dominios permitidos para consultar sus restricciones. Si el formulario no está disponible, completa primero el paso de configuración indicado en el panel.

<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	Solicitar un idioma de interfaz al inicializar, solo si el proyecto permite anulaciones del script.
data-chattybox-widget="true"	No	Permite que loaders dinámicos y el SDK encuentren un script existente; se recomienda al insertarlo desde el código de la aplicación.
data-debug="true"	No	Activa los diagnósticos del navegador; está desactivado de forma predeterminada.
data-color	No	Anulación explícita del color de acento tras obtener la configuración correctamente; use un color hexadecimal de seis dígitos. Es preferible usar el dashboard.
data-position	No	Anulación explícita de la posición tras obtener la configuración correctamente: bottom-right, bottom-left, top-right o top-left. Es preferible usar el dashboard.

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 y restricciones de origen opcionales por clave. Abre Claves y dominios > Editar orígenes para activar una restricción y añadir o quitar orígenes de producción, staging, vista previa o localhost.
• Importación y actualización de contenido, pruebas del chatbot, analítica y preguntas sin responder.

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, no de los formularios del dashboard. El bloqueo es irreversible y también impide operaciones manuales de contenido. Las claves públicas y las restricciones de origen opcionales siguen siendo ajustes independientes del proyecto, no valores del archivo de configuración.

La URL de la API puede ser la raíz del despliegue HTTP o terminar en /chat; el loader elimina las barras finales y un /chat final para derivar sus endpoints. No convierte una URL Convex .cloud en .site. No incluya cadenas de consulta ni fragmentos. El SDK reconoce el atributo marcador anterior, pero no necesariamente cualquier script manual que tenga el mismo src. Instale un solo loader. El SDK npm publicado 0.1.4 comparte el script únicamente entre montajes con opciones idénticas y rechaza cambios en la clave, el endpoint, la URL del script, el locale o la depuración mientras queden handles activos. El widget alojado no sigue los cambios de configuración del dashboard: vuelva a inicializarlo para aplicar los ajustes guardados. En el código fuente actual del loader alojado widget.js v16, las etiquetas de la interfaz propias del producto pueden actualizarse cuando <html lang> o data-locale cambian el locale resuelto, según la política de idioma del proyecto. Compruebe la versión desplegada del loader antes de confiar en las actualizaciones en el cliente; este comportamiento corresponde al loader alojado, no al SDK npm 0.1.4. Si se activan, las restricciones de origen usan Origin o, como alternativa, el origen de Referer; si el origen falta o no está permitido, se devuelve 401 Invalid API key. No son autenticació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"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

En una SPA React, añada el script una vez en la shell superior o en la plantilla HTML. No lo inserte desde cada componente de ruta. En el SDK publicado 0.1.4, los montajes idénticos comparten el script; llame remove() en cada handle y solo el último ordena a widget.js v15 eliminar UI, estilos, enlaces de fuentes, trabajo pendiente, script y API global. Las opciones distintas se rechazan mientras existan handles.

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 Docusaurus tiene rutas traducidas, establece data-locale antes de cargar solo si se permiten overrides, o usa el modo automático con <html lang>. El modo fijo usa el locale predeterminado del proyecto, salvo que se permita una anulación. En el código fuente actual del widget alojado widget.js v16, las etiquetas de la interfaz propias del producto pueden actualizarse si <html lang> o data-locale cambian el locale resuelto, según la política de idioma del proyecto. Comprueba el comportamiento del loader desplegado antes de confiar en estas actualizaciones; no se trata del SDK npm publicado 0.1.4. El título y el mensaje de bienvenida escritos por el cliente, así como las respuestas generadas, no se traducen automáticamente.

Mantén el loader en la shell persistente de la aplicación durante la navegación normal. Si necesitas desmontarlo deliberadamente o revocar el consentimiento, elimina todos los handles del SDK 0.1.4: el último handle coincidente indica al widget alojado widget.js v15 que elimine su interfaz y estilos y cancele la inicialización, los reintentos (hasta 10 intentos en 30 segundos) y el chat en curso. window.ChattyBox.destroy() también está disponible tras inicializar v15. La limpieza no puede deshacer una solicitud ya procesada en el servidor. El widget alojado se añade a document.body; no se renderiza dentro del componente que carga el script.

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.

1. Abre tu contenedor de GTM.
2. Crea una etiqueta nueva de tipo Custom HTML.
3. Pega el snippet de ChattyBox.
4. Usa un activador All Pages o uno más específico solo para las páginas donde deba mostrarse el widget.
5. 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.

En una SPA, un activador GTM más específico evita la carga inicial en las rutas excluidas, pero no elimina un widget ya cargado en otra ruta. No vuelvas a activar el loader cada vez que cambie el historial de navegación.

Política de seguridad de contenido (CSP)

Para el loader alojado predeterminado, permita https://chattybox.ai en script-src y el origen de la API del widget en connect-src. El widget inyecta una hoja de estilos y atributos de estilo en línea; actualmente no ofrece una opción de nonce. Una política que prohíba los estilos en línea bloqueará partes de la interfaz. Si la política lo permite, autorice 'unsafe-inline' para estos estilos o utilice una interfaz personalizada compatible con su CSP. Cargar Inter al abrir el launcher también requiere https://fonts.googleapis.com en style-src y https://fonts.gstatic.com en font-src. Permita en img-src el origen de cualquier imagen de icono configurada. Revise los requisitos de consentimiento y seguridad antes de relajar la CSP.

Guía del plugin de WordPress

Para una instalación de WordPress sin código, usa el plugin de WordPress de ChattyBox. Sigue la guía del plugin de WordPress para instalarlo, configurarlo, excluir rutas y verificarlo. El endpoint de producción se configura automáticamente.

El plugin carga el widget alojado en las solicitudes del frontend público sin editar el tema. Intencionadamente, no se carga en wp-admin, feeds, solicitudes REST ni solicitudes AJAX.

Esto no comprueba el acceso o la privacidad de cada página del frontend. Cuando sea necesario, configure y pruebe exclusiones para páginas de pago, cuenta, protegidas por contraseña o de membresía mediante el filtro del plugin, o use una instalación manual limitada a las páginas necesarias. La URL del loader no cambia el endpoint de producción integrado del plugin; use un fragmento manual para otra implementación de API.

Si prefieres instalar el script manualmente, usa una de las ubicaciones de scripts que tu configuració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 conocimientos 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.

Módulo de Drupal

Para Drupal 10 u 11, Composer es la ruta de instalación recomendada. Añade el repositorio VCS público de GitHub al composer.json raíz del proyecto Drupal que lo consuma:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Después, instala el módulo etiquetado y actívalo:

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Abre Configuration > Web services > ChattyBox, pega la clave API pública del widget preparada en Instalar → Instalación en el sitio web y activa el chatbot. La versión del módulo auditada localmente utiliza un endpoint de API definido en el código: compáralo con el del fragmento y usa la integración manual para otro despliegue de API. El módulo empieza desactivado. Omite las solicitudes administrativas y no HTML, pero no todo el contenido privado del frontend. Cambiar la URL del script no cambia el endpoint de producción integrado. Consulta la guía del módulo de Drupal para las exclusiones de rutas, la caché y el consentimiento.

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 una respuesta compatible incluya citas de fuentes y después haz una pregunta no compatible para comprobar el respaldo (que puede no tener fuentes).
• Comprueba en la consola del navegador si faltan data-api-key, si falta data-api-url o si hay errores de clave. Comprueba si la clave tiene restricciones de origen activadas y, de ser así, si el origen deseado está permitido.