> Responda as DMs do Instagram com um agente de IA: teste em uma conta compartilhada, conecte sua conta profissional e atenda prints, áudios e intervenções. # 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. ```bash 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: ```yaml 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: ```bash vatio secrets set LOJA_API https://api.casa-ipe.example vatio secrets set LOJA_API_KEY sk_live_... ``` `tools/buscar_produtos.yml`: ```yaml 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: ```bash 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 ``` ```markdown # 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 ```bash 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: ```bash 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](/pt/guias/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](https://vatio.ai/docs/authentication/sessions#on-whatsapp)). [Um chat com IA para o seu site](/pt/guias/chat-com-ia-para-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](/pt/guias/melhorar-seu-agente-de-ia). ## 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](/pt/guias/agente-ia-para-whatsapp). Cada opção da página Canais está na [documentação do Instagram](https://vatio.ai/docs/channels/instagram). ## Perguntas frequentes ### Um agente de IA pode responder as DMs do Instagram automaticamente? Sim. Você conecta sua conta profissional do Instagram pelo consentimento da Meta no inbox da Vatio, e o seu agente em live responde cada DM enviada para essa conta. É o mesmo agente que responde no WhatsApp e no seu site, descrito em um único vatio.yml. ### Preciso conectar minha conta do Instagram para testar o agente? Não. A Vatio tem uma conta de preview compartilhada. Você escaneia um QR code na página Testar do inbox, envia da sua própria conta o código que ele mostra e conversa com o seu agente por lá. Um workspace pode ter até cinco contas de teste, e elas nunca chegam a live. ### O agente lê os prints e os áudios que chegam pelo Instagram? Sim. Imagens compatíveis, como o print de um post, chegam ao agente, e os áudios são transcritos, até 8 MB por arquivo. Um vídeo, como um reel compartilhado, não é algo que ele consiga assistir. As respostas dele são só texto. ### O agente pode mandar a primeira mensagem ou fazer campanhas no Instagram? Não. O Instagram só permite que uma empresa responda a quem escreveu para ela, então no Instagram a Vatio só responde às mensagens que chegam: não há DMs ativas, transmissões nem follow-ups. Os lembretes e as campanhas que o seu backend envia pela Messages API da Vatio saem só pelo WhatsApp. O agente retoma sempre que alguém escreve. ### Minha equipe pode assumir uma conversa do Instagram? Sim. Os supervisores veem todas as conversas no inbox da Vatio e assumem uma respondendo por lá, o que pausa o agente naquele chat. Eles devolvem a conversa pelo inbox, ou a intervenção expira 8 horas depois da última mensagem do cliente. ### O agente pode consultar os pedidos de um cliente pelo Instagram? 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 é pedir o número do pedido mais um segundo dado, e seu backend confere se eles batem.