Deploy

Atributos del widget

Todo lo que se puede configurar desde el HTML del embed.

Todo lo que se puede configurar desde el HTML del embed. Los obligatorios son los tres primeros; el resto tiene valores por defecto pensados para no cambiar el comportamiento de nadie.

Conexión

Atributo	Qué hace
`gateway-url`	La URL pública de tu plataforma.
`agent-id`	El id del agente que responde.
`api-key`	La clave de consumo. Publicable por diseño.
`session-id`	Retomar una sesión concreta. Tiene prioridad sobre la guardada.
`persist-session`	Guarda el id de sesión y retoma al recargar.

Apariencia

Atributo	Valores
`theme`	`dark`, `light`, o vacío para seguir al sistema.
`mode`	`inline` (por defecto) o `floating`.
`open`	Si la tarjeta flotante empieza abierta. Inerte en inline.
`greeting`	El titular del estado vacío. `""` lo oculta.
`placeholder`	El texto del campo de escritura.
`lang`	`es` o `en`. Si no, lo hereda del `<html lang>` de la página.

El marco del widget —borde y radio— no es un atributo sino dos propiedades CSS, --ai-chat-frame-border-width y --ai-chat-frame-radius, ambas en 0 por defecto. Si la página ya dibuja un panel, dos bordes a 40px de distancia es el síntoma de haberlas activado sin querer.

Comportamiento

Atributo	Por defecto	Qué hace
`verbosity`	quieto	`full` muestra la narración del proceso del modelo.
`model-switcher`	apagado	Deja cambiar de modelo antes del primer mensaje.
`dictation`	apagado	Botón de dictado por voz.
`dictation-lang`	resuelto	Idioma del dictado, separado del de la interfaz.

La polaridad de los valores por defecto no es casual

model-switcher y dictation están apagados y verbosity está en modo quieto, y las razones son opuestas:

Los dos primeros añaden un control. Este bundle se publica a todos los embeds a la vez, así que encenderlos por defecto haría que el chat de cada cliente creciera un botón porque nosotros publicamos algo. Lo mismo vale para mode: un valor por defecto flotante pondría un panel fijo sobre la página de todos.

verbosity quita texto que nunca fue para el visitante. Un turno que instaló un paquete y escribió un script mostraba cuatro párrafos de mecánica con el mismo peso visual que la respuesta. El visitante en el sitio de un cliente no sabe qué es un contenedor.

Dictado

dictation usa el reconocimiento de voz del navegador. Cero librerías, cero backend, cero costo — y no es on-device: Chrome manda el audio a Google y Safari a Apple.

A la plataforma no llega nada, pero la voz del visitante sale de la página. Por eso es opt-in y por eso está dicho aquí.

El botón no se dibuja si el navegador no lo soporta o el contexto no es seguro. No aparece muerto.

Cambio de modelo

Cuando model-switcher está activo, la lista se restringe a la familia de la credencial del agente, y solo funciona antes del primer mensaje.

No es una limitación arbitraria: la configuración de la sesión es inmutable, y cambiar de modelo a mitad rompe la validación de firmas de razonamiento en Anthropic y la reproducción del razonamiento en DeepSeek.

Aviso

La familia es una restricción de protocolo, no de precio. Como la clave de consumo es publicable, sin un techo explícito cualquiera que lea el embed puede hacer correr un agente barato a precio de modelo caro. Ese techo se pone en la configuración del agente, con switchable_models. Ausente = toda la familia; una lista vacía = sin cambio de modelo.

Identidad

Atributo	Qué hace
`end-user-id`	Quién dice el sitio que está conectado.
`end-user-hash`	La prueba, firmada por el backend del cliente.

Los dos o ninguno — ver Identidad de usuario final.

Variables dinámicas

Atributo	Qué hace
`dynamic-variables`	Valores para esta conversación, como objeto JSON.

<ai-chat
  agent-id="..."
  api-key="..."
  dynamic-variables='{"user_name": "Ana", "plan_tier": "premium"}'
></ai-chat>

Se envían una vez, al abrir la sesión. Cambiar el atributo después no alcanza a una conversación que ya existe: son el estado inicial, no un enlace vivo — si lo reescribiéramos a mitad, el mismo transcript se renderizaría distinto al recargar.

Aviso

El gateway recorta este mapa a las variables que el agente declara en su configuración, y rechaza cualquier nombre secret__*. No es una formalidad: la clave de consumo es publicable, así que quien lea el HTML de la página podría fijar una variable que el prompt trata como un hecho de autorización («el plan del cliente es {{plan_tier}}»). La configuración del agente es la declaración de qué puede influir una página.

Un valor mal formado se descarta en silencio, no revienta: es un atributo en la página de otro y una comilla suelta no debe tumbar el chat. Dónde se ve que una variable no llegó es en el panel {} Vars de la consola.