#Um chat com IA para o seu site

Para colocar um chat com IA no seu site com a Vatio, você publica seu agente, cria um token publicável vatpub_ que só funciona a partir da origem do seu site e cola uma tag script. O widget pega a aparência do inbox da Vatio, e qualquer página pode sobrescrevê-la; o nome e a descrição do negócio com os quais o agente trabalha ficam na página Negócio do inbox. Quando seu backend assina um token dizendo quem é o visitante, o mesmo widget reconhece os clientes logados e roda as tools que leem os dados deles. É o mesmo agente que responde no WhatsApp e no Instagram, descrito em um arquivo vatio.yml.

Este guia vai de um agente publicado até um widget no seu site: com a sua marca, sabendo quem está logado e testado antes no preview.

#Comece de um agente publicado

O widget conversa com um ambiente, normalmente o live. Se você ainda não tem um agente, Construir um agente de IA leva você até lá; depois:

vatio push
vatio publish

Antes de publicar, teste na página Testar do inbox, o link que o vatio push imprime depois de Try it:. O widget precisa de um site onde ficar; se você não tem site, ou ainda não tem, o mesmo agente pode atender seus clientes no WhatsApp ou no Instagram.

#Crie um token para o seu site

vatio tokens create --env live --label site \
  --origin https://cafe-serra-alta.example --origin http://localhost:3000

O create imprime o token completo uma única vez. Um token publicável só funciona a partir das origens permitidas dele, além das páginas da própria Vatio e dos app builders: todo token aceita os previews e os apps publicados do Lovable, Replit, Bolt, v0 e Base44 sem listá-los, então um app feito ali funciona assim que você cola o snippet. As origens são valores exatos scheme://host[:port], sem caminho nem curinga, então https://www.cafe-serra-alta.example é uma segunda origem para listar se o seu site também responde ali. Uma página em uma origem que o token não aceita recebe origin_not_allowed, e o console do navegador mostra essa origem, pronta para colar.

vatio tokens origins PREFIX URL... substitui a lista de um token, e a seção de tokens de Canais → Widget web, no inbox, também a edita. vatio tokens list mostra os prefixos e as origens; vatio tokens revoke PREFIX impede novos chats com esse token, enquanto as credenciais de chat já emitidas continuam válidas até expirar.

Um token publicável escolhe um workspace e um ambiente, e não consegue fazer deploy nem abrir o inbox: ele foi feito para o código da página. Nunca coloque um token de developer vat_ em um navegador. E as origens mantêm o token no seu site, mas não dizem nada sobre quem é o visitante. Isso é trabalho do token de visitante, mais abaixo.

#Cole uma tag script

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

Coloque antes do </body> no layout que todas as páginas compartilham. O widget espera a página carregar e ficar ociosa antes de iniciar, para não competir com o seu próprio conteúdo; data-eager="true" faz ele iniciar na hora. Canais → Widget web também mostra um Snippet de instalação pronto, com um token que a Vatio gerencia; as origens desse token são editadas na seção de tokens da mesma página.

Se o seu app usa um bundler (React, Next.js, Vue, Svelte), você pode instalar o mesmo widget pelo npm e montá-lo no seu próprio código: npm install @vatio-ai/widget e depois mountVatioWidget({ workspace, token }), que devolve identify e unmount. As opções são as mesmas dos atributos data-*, em camelCase; veja From your app’s code. O widget é open source (MIT) em github.com/vatio-ai/widget.

Na web, cada resposta é uma mensagem completa que o widget exibe de forma progressiva, em Markdown, então listas, negritos e links aparecem como deveriam. O WhatsApp e o Instagram recebem as respostas do mesmo agente como mensagens de texto simples, no ritmo de quem digita. O agente só envia URLs que recebeu, e quando um pedido parece resolvido, o widget pergunta uma vez ao visitante como o agente ajudou; a avaliação aparece no inbox.

#Com a cara da sua marca

No inbox, abra Canais → Widget web: ali ficam o logo, que é o avatar do agente no widget e na página de chat; a cor de destaque; Sobre, o texto que o visitante vê quando o widget abre, antes de alguém escrever; o título, a saudação, até quatro sugestões, a posição, o esquema de cores, o raio dos cantos, a fonte, o idioma e mais cores.

O nome e a Descrição do negócio, que vão no prompt do agente em volta das instruções, não ficam ali: quem toca o negócio os define na página Negócio do inbox. É assim que o agente sabe o que é o negócio.

São configurações do workspace, não parte de um deployment: ao salvar, elas valem na hora para todos os ambientes, sem push nem publicação. Um bloco widget: ou business: em um vatio.yml antigo é ignorado com um aviso.

Uma página pode sobrescrever qualquer valor do widget na própria tag; eles são resolvidos a partir da página, depois do workspace e depois do padrão da plataforma. Nas páginas de assinatura, por exemplo:

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="cafe-serra-alta"
        data-token="vatpub_REPLACE_ME"
        data-greeting="Dúvidas sobre a sua assinatura? Pode perguntar."
        data-suggestions="Quando chega minha próxima entrega?|Qual café vem este mês?|Como preparo no coador?"
        data-accent="#8A3B12"
        data-position="left"
        data-locale="pt"></script>

Os atributos são data-accent e data-accent-ink, data-surface, data-ink, data-muted e data-line (todos #RRGGBB), data-scheme (auto, light ou dark), data-position (right ou left), data-reply-style (stream, ou paced para mensagens curtas com indicador de digitação, como no WhatsApp), data-font (inherit usa a fonte do seu site), data-radius, data-title, data-greeting, data-suggestions (separadas por |, até quatro), data-about e data-locale (en, es ou pt). O data-locale define os textos da interface, cujo padrão é inglês; o agente responde no idioma do visitante de qualquer jeito.

#Reconheça os clientes logados

Para dizer ao agente quem está conversando, seu backend assina um JWT e a Vatio o verifica. A Vatio guarda só a sua chave pública, então consegue conferir um token, mas nunca emitir um.

vatio auth --new-key

O identity.pub fica no workspace e o vatio.yml o aponta em auth. O identity.pem vai para o seu backend como segredo, nunca para vatio secrets set. Seu backend assina com RS256, com sub (o id do seu usuário), aud (o slug do seu workspace) e um exp curto; name e email são opcionais:

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

Coloque o token na tag só para os visitantes logados:

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="cafe-serra-alta"
        data-token="vatpub_REPLACE_ME"
        data-visitor-token="JWT_ASSINADO"></script>

Visitantes sem login não recebem token, e o agente os atende com as tools públicas. Quando alguém faz login sem recarregar a página, chame window.VatioWidget.identify(novoToken); null faz logout. A conversa sobrevive ao login: uma pergunta feita como anônimo continua, agora com um nome, então o agente pode respondê-la sem que o cliente precise digitar de novo. Um token com outro sub, ou o logout, começa uma conversa nova, então em um dispositivo compartilhado um cliente nunca vê o chat de outro. Gere um token novo a cada carregamento de página para a conversa sobreviver ao primeiro exp.

Com um visitante verificado, as tools marcadas access: private rodam. tools/minha_assinatura.yml, com o endereço da API guardado com vatio secrets set SERRA_API:

description: A assinatura do cliente logado e a próxima entrega.
when_to_use: Um cliente logado pergunta sobre a própria assinatura, a próxima caixa ou a data de entrega.
access: private
request:
  method: GET
  base_url: "$env.SERRA_API"
  path: /me/assinatura
  headers:
    Authorization: "Bearer $auth.token"
respond:
  data:
    assinatura: "$.assinatura"

agent:
  instructions: |
    ...
    Dúvidas sobre a assinatura: chame minha_assinatura. Se o visitante
    não estiver logado, envie o link entrar e responda quando ele voltar.
  tools: [minha_assinatura, knowledge_lookup]
  links:
    entrar: https://cafe-serra-alta.example/entrar
auth:
  public_key: identity.pub

Seu endpoint verifica o mesmo JWT com a chave pública e lê a assinatura do sub dele. Uma tool privada nunca recebe o id do usuário como parâmetro, e o deploy falha se receber: quem preenche os parâmetros é o modelo, e ele pode ser convencido a colocar o de outra pessoa. Um token recusado deixa o visitante como anônimo em vez de dar erro. Conectar seu backend aprofunda.

#Teste as mudanças antes no preview

O preview é a próxima versão do agente, com suas mudanças de conhecimento, seus chats e seus tokens publicáveis. Depois de vatio push, o vatio env imprime o token, o snippet do widget e o link de teste do preview. vatio tokens create --env preview --origin https://staging.cafe-serra-alta.example cria um token para o seu site de staging que fala com o preview; para trabalhar localmente, use --origin http://localhost:3000.

A aparência é a exceção: as configurações de Canais → Widget web valem para o workspace inteiro e se aplicam em todo lugar assim que você salva. Para testar uma aparência nova só no staging, use atributos data-* ali.

#Sua própria interface com o SDK de navegador

Quando o chat faz parte do seu produto, e não é uma bolha no canto, use o SDK de navegador com o mesmo token e as mesmas origens:

npm install @vatio-ai/sdk

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

const chat = await Vatio.chat({ workspace: "cafe-serra-alta", token: "vatpub_REPLACE_ME" });
chat.on("message", (message) => render(message)); // deduplique por message.id
chat.on("typing", (typing) => showTyping(typing));
for (const message of await chat.history()) render(message);
await chat.send("Quando chega minha próxima entrega?");

O visitorToken recebe o mesmo JWT assinado que o data-visitor-token. O replyStyle é stream por padrão, uma resposta completa para exibir de forma progressiva, e paced entrega mensagens curtas com indicador de digitação. O chat.send aceita até quatro arquivos: imagens, PDFs, texto ou áudio. A referência do SDK lista cada método e opção.

#Acompanhe pelo inbox

Cada conversa, do widget ou do SDK, aparece no inbox com as chamadas de tools. Adicione um objeto metadata ao token de visitante, com um link profile para o seu painel de administração e alguns badges como o plano do cliente, e o inbox mostra isso no cabeçalho da conversa, para quem responde saber com quem está falando. Os supervisores assumem uma conversa respondendo, e marcam as respostas erradas com o que deveria ter acontecido; seu coding agent corrige a causa a partir dessas notas, como explica Melhorar seu agente.

Atualizado: 11 de outubro de 2026