Widget embebible

El camino más corto para tener un agente en tu web: una etiqueta <script> y ya hay un chat flotante, con los colores que hayas configurado en el panel.

Por debajo es un Web Component (<ur-agent-chat>) sin dependencias de framework, que delega toda la comunicación en @nykk/ur-agent-client.

Antes de empezar

El canal widget del agente tiene que estar habilitado, y tu dominio permitido en su lista de orígenes. Ver Canales.

El snippet

<script
  src="https://<tu-backend-ur>/widget.js"
  data-agent="<identifier-del-agente>"
></script>

Eso es todo. El script se inyecta solo en document.body y se descarga del backend el título y los colores del agente, así que normalmente no hace falta nada más.

El panel te da este mismo snippet ya relleno, en la ficha del canal widget del agente.

/widget.js tiene que ser el mismo origen que el backend

El bundle lo sirve el propio backend de ur. No lo copies a otro dominio ni a un CDN: el widget resuelve a qué backend hablar a partir del origen desde el que se carga.

Atributos del <script>

Atributo	Por defecto	Qué hace
data-agent	—	Obligatorio. identifier o id del agente
data-api-base	El origen del script	Backend de ur, si es otro
data-channel	widget	El canal por el que entra
data-title	Del panel, o Asistente virtual	Título de la cabecera
data-color	Del panel	Color principal (cabecera, burbuja del usuario)
data-color-text	Del panel	Color del texto sobre el color principal
data-color-bot	Del panel	Fondo de las burbujas del agente
data-context	—	Contexto de cliente, como JSON

Como módulo, dentro de tu app

Si ya tienes un bundler y prefieres colocar el elemento tú:

npm install @nykk/ur-agent-widget

import '@nykk/ur-agent-widget';

<ur-agent-chat
  agent="<identifier-del-agente>"
  api-base="https://<tu-backend-ur>"
  title="Asistente virtual"
></ur-agent-chat>

Importado así no se auto-monta nada: el elemento va donde tú lo pongas. Los atributos son los mismos de la tabla de arriba sin el prefijo data-, más dos que solo existen en esta forma:

Atributo	Qué hace
subject	Reanuda una conversación concreta en vez de la guardada en el navegador
started-at	Fecha ISO. Pone el panel en modo lectura de una conversación existente
inline	Booleano. En vez de flotar, rellena su contenedor y oculta burbuja, cierre y reinicio

Colores y tema

Al arrancar, el widget pide al backend la configuración del agente y rellena con ella el título y los colores que no le hayas fijado explícitamente. Es decir: el sitio de cambiar la marca es el panel, y el snippet se queda limpio.

Para un control más fino, el componente expone variables CSS en su :host:

ur-agent-chat {
  --uw-primary: #4f46e5;
  --uw-primary-text: #ffffff;
  --uw-bot-bubble: #f1f5f9;
  --uw-radius: 12px;
  --uw-panel-width: 380px;
  --uw-panel-height: 600px;
  --uw-bottom: 24px;
  --uw-right: 24px;
}

Están además --uw-primary-hover, --uw-bg, --uw-text, --uw-text-secondary, --uw-user-bubble, --uw-user-text, --uw-bot-text, --uw-border, --uw-input-bg, --uw-font, --uw-shadow y --uw-bubble-size.

Contexto por turno

Si las tools del agente declaran contexto, puedes pasárselo. Desde HTML:

<script
  src="https://<tu-backend-ur>/widget.js"
  data-agent="soporte"
  data-context='{"visitor_context":{"page":"/precios"}}'
></script>

Desde JavaScript es mejor asignar la propiedad — evita el parseo y permite actualizarla conforme el usuario navega, sin recrear el widget (que perdería la conversación):

document.querySelector('ur-agent-chat').context = {
  visitor_context: { page: '/contacto' },
};

Un JSON mal formado en el atributo no rompe el widget: se avisa por consola y se ignora.

Lee Contexto de cliente antes de usarlo — sobre todo la parte de que no es una credencial.

Detalles de uso

• Reiniciar la conversación es mantener pulsado el botón de reinicio ~2 segundos, no un clic. Es deliberado: evita perder el hilo por un toque accidental.
• El panel se puede maximizar, con un tope de 800×800 px.
• El widget guarda la identidad de conversación en localStorage, así que el usuario recupera su hilo al volver.

Si el widget no te encaja

Cuando necesites tu propio diseño o integrarlo en una pantalla existente, la pieza de abajo es el SDK: SDK — quickstart.