Deploy
Insertar el widget
Poner el chat en el sitio de un cliente.
El widget es un web component: una etiqueta HTML que el cliente pega en su sitio y que abre el chat contra un agente tuyo. No necesita framework, no necesita build, y funciona igual en un sitio hecho con React que en uno hecho a mano.
Lo que necesitas antes de empezar
Dos cosas, y una de ellas hay que crearla:
- El id del agente. Está en la URL de su página:
/agents/<id>. - Una clave de consumo, que se crea en
API keys. Es un tipo de clave distinto de las de administración — ver Claves API.
Aviso
La clave de consumo es publicable, y eso es intencional: cualquiera que vea el HTML de la página puede extraerla. Identifica al embed, no a la persona. No pongas ahí una clave de administración, y no asumas que un visitante no puede leerla.
El snippet
<script src="https://tu-cdn/ai-chat.iife.js"></script>
<ai-chat
gateway-url="https://tu-gateway.example.com"
agent-id="EL_ID_DEL_AGENTE"
api-key="LA_CLAVE_DE_CONSUMO"
lang="es"
persist-session
></ai-chat>
Eso es todo lo mínimo. El elemento se llena del alto y ancho que le dé la caja donde lo pongas, así que el tamaño lo controla el CSS del cliente:
ai-chat {
display: block;
height: 600px;
}
Inline o flotante
Por defecto el widget es inline: un bloque que ocupa su hueco en la página,
como cualquier otro elemento. Con mode="floating" se convierte en una burbuja
en la esquina que abre una tarjeta, al estilo de un chat de soporte.
<ai-chat mode="floating" gateway-url="..." agent-id="..." api-key="..."></ai-chat>
Nota
Que inline sea el valor por defecto no es una preferencia estética: el bundle se publica a todos los embeds a la vez, así que un default flotante pondría un panel fijo encima de la página de cada cliente sin que nadie desplegara nada.
Cerrado, el modo flotante no renderiza el chat en absoluto — detrás de la burbuja no hay ni conexión abierta ni nada escuchando.
Idioma
El widget resuelve su idioma en este orden: el atributo lang, luego el
<html lang> de la página, luego el navegador, y en último caso inglés.
En un sitio en español no hace falta poner nada — lo hereda del <html lang> del
cliente. El atributo es para cuando el sitio declara un idioma y el chat debe ir
en otro.
Persistir la conversación
Con persist-session, el widget guarda el id de la sesión en localStorage y al
recargar la página retoma la conversación donde iba. Sin el atributo, cada carga
empieza de cero.
Es lo que casi siempre quieres, con una salvedad importante: en un sitio donde
varias personas usan el mismo navegador, guardar la sesión sin identificar a cada
una hace que compartan el historial. Para eso está Identidad de usuario
final, y es la solución correcta a ese
problema — no quitar persist-session.
Qué NO llega al widget
El resultado crudo de una herramienta no sale del gateway. Si el agente consulta un inventario, el widget recibe la respuesta redactada por el modelo, no las filas que devolvió la consulta.
Eso es estructural, no una opción: una clave de consumo es publicable, y un
resultado de herramienta puede traer datos del cliente o salida de una shell.
Para leer el resultado crudo está la pestaña Debug de la sesión en la consola,
que es la superficie hecha para diagnosticar.
Errores
El widget no muestra el error crudo. Traduce el fallo a una frase para el visitante y decide si ofrece reintentar — un 401 no lo ofrece, porque mandaría a alguien a golpearse contra una pared.
El texto original no se pierde: queda guardado tal cual en la sesión y lo
puedes leer en Sessions.
Siguientes pasos
- Atributos del widget — todo lo configurable.
- Identidad de usuario final — que cada visitante vea solo lo suyo.