> Coloque um agente de IA no WhatsApp: teste em um número compartilhado sem conta da Meta, conecte seu número comercial e continue usando o WhatsApp Business. # Um agente de IA no WhatsApp Para colocar um agente de IA no WhatsApp com a Vatio, você o descreve em um arquivo `vatio.yml`, faz push e conversa com ele pelo seu próprio celular em um número de preview compartilhado, sem conta da Meta. Quando ele estiver respondendo bem, você conecta seu número comercial pelo cadastro da Meta no inbox da Vatio e ativa **Em produção**. O agente responde ao que as pessoas mandam, inclusive áudios, fotos e PDFs, e qualquer pessoa da sua equipe pode assumir uma conversa pelo inbox ou pelo app do WhatsApp Business. Este guia vai de uma pasta vazia até o seu próprio número, e mostra o que o agente pode e não pode fazer quando chega lá. ## Comece com um agente mínimo Você precisa do Node.js 20 ou mais recente. O `vatio init` não pede conta; o primeiro `vatio push` abre o seu navegador para entrar com e-mail, Google ou GitHub, e isso cria a sua. ```bash npx @vatio-ai/skills npm install -g @vatio-ai/cli@latest vatio init bicicletaria-vila-madalena ``` Troque o `vatio.yml` inicial por algo pequeno assim: ```yaml workspace: bicicletaria-vila-madalena agent: name: Bicicletaria Vila Madalena personality: Simpático e breve. Mensagens curtas, do jeito que as pessoas escrevem no WhatsApp. instructions: | Você atende os clientes da Bicicletaria Vila Madalena, uma loja e oficina de bicicletas em São Paulo. Abrimos de segunda a sexta, das 9:00 às 18:00, e aos sábados, das 10:00 às 14:00. Uma revisão padrão leva dois dias úteis. Se não souber algo, diga isso e ofereça passar a pergunta para a equipe. Nunca invente um preço, um estoque ou uma data de retirada. handoff: when: - uma reclamação sobre um conserto ou uma cobrança - o cliente quer um orçamento de bicicleta montada sob medida ``` ```bash vatio push vatio chat "oi, vocês abrem no sábado?" vatio chat "o câmbio que vocês consertaram semana passada está pior do que antes" vatio chat show ``` A segunda mensagem é uma reclamação, então deveria ser transferida; o `chat show` mostra se foi, com cada chamada de tool. Quando as informações não couberem mais nas instruções, preços e serviços vão para uma base de conhecimento; [Construir um agente de IA](/pt/guias/construir-um-agente-de-ia) cobre esse passo. O `vatio chat` responde assim que a resposta fica pronta, então ele testa o que o agente diz, não como o WhatsApp entrega. Para isso você precisa de um celular. ## Teste no número de preview compartilhado O número de preview é da Vatio, então você testa no WhatsApp de verdade antes de mexer com a Meta. Tudo acontece na aba **WhatsApp** da página **Testar** do inbox: 1. Abra **Testar → WhatsApp**. Um telefone que você já verificou em outro workspace seu aparece em **Você já verificou estes números**, e **Usar em preview** o conecta com um clique, sem código. 2. Se não, em **Conecte seu celular**, escaneie o QR code com o seu celular. O WhatsApp abre no número de preview compartilhado com uma mensagem já escrita, que leva um código de 6 caracteres: envie. Sem câmera por perto, envie você mesmo esse código para o número de preview; a página mostra os dois. É essa mensagem que prova que o celular é seu. A Vatio responde na hora com "Verificamos seu celular ✅", e a página se atualiza sozinha. 3. Escreva para o agente desse celular e leia a conversa em **Conversas**, no mesmo inbox. Embaixo de cada resposta do agente fica o que ele fez: as tools que chamou e o que elas devolveram, e o conhecimento que leu. É o mesmo inbox de onde sua equipe responde quando o agente já está no ar. Você pode registrar até cinco telefones de teste por workspace, então o dono da oficina e mais alguém da equipe também podem testar: **Adicionar outro número**, abaixo da lista, mostra um QR code novo. Um código vale por 15 minutos e funciona uma vez, e o QR code da página se renova sozinho. Um telefone verificado aponta para um workspace por vez; enviar dele o código de outro workspace, ou escolher **Usar em …** em outro workspace, faz ele passar para lá. Cada telefone de teste chega a `preview`, então uma mudança se testa no WhatsApp antes de publicar. Ele nunca chega a live: live é o seu próprio número. Agora escreva como os clientes escrevem: três mensagens curtas seguidas, um áudio, uma foto de uma roda empenada. Esse é o teste que o `vatio chat` não consegue fazer. ## Conecte seu próprio número comercial Quando o preview estiver certo, publique: ```bash vatio publish ``` Depois, no inbox, abra **Canais → WhatsApp** no live, escolha **Conectar WhatsApp** e conclua o cadastro da Meta na janela que abrir. Publicar pelo inbox, com **Publicar no live** na página **Testar**, passa pela mesma verificação do `vatio publish`. Um número recém-conectado fica em pausa. Ele continua funcionando exatamente como antes até você ativar **Em produção**, que é o que faz o seu deployment live começar a responder. Isso dá tempo para conferir a conexão: o mesmo modal mostra se a Meta está entregando as mensagens do número, e **Verificar** roda essa checagem de novo. Desativar **Em produção** pausa as respostas sem desconectar nada. Para trocar de número, exclua a integração primeiro e conecte o novo. Se o número é do seu cliente, você não precisa do acesso do cliente ao Facebook. Em **O número é do seu cliente?**, no mesmo modal, convide por e-mail quem tem o número. A pessoa entra como supervisor, conecta o número em uma página própria e você recebe um e-mail quando ele estiver conectado. Enquanto isso, o modal mostra em que etapa está cada pessoa convidada, de abrir o convite até o cadastro na Meta, então você sabe se espera ou ajuda. Ativar **Em produção** continua com você. A partir daí, `vatio publish` muda o que o número responde, e `vatio rollback` restaura a versão anterior. ## Continue usando o app do WhatsApp Business Você não precisa abrir mão do app no celular da oficina. A conexão permite mantê-lo, e os dois funcionam juntos: - **Responder pelo app é assumir a conversa.** A resposta chega à Vatio e pausa o agente naquela conversa, igual a uma resposta pelo inbox. - **Devolva pelo inbox** quando o agente tiver que voltar, com **Devolver ao agente** na conversa. Ou deixe: a intervenção expira 8 horas depois da última mensagem do cliente, e cada resposta humana reinicia esse relógio. - **O agente também pode pedir uma pessoa.** O bloco `handoff` acima permite que ele passe adiante as reclamações, e um cliente que pede para falar com uma pessoa com essas palavras sempre é transferido. Dentro do horário de atendimento, que quem toca o negócio define na página **Negócio** do inbox, o agente fica em silêncio; fora dele, continua ajudando. Uma transferência que ninguém assume em uma hora volta para o agente. A Vatio ainda não notifica ninguém sobre uma transferência. A conversa aparece como aguardando no inbox, então alguém precisa estar de olho. ## Como uma conversa de WhatsApp se comporta - **Uma conversa dura até oito horas de silêncio.** A Vatio continua a última conversa até que a última mensagem do cliente tenha mais de oito horas; a mensagem seguinte começa um chat novo. - **Fragmentos viram uma pergunta só.** A Vatio agrupa as mensagens que chegam juntas e espera um momento de silêncio antes de responder, e também espera um áudio ou uma foto que ainda está sendo processado. [Conversas fluidas](/pt/guias/conversas-fluidas) explica por que isso importa. - **Uma edição reescreve a mensagem.** Quando o cliente edita uma mensagem dentro dos 15 minutos que o WhatsApp permite, ou você edita uma resposta pelo app do WhatsApp Business, o inbox mostra o texto novo marcado como editado e o agente passa a ler esse texto. Uma edição não é uma mensagem nova: o agente não responde a ela, e ela não assume a conversa. - **Uma mensagem apagada some.** Quando o cliente apaga uma mensagem para todos, dentro dos dois dias que o WhatsApp permite, ou você apaga uma pelo app, ela some do inbox e do que o agente lê. - **Áudios, imagens e PDFs são lidos.** O áudio é transcrito, e imagens e PDFs compatíveis de até 8 MB por arquivo chegam ao agente. O que não é compatível ou é maior fica disponível para os supervisores, e o agente recebe um aviso de que não consegue ler. - **As respostas são texto, no ritmo de quem digita.** No WhatsApp uma resposta chega como mensagens curtas de texto simples, com pausas e indicador de digitação, e não como um bloco longo. O agente não envia imagens, arquivos nem áudios. - **Os links passam por uma lista permitida.** O agente só envia URLs que recebeu, em `links`, nas instruções ou no resultado de uma tool. Qualquer outra URL é removida da resposta. ## Com quem o agente está falando Para o seu backend, um contato do WhatsApp começa anônimo: não há uma página onde ele possa assinar um token dizendo quem é a pessoa. As tools públicas rodam para qualquer pessoa. Uma tool marcada `access: private`, que lê os dados de uma pessoa por trás de um login, exige que ela entre na conta, então a Vatio a leva ao seu site para isso. Adicione a sua página de login em `auth:`, ao lado da chave pública que verifica os seus tokens: ```yaml auth: public_key: identity.pub sign_in_url: https://bicicletaria-vila-madalena.example/vatio/entrar ``` Quando uma tool privada roda para um contato que não entrou na conta, a Vatio envia para ele um botão **Entrar**. Ele abre a sua página com um `code` de uso único; a sua página faz o login do jeito que o seu site já faz e redireciona para `https://vatio.ai/connect/?token=`, com o mesmo JWT que você coloca no widget web. A Vatio pede para a pessoa confirmar o número do WhatsApp, um passo que ela pula quando o claim `phone_number` do token bate com ele, e a conversa continua de onde parou: o agente roda a tool que estava esperando. O token fica com o contato até o `exp` dele. Com a gem [vatio-sdk](https://vatio.ai/docs/sdk/ruby), a página é um único redirect para `Vatio::Identity.sign_in_redirect_url`; a [documentação](https://vatio.ai/docs/authentication/sessions#on-whatsapp) tem os detalhes. Nem toda consulta precisa de uma conta. Para clientes que nunca se cadastraram, o padrão é uma tool pública que pede uma referência mais um segundo dado, e seu backend confere se eles batem. Primeiro guarde o endereço e a chave da API como secrets: ```bash vatio secrets set OFICINA_API https://api.bicicletaria-vila-madalena.example vatio secrets set OFICINA_API_KEY sk_live_... ``` `tools/status_conserto.yml`: ```yaml description: Consulta o status de um conserto. when_to_use: O cliente pergunta se a bicicleta está pronta ou como está o conserto. parameters: type: object properties: ordem: { type: string, description: "Número da ordem de serviço, por exemplo OS-2041" } final_telefone: { type: string, description: "Últimos quatro dígitos do telefone da ordem" } required: [ordem, final_telefone] access: public request: method: GET base_url: "$env.OFICINA_API" path: /consertos/status requires: [params.ordem, params.final_telefone] headers: Authorization: "Bearer $env.OFICINA_API_KEY" query: ordem: "$params.ordem" final_telefone: "$params.final_telefone" respond: data: conserto: "$.conserto" ``` Quem preenche os parâmetros de uma tool é o modelo, então a checagem de que a ordem corresponde a esses dígitos fica no seu backend, que responde `404` quando eles não batem. Nunca deixe isso para o prompt. Às vezes uma tool precisa do telefone do próprio cliente, por exemplo para agendar um retorno por ligação. No WhatsApp o agente já tem o número: `pedir_retorno` é um `POST` cujo body leva `$contact.phone_number`, com `contact.phone_number` em `requires` e sem um parâmetro de telefone para o modelo preencher. Se um cliente esconde o número atrás de um nome de usuário do WhatsApp, a Vatio envia para ele um botão para compartilhá-lo com um toque na primeira vez que a tool roda; o número chega com a próxima mensagem dele, e a tool pode rodar então. Não há nada para ativar nem nada que o agente precise perguntar. O número diz como falar com o cliente, não quem ele é, então `status_conserto` mantém o segundo dado: ```yaml agent: instructions: | ... Status de conserto: peça o número da ordem e os últimos quatro dígitos do telefone da ordem, e chame status_conserto. Retornos: chame pedir_retorno. Ela já tem o número do cliente. tools: [status_conserto, pedir_retorno] ``` [Conectar seu backend](/pt/guias/conectar-seu-backend) aprofunda as tools e os visitantes autenticados. ## O que a Vatio não faz no WhatsApp O agente nunca decide por conta própria escrever primeiro. Quando o seu negócio precisa, seja um lembrete, um aviso de pedido ou cada pessoa de uma lista de campanha, o seu backend pede pela [Messages API](https://vatio.ai/docs/api/messages), uma requisição por contato e até 60 por minuto por chave: dentro de 24 horas desde a última mensagem da pessoa ela envia o seu texto ou faz o agente escrever a partir de um brief, e depois disso o WhatsApp só entrega um modelo que a Meta aprovou, que o inbox lista em **Mensagens enviadas → Modelos**. O agente cuida das respostas sabendo do que se tratava a mensagem, e quem pediu para não receber mensagens e as conversas que uma pessoa assumiu são respeitados. O que a Vatio não tem é um painel de campanhas para subir listas, segmentá-las ou agendar envios: essa lógica fica no seu backend. Também não há chamadas de voz, e o agente nunca gera imagens nem arquivos. ## O Instagram é o mesmo agente As DMs do Instagram funcionam do mesmo jeito: uma conta de preview compartilhada com até cinco contas de teste, e depois a sua própria conta profissional conectada em **Canais** no inbox. É o mesmo agente, com o mesmo inbox e o mesmo login, só que a confirmação mostra o @ em vez de um número, e aparece sempre. Veja a [documentação do Instagram](https://vatio.ai/docs/channels/instagram), e a [do WhatsApp](https://vatio.ai/docs/channels/whatsapp) para cada opção da página Canais. ## Perguntas frequentes ### Preciso de uma conta da Meta para testar um agente de IA no WhatsApp? Não. A Vatio tem um número de preview compartilhado: você adiciona até cinco telefones como números de teste na página Testar do inbox, conecta cada um escaneando um QR code e enviando a mensagem que ele deixa escrita no WhatsApp, e conversa com o agente a partir deles. O cadastro da Meta só aparece quando você conecta seu próprio número para o tráfego real. ### Posso continuar usando o app do WhatsApp Business depois de conectar um agente de IA? Sim. A conexão permite manter o app no seu celular. Uma resposta enviada por ele assume aquela conversa e pausa o agente ali; devolva pelo inbox, ou a intervenção expira 8 horas depois da última mensagem do cliente. ### O agente pode enviar campanhas ou lembretes pelo WhatsApp? Sim, a partir do seu backend. Ele chama a Messages API da Vatio uma vez por contato, para um lembrete, um aviso ou cada pessoa de uma lista de campanha, até 60 mensagens por minuto por chave: dentro de 24 horas desde a última mensagem da pessoa ela envia o seu texto ou faz o agente escrever a partir de um brief, e depois disso o WhatsApp só entrega um modelo que a Meta aprovou, listado no inbox em Mensagens enviadas → Modelos. Quem pediu para não receber mensagens e as conversas que uma pessoa assumiu são respeitados, e o agente atende as respostas. O que a Vatio não tem é um painel de campanhas: o seu backend decide para quem e quando, e o agente nunca decide por conta própria escrever primeiro. ### O agente entende áudios e fotos no WhatsApp? Sim. Os áudios são transcritos, e imagens e PDFs compatíveis de até 8 MB por arquivo chegam ao agente. As respostas dele são só texto: ele não envia imagens, arquivos nem áudios. ### O agente pode consultar a conta de um cliente pelo WhatsApp? Sim, depois que o cliente entra na conta. As tools públicas rodam para qualquer pessoa, e uma tool marcada access: private roda para um contato logado: com um sign_in_url no vatio.yml, a Vatio envia um botão Entrar que abre o seu site, e a conversa continua quando ele volta. Para clientes sem conta, o padrão é uma tool pública que pede um número de referência mais um segundo dado, e seu backend confere se eles batem. ### Quanto tempo dura uma conversa de WhatsApp com o agente? A Vatio continua a mesma conversa até que a última mensagem do cliente tenha mais de oito horas. A mensagem seguinte começa um chat novo.