Saltar al contenido principal
ChattyBox Logo

Guías de instalación

:::note Estado de versión El SDK npm publicado 0.1.4 con widget.js v15 admite teardown con remove() o window.ChattyBox.destroy() y cancela trabajo pendiente. :::

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. De forma predeterminada, funciona en los orígenes de producción, preview/staging y localhost. Para añadir un refuerzo opcional de seguridad en profundidad, selecciona Edit origins, activa Restrict this key to specific origins y añade los orígenes permitidos exactos. Cuando está activada, la coincidencia incluye el esquema, el nombre de host y el puerto: https://example.com, https://preview.example.com y http://localhost:3000 son entradas independientes. Vuelve a Embed, selecciona la clave 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:

AtributoObligatorioSe utiliza para
srcSíCargar el JavaScript del widget de ChattyBox.
data-api-keySíIdentificar la clave pública del widget de tu proyecto.
data-api-urlSíEnviar las solicitudes del widget a la API de ChattyBox.
data-localeNoSolicitar idioma al iniciar, solo con overrides permitidos.
data-chattybox-widget="true"NoPermite que loaders dinámicos/SDK encuentren el script.
data-debug="true"NoActiva diagnósticos.

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, eliminación y restricciones de origen opcionales por clave pública. Abre Public Keys > Edit origins para activar una restricción y añadir o quitar orígenes de producción, staging, preview o localhost.
  • 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.

Instale un solo loader. El widget carga configuración y traducciones una vez; recargue para aplicar cambios. Las restricciones de origen son opcionales, usan Origin o Referer y 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. 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, use data-locale antes de cargar solo si se permiten overrides, o auto con <html lang>. Fixed usa el idioma predeterminado; el locale no se recalcula en navegación de cliente.

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.

  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 SPA, un trigger GTM más estrecho evita la carga inicial, pero no elimina un widget cargado en otra ruta.

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 identifica toda página privada de frontend: excluya checkout, cuenta, contraseña o membresía cuando corresponda. La URL del loader no cambia el endpoint API integrado del plugin.

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. El módulo aún no aparece listado en Drupal.org ni Packagist, por lo que esta entrada VCS es necesaria antes de ejecutar composer require:

{
  "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 y activa el chatbot. El módulo empieza desactivado y su URL del loader no cambia el endpoint API integrado; use un snippet manual para otro despliegue.

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 una respuesta compatible con citas y una pregunta no compatible con fallback, 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 los orígenes solo si has activado explícitamente una restricción para la clave.

Preferencias de privacidad

Utilizamos herramientas opcionales de analítica y gestión de etiquetas para comprender el uso del sitio. Elige si quieres permitir Ahrefs Web Analytics, PostHog y Google Tag Manager. Al desactivar la analítica, esta página se recargará para que el cambio se aplique correctamente. Las funciones esenciales del sitio y la monitorización de errores no dependen de esta opción. Lee nuestra política de privacidad.