Integrar el widget web
Ponga su agente en cualquier sitio web con una sola etiqueta de script — con modos burbuja, ventana y pantalla completa incluidos.
Integración básica
<script src="https://chat.agent4.io/ui/embed.js"
data-token="YOUR_SHARE_TOKEN" async></script>El cargador inyecta una burbuja de chat flotante (abajo a la derecha) que se despliega en ventana o a pantalla completa. El iframe apunta al origen de la plataforma, así que su sitio no necesita ninguna configuración de CORS.
Opciones
| Atributo | Efecto |
|---|---|
data-token | Obligatorio. El token de share generado en la consola. |
data-color | Color de acento para la cabecera y la burbuja del widget. |
data-position="left" | Ancla la burbuja abajo a la izquierda en lugar de a la derecha. |
Teclado: Ctrl/⌘ + Shift + F alterna entre burbuja, ventana y pantalla completa.
Paleta de comandos (barra Ask)
¿Prefiere el patrón moderno de «Ask a question» que ve en los sitios de documentación? Cambie
embed.js por ask.js — la misma línea de script, sin ningún otro cambio:
<script src="https://chat.agent4.io/ui/ask.js"
data-token="YOUR_SHARE_TOKEN" async></script>Esto inyecta una barra fina de Ask a question al pie de la página. Al hacer clic en ella — o al
pulsar ⌘K / Ctrl+K en cualquier parte — se despliega en una paleta de comandos centrada sobre un
fondo atenuado; Esc o un clic fuera la cierra. La barra no es una etiqueta fija: escribe sola, una
tras otra, las preguntas que sus visitantes más probablemente hacen en esa página (tomadas de los
mismos guiones de página que alimentan las preguntas sugeridas de la burbuja).
| Atributo | Efecto |
|---|---|
data-token | Obligatorio. El token de recurso compartido de la consola. |
data-color | Color de acento. |
data-position | bottom-center (predeterminado), bottom-right o bottom-left. |
La paleta ejecuta exactamente el mismo agente, recuperación y autenticación que la burbuja — incluido el modo host-session de abajo — así que todo lo demás en esta página se aplica sin cambios. Elija burbuja o barra Ask por recurso compartido en la consola (Integración en el sitio web → Burbuja de chat / Barra Ask).
Lista de dominios permitidos
Cada share lleva una lista allowed_domains. La plataforma la aplica mediante una CSP
frame-ancestors, de modo que el widget solo se renderiza dentro de los sitios que usted indicó. Se
configura en el propio share, desde la consola.
Modos de autenticación
Un share funciona en uno de estos tres modos:
- Anónimo — los visitantes conversan sin cuenta; cada navegador obtiene su propio espacio.
- Inicio de sesión con cuenta — los visitantes acceden con una cuenta de usuario final de la plataforma; el historial y la memoria los acompañan entre dispositivos.
- Sesión del anfitrión (HMAC) — su backend le indica al widget quién es el usuario, de modo que sus usuarios ya autenticados son reconocidos sin un segundo inicio de sesión:
<script src="https://chat.agent4.io/ui/embed.js"
data-token="YOUR_SHARE_TOKEN"
data-uid="user-42"
data-ts="1767139200"
data-sig="HMAC_SHA256(secret, uid + ts)"
async></script>Su servidor calcula data-sig con el secreto de firma del share; la plataforma lo verifica y asocia
user-42 a una identidad de usuario final estable.
Página independiente
Todo share es accesible además como página completa en
https://chat.agent4.io/s/YOUR_SHARE_TOKEN, algo útil para códigos QR, enlaces en correos o páginas de
aterrizaje publicitarias cuando usted no controla el sitio que las aloja.