#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.

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:

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

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 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:

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 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:

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/<code>?token=<jwt>, 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, a página é um único redirect para Vatio::Identity.sign_in_redirect_url; a documentação 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:

vatio secrets set OFICINA_API https://api.bicicletaria-vila-madalena.example
vatio secrets set OFICINA_API_KEY sk_live_...

tools/status_conserto.yml:

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:

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 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, 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, e a do WhatsApp para cada opção da página Canais.

Atualizado: 11 de outubro de 2026