#Um agente de IA no Instagram

Para responder as DMs do Instagram com um agente de IA na Vatio, você descreve o agente em um arquivo vatio.yml, faz push e conversa com ele pela sua própria conta do Instagram por meio de uma conta de preview compartilhada, antes de conectar qualquer coisa. Quando ele estiver respondendo bem, você publica e conecta sua conta profissional pelo consentimento da Meta no inbox da Vatio; a partir daí, o seu agente em live responde cada DM enviada para essa conta. É o mesmo agente que responde no WhatsApp e no seu site, ele lê os prints e os áudios que as pessoas mandam, e qualquer pessoa da sua equipe pode assumir uma conversa pelo inbox.

Este guia cobre as conversas que o Instagram traz, como testá-las e como conectar a conta.

#Um agente, todos os canais

Não existe um agente separado para o Instagram. Um workspace roda um único agente, e o canal só muda como as respostas são entregues, então um agente que já está no WhatsApp ou no seu site está pronto para o Instagram. Se você ainda não tem um, 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 casa-ipe

Um agente para uma loja de móveis e decoração que vende principalmente pelo Instagram:

workspace: casa-ipe
agent:
  name: Casa Ipê
  personality: Simpático e rápido. Mensagens curtas, do jeito que as pessoas escrevem na DM.
  instructions: |
    Você atende os clientes da Casa Ipê, uma loja de móveis e decoração
    que vende online e no showroom em Pinheiros, São Paulo.

    Cada produto tem um código como CI-0412, na imagem e na legenda de
    cada post. Quando alguém perguntar por um produto, procure o código na
    mensagem ou no print e chame buscar_produtos com ele. Sem código,
    busque pelo que a pessoa descreve ou pelo que a imagem mostra, e
    pergunte qual é se houver vários. Informe o preço, se tem estoque e o
    link do produto que a tool devolveu.

    Se mandarem algo que você não consegue ver, como um vídeo, peça o
    código do produto ou um print. Para frete, trocas e o showroom,
    consulte primeiro o knowledge_lookup.

    Nunca invente um preço, um estoque ou um prazo de entrega.
  tools: [buscar_produtos, knowledge_lookup]
  knowledge: [loja]
  handoff:
    when:
      - uma entrega que chegou avariada ou uma reclamação
      - um móvel sob medida ou um desconto para empresas

#O que as pessoas mandam pelo Instagram

As DMs do Instagram são curtas: “preço?”, “info”, “ainda tem?”, “vocês entregam em Curitiba?”, muitas vezes com um print, porque a pessoa escreveu a partir do feed. Uma conversa típica:

Cliente: preço? (print de um post)

Agente: É a mesa lateral Jequitibá, CI-0412: R$ 1.290, e tem em estoque. https://casa-ipe.example/p/ci-0412

Cliente: vcs entregam em curitiba

Agente: Entregamos. O frete de móveis para fora de São Paulo é R$ 149 por pedido e leva de 5 a 7 dias úteis. Se preferir, você também pode retirar no showroom sem custo.

Por trás dessas respostas, o agente leu “CI-0412” no print, chamou buscar_produtos com esse código e consultou o frete na base de conhecimento. O link veio da tool, e é isso que permite ao agente enviá-lo. Três hábitos fazem isso funcionar:

• Coloque um código em cada post, na imagem e na legenda. O agente lê imagens, então um print com um código no canto vira uma busca por código, e não um palpite sobre qual mesa de madeira era.
• Responda antes de perguntar. “preço?” merece um preço; as perguntas vêm depois.
• Preço e estoque vêm de uma tool, e o que muda pouco, do conhecimento.

Guarde o endereço e a chave da API como secrets:

vatio secrets set LOJA_API https://api.casa-ipe.example
vatio secrets set LOJA_API_KEY sk_live_...

tools/buscar_produtos.yml:

description: Busca no catálogo por código do produto ou por descrição.
when_to_use: O cliente pergunta por um produto, o preço ou o estoque, pelo código, por uma descrição ou com um print.
parameters:
  type: object
  properties:
    codigo: { type: string, description: "Código do produto, por exemplo CI-0412" }
    consulta: { type: string, description: "O que o cliente descreve ou a imagem mostra, por exemplo mesa lateral de madeira" }
access: public
request:
  method: GET
  base_url: "$env.LOJA_API"
  path: /produtos/busca
  headers:
    Authorization: "Bearer $env.LOJA_API_KEY"
  query:
    codigo: "$params.codigo"
    q: "$params.consulta"
respond:
  data:
    produtos: "$.produtos"
  message:
    when_empty: Nenhum produto corresponde a esse código ou descrição.
    default: "Encontrei {{count}} produtos."

Faça o endpoint devolver o nome, o preço, o estoque e o link de cada produto, e nada que você não colocaria em um post: o que uma tool devolve, o modelo pode repetir.

Frete, trocas e o showroom vão para uma base de conhecimento, uma entrada por assunto:

vatio kb create loja
vatio kb write loja frete frete.md
vatio kb write loja trocas-e-devolucoes trocas-e-devolucoes.md
vatio kb write loja showroom showroom.md

# Frete

## Valores e prazos
Itens pequenos pagam R$ 29 e móveis R$ 149 por pedido fora de São Paulo.
Na capital, a entrega leva de 2 a 4 dias úteis; no resto do país, de 5 a 7.
A retirada no showroom é gratuita. Aceitamos Pix e cartão.

A Vatio não lê sites, e uma legenda que o agente nunca recebeu não é algo que ele saiba: coloque o que importa em uma entrada ou por trás da tool.

#Teste na conta de preview compartilhada

vatio push
vatio chat "quanto custa a CI-0412?"
vatio chat "a luminária que eu comprei chegou quebrada"
vatio chat show

A segunda mensagem é uma entrega avariada, então deveria ser transferida; o chat show mostra se foi. O vatio chat manda texto e responde na hora, então os prints e o ritmo das respostas se testam no próprio Instagram, na conta de preview da Vatio. Tudo acontece na aba Instagram da página Testar do inbox:

1. Abra Testar → Instagram. Uma conta que você já verificou em outro workspace aparece em Você já verificou estas contas, e Usar em preview conecta ela com um clique, sem código.
2. Se não, em Conecte sua conta, escaneie o QR code com seu celular: abre a DM com a conta de preview da Vatio. Da conta com a qual você vai testar, envie o código que a página mostra; no computador, mande uma DM para a conta que a página indica e envie o código. Essa DM prova que a conta é sua: a Vatio responde na hora com “Verificamos sua conta ✅”, e a página se atualiza sozinha.
3. Continue conversando com o agente nessa DM e leia a conversa em Conversas, no mesmo inbox.

O Instagram não deixa a Vatio escrever primeiro, então a sua conta envia o código em vez de recebê-lo. Um código dura 15 minutos e vale uma vez, e o da página se renova sozinho. Uma conta encaminha para um só workspace por vez; enviar dela o código de outro workspace, ou escolher Usar em … em outro workspace, move ela para lá.

Um workspace pode ter até cinco contas de teste: Adicionar outra conta, abaixo da lista, mostra um código novo. Cada uma chega a preview, então uma mudança se testa no Instagram antes de publicar. Ela nunca chega a live: live é a sua própria conta.

Depois escreva como seus seguidores escrevem: um print com “preço?”, três mensagens curtas seguidas, um áudio perguntando sobre o frete.

#Conecte sua conta profissional

Quando o preview estiver certo, publique:

vatio publish

Depois, no inbox, abra Canais → Instagram no live, escolha Conectar Instagram e conclua o consentimento 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. Precisa ser uma conta profissional, e o consentimento pede para ler o perfil e gerenciar as mensagens.

Não há um botão para ativar depois: assim que a conta é conectada, o seu deployment live responde as DMs dela, e por isso você publica antes. O mesmo modal mostra se a conta está recebendo DMs (Em produção — respondendo DMs quando está), e Verificar roda essa checagem de novo.

Um workspace conecta uma conta, e uma conta se conecta a um workspace; para trocar de conta, exclua a integração primeiro. A Vatio renova o access token automaticamente, e se ele expirar, escolha Reconectar com a mesma conta.

A partir daí, vatio publish muda o que a conta responde, e vatio rollback restaura a versão anterior.

#Como uma conversa do Instagram se comporta

• Uma conversa dura até oito horas de silêncio. Quando a última mensagem do cliente tem mais de oito horas, a seguinte começa um chat novo.
• Fragmentos viram uma pergunta só. A Vatio agrupa as mensagens que chegam juntas, espera um momento de silêncio e os arquivos que ainda estão sendo processados, e responde uma vez. Conversas fluidas explica por quê.
• Edições e mensagens desfeitas acompanham o cliente. Uma DM editada mostra o texto novo no inbox, marcada como editada, e o agente passa a ler esse texto; uma desfeita some dos dois. Nenhuma é uma mensagem nova, então o agente não responde a ela.
• Imagens, áudios e PDFs são lidos. Arquivos compatíveis de até 8 MB cada chegam ao agente, e o áudio é transcrito. O resto, como um vídeo ou um reel compartilhado, 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: mensagens curtas de texto simples com indicador de digitação. O agente não envia imagens nem arquivos, então a página do produto leva as fotos e o link é o que ele envia.
• 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.

#Com quem o agente está falando

Para o seu backend, um contato do Instagram começa anônimo: não há uma página onde ele possa assinar um token dizendo quem é a pessoa, então, até ele entrar na conta, só rodam tools públicas. Os pedidos ou a conta de um cliente ficam por trás de um login, em uma tool marcada access: private. Com sign_in_url em auth:, essa tool envia ao cliente um botão Entrar que abre o seu site; a sua página redireciona de volta com o mesmo token que você coloca no widget, a Vatio pede para ele confirmar o @ que está sendo conectado, e a conversa continua de onde parou (veja a documentação). Um chat com IA para o seu site mostra como assinar o token.

Uma DM também não traz número de telefone. No WhatsApp o agente já tem o número do cliente; no Instagram, só se o cliente digitar. Uma tool que precisa de um telefone ou e-mail, por exemplo para agendar uma visita ao showroom, recebe isso como parâmetro, e seu backend valida. Para consultar o pedido de quem não entrou na conta, peça o número do pedido mais um segundo dado, como o e-mail da compra, e deixe o seu backend conferir se eles batem. Quem preenche os parâmetros é o modelo, então essa checagem fica no código, nunca no prompt.

#Quando uma pessoa assume a conversa

Os supervisores que você convida em Equipe no inbox veem todas as conversas do Instagram no inbox, com cada chamada de tool ao lado da resposta que ela produziu.

• Responder pelo inbox é assumir a conversa. Isso pausa o agente naquele chat. Devolver ao agente libera a conversa, ou a intervenção expira 8 horas depois da última mensagem do cliente; cada resposta humana reinicia esse relógio.
• O agente também pode pedir uma pessoa. O bloco handoff acima transfere as reclamações e os móveis sob medida, e um cliente que pede para falar com uma pessoa sempre é transferido. Dentro do horário de atendimento, que quem toca a loja 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.
• Ninguém é notificado ainda. Uma conversa transferida aparece como aguardando no inbox, então alguém precisa estar de olho.

Quando uma resposta saiu errada, use Reportar esta resposta e escreva o que deveria ter acontecido. Seu coding agent corrige a causa a partir dessas notas; veja Melhorar seu agente.

#O que a Vatio não faz no Instagram

O agente só responde às DMs que recebe. A Vatio não envia DMs ativas, transmissões, campanhas nem follow-ups, e o Instagram só permite que uma empresa responda a quem escreveu primeiro. Ele trabalha nas mensagens diretas, não nos comentários dos seus posts. Também não há chamadas de voz, e o agente nunca gera imagens nem arquivos.

O WhatsApp funciona do mesmo jeito, com um número de preview compartilhado e o seu próprio número comercial; veja Um agente de IA no WhatsApp. Cada opção da página Canais está na documentação do Instagram.

Atualizado: 11 de outubro de 2026