Insertar el Widget de chat (Guía para desarrolladores)

Widget Embed Guide

El widget es un Web Component (<web-chat-agent>) que se carga de forma asíncrona y funciona en cualquier sitio, sin frameworks ni pasos de compilación. El script genera un botón de chat flotante; los visitantes hacen clic en él para abrir la ventana de chat.

Embed Code

Pega esto justo antes de la etiqueta de cierre </body>:

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Reemplaza YOUR_CHATBOT_ID con tu ID del chatbot. Encuentra el código de incrustación ya completado en Panel → tu asistente → Canales → Widget de chat → Mostrar detalles de instalación y cópialo desde allí para evitar errores tipográficos.

El widget llama a la API en el mismo origen desde el que se cargó. Carga el script desde webchatagent.com y las solicitudes de chat irán a webchatagent.com/api/... automáticamente, nunca configuras una URL de API manualmente.

Cómo funciona

1. El script async se carga en segundo plano y no bloquea el renderizado de la página.
2. El elemento <web-chat-agent> genera un botón de chat flotante.
3. El widget obtiene la configuración de tu panel (colores, textos, herramientas, mensaje de bienvenida) y la aplica. No se necesitan atributos adicionales.
4. El visitante hace clic en el botón, se abre la ventana de chat y los mensajes se envían a tu chatbot de IA.

Atributos HTML

Cada ajuste visual de Canales → Widget de chat se aplica automáticamente. Los atributos HTML en el elemento son ajustes opcionales que sobrescriben la configuración; úsalos solo para cambios específicos por página (por ejemplo, una posición diferente en una página de destino). Los nombres de los atributos usan kebab-case (el widget asigna theme-color a la propiedad themeColor internamente).

Los valores predeterminados a continuación son las opciones de reserva integradas del widget. En la práctica, la mayoría de los atributos se dejan sin definir y heredan el valor que configuraste en el panel.

Configuración básica

Colores

Todos los atributos de color aceptan cualquier color CSS válido (hexadecimal como #2563eb, rgb(), hsl()). Cuando no se definen, el widget utiliza el valor de tu panel o su opción de reserva integrada (el color predeterminado de marca es azul, #2563eb).

Imágenes

Posicionamiento

Contenido y comportamiento

Actualización del consentimiento en tiempo de ejecución

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Envía denied cuando el consentimiento sea rechazado o revocado. Los activadores locales anónimos permanecen disponibles. Consulta la guía de consentimiento de cookies para ver la matriz de activadores y los adaptadores CMP.

Botones de sugerencia

Botones de acción rápida que se muestran debajo de la lista de mensajes. Cada botón tiene un title visible y una action (el texto enviado como el mensaje del usuario al hacer clic). Pasa un array JSON como valor del atributo:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Session Context Data

Cuando el widget se ejecuta dentro de un sistema que ya conoce al visitante, como un CRM, un portal de clientes o un área con inicio de sesión, la página que lo integra puede pasar esa información al chatbot. La IA ve los valores, hace referencia a ellos en sus respuestas y los utiliza para completar los argumentos correspondientes en llamadas a herramientas MCP y conectores API. Un visitante cuyo número de caso ya aparece en pantalla nunca debería tener que escribirlo de nuevo.

Los datos de contexto se envían con cada solicitud de chat de la sesión, se inyectan en el prompt de la IA solo para esa solicitud y no se almacenan como un registro propio.

Pasar el contexto mediante el atributo HTML

Se aceptan dos formatos. El formato simple no requiere conocimientos de JSON, ya que utiliza pares Clave=Valor separados por punto y coma:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Solo el primer = de cada par separa la clave y el valor, de modo que los valores que contienen = (por ejemplo, tokens en base64) permanecen intactos. En este formato, un valor no puede contener un punto y coma; utilice JSON para ese caso:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

Con JSON, envuelva el valor del atributo entre comillas simples para que las comillas dobles internas se conserven.

Pasar el contexto mediante JavaScript

Si prefiere JavaScript en lugar del atributo (o lo necesita, por ejemplo en WordPress), configure la variable global window.webchatagentContext. Se puede definir con total seguridad antes de que se haya cargado el script del widget; el widget lo detecta al inicializarse, por lo que el orden de carga de los scripts no importa:

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Actualizar el contexto en tiempo de ejecución

Cuando los datos cambien mientras el widget ya está en ejecución (inicio de sesión, cambio a otro caso), envíe el evento webchatagent:context con un objeto simple:

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Cada evento reemplaza el contexto completo; detail: null o {} lo borra. Prioridad al cargar: se aplica primero el atributo context-data, luego window.webchatagentContext (si está definido) y después los eventos. El contexto reside en la página; tras recargarla, configúrelo de nuevo.

Implementaciones con marca blanca: los alias neutrales respecto a la marca window.chatWidgetContext (global) y chat-widget:context (evento) funcionan de forma idéntica, por lo que las páginas integradas nunca necesitan hacer referencia al nombre de la plataforma.

Límites

Un máximo de 20 claves, nombres de clave de hasta 64 caracteres, valores de hasta 500 caracteres (los números y booleanos se convierten a cadenas), 4.000 caracteres en total. Los saltos de línea y los caracteres < > se eliminan de las claves y los valores. Las respuestas a solicitudes con datos de contexto nunca se sirven desde la caché de respuestas.

Seguridad: los datos de contexto no son autenticación

Los valores provienen del navegador del visitante. Cualquiera puede abrir DevTools y enviar un contexto arbitrario, por lo que la IA está instruida para tratarlo como datos de fondo no verificados; nunca base la autorización en ellos.

Dos reglas para su uso en producción:

1. Restrinja allowedDomains para su chatbot en el panel. Sin esto, cualquier página puede integrar su bot y suministrarle contexto.
2. Para consultas de datos personales, pase un token opaco en lugar de la identidad directa. Genere en el servidor un token de corta duración para el usuario con sesión iniciada, páselo como un valor de contexto (por ejemplo, userToken=...) y deje que el endpoint de su conector API valide el token antes de devolver los datos del usuario. La IA reenvía el token en la llamada API; su backend decide qué autoriza. Un token falsificado no devolverá nada.

WordPress

El plugin de WordPress (a partir de su próxima versión) admite datos de contexto en el servidor: el filtro webchatagent_context_data los suministra para el widget flotante (y como valor predeterminado para las integraciones inline), y el shortcode inline acepta un atributo context-data:

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

En versiones anteriores del plugin, configure window.webchatagentContext o envíe el evento webchatagent:context en su lugar; ambos métodos funcionan en cualquier plataforma.

Ejemplo: Personalización completa

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Panel frente a atributos HTML

Los ajustes del panel se almacenan en el servidor y se cargan cuando el widget se inicializa. Los atributos HTML los sobrescriben solo para esa página.

Recomendación: Realice toda la personalización visual en el panel. Recurra a los atributos HTML solo cuando una página deba ser diferente, ya sea por un posicionamiento distinto, un tema forzado o botones de sugerencia específicos para la página.

CSS personalizado

Para cambios que van más allá de los atributos anteriores, aplique estilos a los elementos internos del widget con su propio CSS. Cada elemento personalizable incluye una clase .wca-* estable (por ejemplo .wca-header, .wca-message, .wca-bubble), por lo que sus selectores seguirán funcionando tras las actualizaciones del widget y no requieren !important. Añada el CSS en el panel y se inyectará en el shadow DOM del widget. Consulte CSS personalizado.

Chat integrado

Para mostrar el chat dentro del diseño de su página en lugar de un botón flotante, utilice la variante inline. Esta carga un script diferente y un elemento distinto (<web-chat-agent-inline>):

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

El elemento inline acepta chatbot-id, un container-height opcional, además de tracking-consent y context-data (consulte Session Context Data; el atributo y el evento en tiempo de ejecución funcionan de forma idéntica aquí); el resto de los ajustes provienen de Canales → Chat integrado. Coloque el elemento donde desee que aparezca el chat y ajuste su tamaño con el contenedor que lo rodea. Consulte Chat integrado para obtener más información.

WordPress

En WordPress, utilice el WebChatAgent WordPress Plugin oficial en lugar de pegar el script manualmente. Gestiona la integración y las actualizaciones automáticamente. Consulte Plugin de WordPress.

Single Page Applications (SPA)

El widget funciona de forma nativa con React, Vue, Angular y otras SPA. Añada la etiqueta de script a index.html y coloque el elemento <web-chat-agent> en la estructura principal de su aplicación (por ejemplo, el diseño raíz). El widget persiste a través de los cambios de ruta del lado del cliente, por lo que no es necesario volver a montarlo al navegar.