#Un chat con IA para tu sitio web

Para poner un chat con IA en tu sitio web con Vatio, publicas tu agente, creas un token publicable vatpub_ que solo funciona desde el origen de tu sitio y pegas una etiqueta script. El widget toma su apariencia del inbox de Vatio, y cualquier página puede sobrescribirla; el nombre y la descripción del negocio con los que trabaja el agente se configuran en la página Negocio del inbox. Cuando tu backend firma un token que dice quién es el visitante, el mismo widget reconoce a tus clientes autenticados y corre las tools que leen sus propios datos. Es el mismo agente que responde en WhatsApp e Instagram, descrito en un archivo vatio.yml.

Esta guía va de un agente publicado a un widget en tu sitio: con tu marca, sabiendo quién inició sesión y probado antes en preview.

#Parte de un agente publicado

El widget habla con un entorno, normalmente live. Si todavía no tienes un agente, Construir un agente de IA te lleva hasta ahí; después:

vatio push
vatio publish

Antes de publicar, pruébalo en la página Probar del inbox, el link que imprime vatio push después de Try it:. El widget necesita un sitio donde vivir; si no tienes sitio web, o todavía no, el mismo agente puede atender a tus clientes por WhatsApp o Instagram.

#Crea un token para tu sitio

vatio tokens create --env live --label sitio \
  --origin https://tostaduria-brasa.example --origin http://localhost:3000

create imprime el token completo una sola vez. Un token publicable funciona solo desde sus orígenes permitidos, además de las páginas de Vatio y los app builders: todo token acepta las vistas previas y las apps publicadas de Lovable, Replit, Bolt, v0 y Base44 sin listarlas, así que una app hecha ahí funciona en cuanto pegas el snippet. Los orígenes son valores exactos scheme://host[:port], sin ruta ni comodín, así que https://www.tostaduria-brasa.example es un segundo origen que tienes que listar si tu sitio también responde ahí. Una página en un origen que el token no acepta recibe origin_not_allowed, y la consola del navegador nombra ese origen, listo para pegar.

vatio tokens origins PREFIX URL... reemplaza la lista de un token, y la sección de tokens de Canales → Widget web, en el inbox, también la edita. vatio tokens list muestra los prefijos y los orígenes; vatio tokens revoke PREFIX impide nuevos chats con ese token, mientras las credenciales de chat ya emitidas siguen válidas hasta que expiran.

Un token publicable elige un workspace y un entorno, y no puede desplegar nada ni abrir el inbox: está hecho para el código de la página. Nunca pongas un token de developer vat_ en un navegador. Y los orígenes mantienen el token en tu sitio, pero no dicen nada sobre quién es el visitante. Eso le toca al token de visitante, más abajo.

#Pega una etiqueta script

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="tostaduria-brasa"
        data-token="vatpub_REPLACE_ME"></script>

Ponla antes de </body> en el layout que comparten todas tus páginas. El widget espera a que la página cargue y quede inactiva antes de iniciarse, para no competir con tu propio contenido; data-eager="true" lo inicia de inmediato. Canales → Widget web también muestra un Snippet de instalación listo, con un token que administra Vatio; los orígenes de ese token se editan en la sección de tokens de la misma página.

Si tu app usa un bundler (React, Next.js, Vue, Svelte), puedes instalar el mismo widget desde npm y montarlo desde tu propio código: npm install @vatio-ai/widget y después mountVatioWidget({ workspace, token }), que te devuelve identify y unmount. Las opciones son las mismas que los atributos data-*, en camelCase; ve From your app’s code. El widget es open source (MIT) en github.com/vatio-ai/widget.

En la web, cada respuesta es un mensaje completo que el widget muestra de forma progresiva, en Markdown, así que las listas, las negritas y los links se ven como corresponde. WhatsApp e Instagram reciben las respuestas del mismo agente como mensajes de texto plano, al ritmo de alguien que escribe. El agente solo envía URL que se le dieron, y cuando una consulta parece resuelta, el widget le pregunta una vez al visitante cómo lo ayudó el agente; la calificación aparece en el inbox.

#Que se vea como tu marca

En el inbox, abre Canales → Widget web para definir el logo, que es el avatar del agente en el widget y en la página de chat; el color de acento; Acerca de, el texto que ve el visitante al abrir el widget, antes de que nadie escriba; el título, el saludo, hasta cuatro sugerencias, la posición, el esquema de color, el radio de las esquinas, la fuente, el idioma y más colores.

El nombre y la Descripción del negocio, que van en el prompt del agente alrededor de sus instrucciones, no están ahí: los configura quien lleva el negocio en la página Negocio del inbox, junto con el horario de atención. Así es como el agente sabe qué es el negocio.

Es configuración del workspace, no parte de un deployment: al guardar se aplica de inmediato a todos los entornos, sin push ni publicación. Un bloque widget: o business: en un vatio.yml antiguo se ignora con una advertencia.

Una página puede sobrescribir cualquiera de los valores del widget en su propia etiqueta; se resuelven desde la página, luego el workspace y luego el default de la plataforma. En las páginas de suscripción, por ejemplo:

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="tostaduria-brasa"
        data-token="vatpub_REPLACE_ME"
        data-greeting="¿Dudas sobre tu suscripción? Pregúntame."
        data-suggestions="¿Cuándo llega mi próximo envío?|¿Qué café viene este mes?|¿Cómo preparo un V60?"
        data-accent="#8A3B12"
        data-position="left"
        data-locale="es"></script>

Los atributos son data-accent y data-accent-ink, data-surface, data-ink, data-muted y data-line (todos #RRGGBB), data-scheme (auto, light o dark), data-position (right o left), data-reply-style (stream, o paced para mensajes cortos con indicador de escritura, como en WhatsApp), data-font (inherit usa la fuente de tu sitio), data-radius, data-title, data-greeting, data-suggestions (separadas por |, hasta cuatro), data-about y data-locale (en, es o pt). data-locale define los textos de la interfaz, cuyo default es inglés; el agente responde en el idioma del visitante de todas formas.

#Reconoce a tus clientes autenticados

Para decirle al agente quién está escribiendo, tu backend firma un JWT y Vatio lo verifica. Vatio guarda solo tu llave pública, así que puede revisar un token pero nunca emitir uno.

vatio auth --new-key

identity.pub se queda en el workspace y vatio.yml la nombra bajo auth. identity.pem va a tu backend como secreto, nunca a vatio secrets set. Tu backend firma con RS256, con sub (el id de tu usuario), aud (el slug de tu workspace) y un exp corto; name y email son opcionales:

// Node (jsonwebtoken)
jwt.sign(
  { sub: String(user.id), name: user.name, email: user.email },
  process.env.VATIO_IDENTITY_PRIVATE_KEY,
  { algorithm: "RS256", audience: "tostaduria-brasa", expiresIn: "1h" }
);

Ponlo en la etiqueta solo para los visitantes que iniciaron sesión:

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="tostaduria-brasa"
        data-token="vatpub_REPLACE_ME"
        data-visitor-token="JWT_FIRMADO"></script>

Los visitantes sin sesión no reciben token, y el agente los atiende con sus tools públicas. Cuando alguien inicia sesión sin recargar la página, llama a window.VatioWidget.identify(nuevoToken); null cierra la sesión. La conversación sobrevive al inicio de sesión: una pregunta hecha como anónimo continúa, ahora con un nombre, así que el agente puede responderla sin que el cliente la vuelva a escribir. Un token con otro sub, o cerrar la sesión, empieza una conversación nueva, así que en un dispositivo compartido un cliente nunca ve el chat de otro. Pon un token nuevo en cada carga de página para que la conversación sobreviva al primer exp.

Con un visitante verificado, corren las tools marcadas access: private. tools/mi_suscripcion.yml, con la dirección de la API guardada con vatio secrets set BRASA_API:

description: La suscripción del cliente autenticado y su próximo envío.
when_to_use: Un cliente autenticado pregunta por su propia suscripción, su próxima caja o la fecha de envío.
access: private
request:
  method: GET
  base_url: "$env.BRASA_API"
  path: /me/suscripcion
  headers:
    Authorization: "Bearer $auth.token"
respond:
  data:
    suscripcion: "$.suscripcion"

agent:
  instructions: |
    ...
    Preguntas sobre la suscripción: llama a mi_suscripcion. Si el visitante
    no ha iniciado sesión, envíale el link iniciar_sesion y responde cuando
    vuelva.
  tools: [mi_suscripcion, knowledge_lookup]
  links:
    iniciar_sesion: https://tostaduria-brasa.example/ingresar
auth:
  public_key: identity.pub

Tu endpoint verifica el mismo JWT con la llave pública y lee la suscripción de su sub. Una tool privada nunca recibe el id del usuario como parámetro, y el deploy falla si lo hace: los parámetros los llena el modelo, y podrían convencerlo de poner el de otra persona. Un token rechazado deja al visitante como anónimo en vez de fallar. Conectar tu backend entra en más detalle.

#Prueba los cambios primero en preview

Preview es su propio entorno, con su propio agente, cambios de conocimiento, chats y tokens publicables. Después de vatio push, vatio env imprime el token, el snippet del widget y el link de prueba de preview. vatio tokens create --env preview --origin https://staging.tostaduria-brasa.example crea un token para tu sitio de staging en preview, y uno con --origin http://localhost:3000 sirve para trabajar en local.

La apariencia es la excepción: la configuración de Canales → Widget web es de todo el workspace y aplica en todas partes apenas guardas. Para probar una apariencia nueva solo en staging, usa atributos data-* ahí.

#Tu propia interfaz con el SDK de navegador

Cuando el chat es parte de tu producto y no una burbuja en la esquina, usa el SDK de navegador con el mismo token y los mismos orígenes:

npm install @vatio-ai/sdk

import { Vatio } from "@vatio-ai/sdk";

const chat = await Vatio.chat({ workspace: "tostaduria-brasa", token: "vatpub_REPLACE_ME" });
chat.on("message", (message) => render(message)); // deduplica por message.id
chat.on("typing", (typing) => showTyping(typing));
for (const message of await chat.history()) render(message);
await chat.send("¿Cuándo llega mi próximo envío?");

visitorToken recibe el mismo JWT firmado que data-visitor-token. replyStyle es stream por defecto, una respuesta completa para mostrar de forma progresiva, y paced entrega mensajes cortos con indicadores de escritura. chat.send acepta hasta cuatro archivos: imágenes, PDF, texto o audio. La referencia del SDK lista cada método y opción.

#Míralo desde el inbox

Cada conversación, desde el widget o desde el SDK, aparece en el inbox con sus llamadas a tools. Agrega un objeto metadata al token de visitante, con un link profile a tu panel de administración y algunos badges como el plan del cliente, y el inbox los muestra en el encabezado de la conversación, para que quien responda sepa con quién habla. Los supervisores toman una conversación respondiendo, y marcan las respuestas malas con lo que debió pasar; tu coding agent corrige la causa desde esas notas, como explica Mejorar tu agente.

Actualizado: 11 de octubre de 2026