Cómo incrustar un chatbot en cualquier sitio web

Ya tienes un chatbot entrenado. Ahora necesitas ponerlo en tu sitio web. Agentkit admite cuatro métodos de incrustación, y el correcto depende de tu plataforma, tu configuración técnica y cuánto control necesitas. Esta guía cubre las cuatro opciones con ejemplos de código, detalles de configuración e instrucciones específicas por plataforma.

Métodos de incrustación de un vistazo

La mayoría de los usuarios debería empezar con el widget de JS. Funciona en cualquier plataforma, carga de forma asíncrona y toma menos de cinco minutos configurarlo.

Antes de empezar

Todos los métodos de incrustación requieren un chatbot entrenado. Si todavía no tienes uno:

1. Regístrate en Agentkit (gratis).
2. Crea un chatbot y entrénalo con tu contenido usando URL de sitios web, documentos, pares de preguntas y respuestas o texto.
3. Pruébalo en el Playground hasta que las respuestas sean precisas.
4. Obtén tu código de incrustación desde Configuración y luego Incrustar en el panel.

Para orientación sobre el entrenamiento, consulta Cómo entrenar un chatbot con el contenido de tu sitio web.

Método 1: widget de JavaScript

El widget de JS es el método de incrustación universal. Una etiqueta de script, colocada antes de la etiqueta de cierre </body>, carga una burbuja de chat en tu sitio. Funciona en cualquier plataforma que permita JavaScript personalizado: sitios HTML estáticos, plataformas CMS, constructores de landing pages y aplicaciones web.

Instalación básica

Copia esta etiqueta de script y colócala antes de la etiqueta de cierre </body> de tu página:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  async>
</script>

Reemplaza your-chatbot-id con el ID real de tu panel de Agentkit. El atributo async garantiza que el script cargue sin bloquear tu página.

Eso es todo lo que necesitas para tener un chatbot funcionando. El widget aparece como una burbuja de chat en la esquina inferior derecha. Los visitantes hacen clic en ella para abrir una conversación.

Configuración mediante atributos data

Puedes personalizar el comportamiento del widget agregando atributos data a la etiqueta de script:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  data-position="bottom-right"
  data-theme="light"
  async>
</script>

Atributos data disponibles

La mayor parte de la personalización visual (colores, mensaje de bienvenida, marca) se controla desde el panel de Agentkit en lugar de los atributos data. Esto mantiene tu código de incrustación simple y te permite actualizar la configuración sin cambiar código en tu sitio.

Cómo carga el widget

El script del widget es liviano y carga de forma asíncrona. Esto es lo que ocurre:

1. Tu página carga con normalidad. El atributo async significa que el script no bloquea el renderizado.
2. El script se descarga desde nuestra CDN y se inicializa.
3. Aparece una burbuja de chat en la página.
4. Cuando un visitante hace clic en la burbuja, se carga la interfaz de chat completa.
5. Los mensajes se envían a la API de Agentkit y se transmiten de vuelta en tiempo real.

El script inicial es pequeño. La interfaz de chat completa solo se carga cuando el visitante interactúa con la burbuja, así que el impacto en la velocidad de tu página es mínimo.

Instalación del widget específica por plataforma

El widget de JS funciona en todas las plataformas, pero los pasos para agregar el script varían según la plataforma. Aquí tienes enlaces rápidos a guías específicas por plataforma:

Método 2: componente de React

Si estás construyendo con React, Next.js, Remix o Gatsby, el componente de React te da una integración más estrecha que la etiqueta de script directa. Obtienes configuración basada en props, tipos de TypeScript y la posibilidad de conectarte a los eventos del chatbot.

Instalación

Instala el paquete de React de Agentkit:

npm install @agentkit/react

Uso básico

import { AgentitkChat } from '@agentkit/react';

function App() {
  return (
    <AgentitkChat chatbotId="your-chatbot-id" />
  );
}

Esto renderiza la misma burbuja de chat que el widget de JS, pero como un componente de React dentro del árbol de componentes de tu app.

Props

Integración con Next.js

En un proyecto de Next.js con App Router, agrega el chatbot a tu layout raíz para que aparezca en todas las páginas:

// app/layout.tsx
import { AgentitkChat } from '@agentkit/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <AgentitkChat chatbotId="your-chatbot-id" />
      </body>
    </html>
  );
}

Para el Pages Router, agrega el componente a _app.tsx en su lugar.

Cuándo usar el componente de React vs. el widget de JS

Si usas React, usa el componente de React. Para todo lo demás, usa el widget de JS.

Método 3: iframe

El método de iframe incrusta el chatbot como una página independiente dentro de un marco en tu sitio. Es útil en entornos donde la inyección de JavaScript está restringida o donde quieres mostrar el chatbot como un elemento en línea en lugar de una burbuja flotante.

Incrustación básica de iframe

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write">
</iframe>

Esto muestra la interfaz de chat completa en línea en tu página, no como una burbuja flotante.

Cuándo usar iframe

Configuración del iframe

Personaliza el iframe mediante parámetros de URL:

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id?theme=dark"
  style="width: 400px; height: 600px; border: none; border-radius: 12px;"
  allow="clipboard-write">
</iframe>

Ajustar el tamaño del iframe

El iframe no se redimensiona automáticamente. Controlas sus dimensiones mediante CSS:

• Chat incrustado a ancho completo: width: 100%; height: 600px;
• Chat en barra lateral: width: 400px; height: 100vh; posicionado en un diseño de barra lateral.
• Widget compacto: width: 350px; height: 500px; para un área en línea más pequeña.

Limitaciones de la incrustación con iframe

Para la mayoría de los sitios web, el widget de JS es la mejor opción. Usa el iframe solo cuando el widget de JS no sea una opción o cuando específicamente quieras una experiencia de chat en línea.

Método 4: plugin de WordPress

Los sitios de WordPress pueden usar el widget de JS mediante cualquiera de los métodos descritos arriba, pero también existe un enfoque dedicado que usa plugins de fragmentos de código y simplifica el proceso para usuarios sin conocimientos técnicos.

Configuración rápida con WPCode

1. Instala el plugin WPCode (gratis, más de 2 millones de instalaciones) desde Plugins y luego Add New.
2. Ve a Code Snippets y luego a Header & Footer.
3. Pega la etiqueta de script de Agentkit en la sección Footer.
4. Guarda.

El chatbot ahora aparece en todas las páginas. WPCode también admite lógica condicional para que puedas mostrar el chatbot solo en páginas específicas.

Otros métodos de WordPress

Para el recorrido completo de WordPress con solución de problemas, consulta Cómo agregar un chatbot a WordPress.

Opciones de personalización

Sin importar qué método de incrustación uses, la mayor parte de la personalización se hace desde el panel de Agentkit. Esto significa que puedes cambiar la configuración sin tocar tu código de incrustación.

Personalización visual

Personalización de comportamiento

Consideraciones de seguridad

Al incrustar un chatbot en tu sitio, ten en cuenta estos ajustes de seguridad.

Restricción de dominio

Configura siempre la restricción de dominio en los ajustes de tu chatbot. Esto garantiza que tu chatbot solo cargue en tus dominios autorizados. Sin ella, cualquiera que encuentre el ID de tu chatbot podría incrustarlo en su propio sitio y usar tu cuota de mensajes.

Ve a Configuración en el panel de Agentkit y agrega cada dominio donde el chatbot debería funcionar:

• Tu dominio principal (por ejemplo, yourbusiness.com)
• Cualquier subdominio (por ejemplo, support.yourbusiness.com)
• Dominios de desarrollo o staging si necesitas hacer pruebas

Límite de frecuencia

El límite de frecuencia restringe la cantidad de mensajes que un mismo visitante puede enviar por sesión. Esto previene abusos y ayuda a gestionar tu cuota de mensajes. Un límite de 15 a 25 mensajes por sesión es razonable para la mayoría de los sitios.

Política de seguridad de contenido

Si tu sitio usa encabezados de política de seguridad de contenido (CSP), necesitas incluir los dominios de Agentkit en la lista blanca. Agrega lo siguiente a tu CSP:

• script-src: cdn.agentkit.ai
• frame-src: cdn.agentkit.ai (si usas el método de iframe)
• connect-src: *.agentkit.com (para las llamadas a la API)

Solución de problemas comunes de incrustación

El chatbot no aparece

El chatbot aparece pero no responde

• Revisa los datos de entrenamiento. Un chatbot sin entrenar no tiene con qué trabajar.
• Verifica el ID del chatbot. Un ID incorrecto significa que el widget carga pero no puede encontrar el chatbot.
• Revisa la restricción de dominio. Si tu dominio no está en la lista de permitidos, el chatbot no responderá.
• Revisa la cuota de tu plan. Si ya usaste todos tus mensajes mensuales, el chatbot dejará de responder hasta el próximo ciclo de facturación.

El chatbot entra en conflicto con otros widgets

Si otro widget de chat (Intercom, Crisp, Drift) se superpone con el tuyo, puedes eliminar el otro widget, cambiar la posición de Agentkit a bottom-left, o usar el método de iframe para colocar el chatbot en línea en lugar de como una burbuja flotante.

Elige el plan correcto para tu incrustación

La facturación anual ahorra aproximadamente un 20% en todos los planes pagos. Empieza con el plan Free para probar la incrustación y luego mejora tu plan cuando tu tráfico requiera más mensajes.

Próximos pasos

Una vez que tu chatbot esté incrustado, el trabajo pasa de la instalación a la optimización:

1. Monitorea las conversaciones en el panel de Agentkit durante la primera semana. Identifica las preguntas con las que el chatbot tiene dificultades.
2. Agrega datos de entrenamiento para los puntos débiles. Los pares de preguntas y respuestas son la forma más rápida de resolver problemas específicos de respuesta.
3. Activa la captura de leads para recopilar correos electrónicos de los visitantes durante las conversaciones. Consulta la guía de generación de leads.
4. Conéctate a tus herramientas mediante Zapier, webhooks o la API REST. Consulta la guía de integraciones.
5. Configura la restricción de dominio y el límite de frecuencia para la seguridad y la gestión de la cuota.

Para recorridos específicos por plataforma, consulta las guías detalladas:

• WordPress
• Shopify
• Squarespace
• Wix
• Webflow

Crea tu chatbot gratis →

No se requiere tarjeta de crédito.