> Coloque um chat com IA no seu site com uma tag script: um token publicável restrito ao seu domínio, a cara da sua marca e clientes logados reconhecidos. # 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](/pt/guias/construir-um-agente-de-ia) leva você até lá; depois: ```bash 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 ```bash 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 ```html ``` Coloque antes do `` 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](https://vatio.ai/docs/channels/widget#from-your-app-s-code). O widget é open source (MIT) em [github.com/vatio-ai/widget](https://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**](https://vatio.ai/docs/channels/inbox#business) 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: ```html ``` 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. ```bash 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: ```js // 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: ```html ``` 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`: ```yaml 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" ``` ```yaml 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](/pt/guias/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: ```sh npm install @vatio-ai/sdk ``` ```js 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](https://vatio.ai/docs/sdk/reference) 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](/pt/guias/melhorar-seu-agente-de-ia). ## Perguntas frequentes ### Como coloco um widget de chat com IA no meu site? Publique seu agente, crie com vatio tokens create um token publicável que permita a origem do seu site e cole uma tag script com data-workspace e data-token antes do fechamento do body. A aparência do widget é configurada em Canais → Widget web, no inbox da Vatio, e o nome e a descrição do negócio, na página Negócio do inbox. ### É seguro colocar o token do widget no HTML da minha página? Sim, os tokens publicáveis vatpub_ foram feitos para o código da página. Cada um só funciona a partir das origens exatas listadas nele, além das páginas da própria Vatio e de app builders como o Lovable, e não consegue fazer deploy nem abrir o inbox. Nunca coloque um token de developer vat_ em um navegador. ### O chat com IA consegue reconhecer os clientes logados no meu site? Sim. Seu backend assina um JWT RS256 de curta duração dizendo quem é o visitante e o coloca como data-visitor-token na tag script. A Vatio o verifica com a sua chave pública, e as tools marcadas access: private passam a rodar para esse cliente. Uma conversa começada antes do login continua. ### Posso mudar as cores e os textos do widget em uma página específica? Sim. Os valores compartilhados ficam em Canais → Widget web, no inbox, e valem para todos os ambientes assim que você salva. Qualquer página pode sobrescrevê-los com atributos na própria tag script, como data-accent, data-greeting ou data-suggestions. ### Preciso de um site para oferecer o chat com IA? Para o widget, sim: ele é um script tag no seu próprio site. Sem site, o mesmo agente ainda pode atender seus clientes no WhatsApp ou no Instagram, e você testa ele na página Testar do inbox antes de qualquer outra pessoa ver. ### Posso construir minha própria interface de chat em vez de usar o widget? Sim. O SDK de navegador, @vatio-ai/sdk no npm, entrega a conversa, o histórico e os eventos de digitação e de status com o mesmo token publicável, e você desenha a interface.