Agente de IA no WhatsApp com Claude e Evolution API (guia 2026)

Resposta direta: um agente de IA no WhatsApp com Claude e Evolution API é um fluxo em que a Evolution recebe a mensagem do cliente e avisa o n8n por webhook (evento MESSAGES_UPSERT), o n8n junta o histórico daquela conversa guardado no Supabase, manda tudo para o Claude com um prompt de sistema que define quem o agente é, o que pode fazer e quando deve passar para uma pessoa, e devolve a resposta pelo endpoint sendText. Uma conversa de 20 trocas custa centavos de dólar em API. O que decide se funciona não é o modelo: é o prompt de sistema, a memória por contato e a regra de transferência para humano. A Evolution pode rodar num número comum (conexão por QR code, sem custo por mensagem, sujeita às regras de uso do WhatsApp) ou em cima da Cloud API oficial da Meta (número verificado; texto de resposta dentro da janela de atendimento não é cobrado). O número da WW Mídia roda nesse desenho desde 2026.

Este guia é para quem tem um número de WhatsApp que recebe mais mensagem do que a equipe consegue responder no mesmo dia e quer um agente que responda de verdade, com contexto, e não um menu de “digite 1”. Ele cobre a arquitetura, o passo a passo no n8n, o que vai no prompt de sistema, o custo por conversa, o que a evidência mostra e onde esses agentes quebram na prática.

O que “agente” significa aqui

Chatbot de menu segue um roteiro fixo: aperta 1, aperta 2, cai fora do roteiro e trava. Agente de IA lê a mensagem como ela veio (“oi, vcs fazem site? quanto fica mais ou menos?”), consulta o que sabe sobre a empresa e sobre aquele contato, responde no tom da marca e decide entre três caminhos: responder, pedir um dado que falta, ou transferir para uma pessoa. O modelo (Claude) faz a leitura e a redação. O resto, que é a maior parte do trabalho, é fluxo: receber, lembrar, decidir, enviar, registrar.

Três decisões antes de abrir o n8n

1. Em que número o agente vai rodar

A Evolution API é um servidor de código aberto que expõe o WhatsApp como API REST. Ela funciona de dois jeitos:

	Número comum (conexão por QR code)	Cloud API oficial da Meta (via Evolution)
Como conecta	Lê um QR code como o WhatsApp Web	Business Manager verificada, app no Facebook Developers, token permanente (passo a passo na doc)
Custo por mensagem	Zero	Resposta em texto a quem escreveu, dentro da janela de atendimento aberta, não é cobrada; a Meta cobra só mensagem de modelo (template) entregue, por categoria e país (tabela da Meta)
Risco	É um número comum: os termos do WhatsApp proíbem “bulk messaging, auto-messaging”; denúncias derrubam o número	Número verificado, selo, sem risco de bloqueio por automação quando segue a política
Serve para	Responder quem escreve para você (inbound), volume de PME, começar hoje	Operação que depende do número, volume alto, disparo ativo com opt-in

Regra que usamos na WW Mídia: agente responde quem escreveu primeiro. Isso é o que o próprio aplicativo WhatsApp Business faz com resposta automática, e é o uso que não gera denúncia. Disparo ativo para lista é outra conversa, exige opt-in (a Meta é literal sobre isso) e, se for para fazer, é na Cloud API.

2. O que o agente pode fazer sozinho

Lista fechada, escrita antes do prompt: responder sobre serviços e preços publicados, coletar nome, empresa e necessidade, marcar horário na agenda, mandar link de material. O que não está na lista o agente não faz, e diz que vai chamar alguém. Agente sem lista fechada inventa política de desconto às 2 da manhã.

3. Quando passa para humano

Três gatilhos que sempre transferem: o cliente pediu (“quero falar com uma pessoa”), o assunto está fora da lista (reclamação, cancelamento, negociação de preço), ou o agente não entendeu duas vezes seguidas. Transferir significa: avisar o cliente, parar de responder naquele contato, avisar a equipe com o resumo da conversa. Se o humano não assumir em X minutos, o agente avisa o cliente de novo com o prazo real.

Arquitetura em seis peças

Evolution API: uma instância por número. Webhook configurado pelo endpoint /webhook/instance com o evento MESSAGES_UPSERT (mensagem nova) e CONNECTION_UPDATE (caiu a conexão), conforme a doc de webhooks.
n8n: recebe o webhook, filtra (ignora mensagem enviada por você mesmo, ignora grupo, ignora status), espera alguns segundos para juntar mensagens picadas, monta o contexto, chama o Claude, envia a resposta, registra.
Supabase: duas tabelas. contatos (telefone, nome, empresa, estágio, humano_assumiu, última interação) e mensagens (contato, direção, texto, data). É a memória do agente; o Claude não lembra nada entre chamadas, o n8n é que entrega o histórico a cada vez.
Claude (via API): recebe prompt de sistema fixo mais as últimas N mensagens daquele contato mais a mensagem nova. Devolve texto ou, se você definir ferramentas, uma chamada de função (“agendar”, “transferir”, “buscar preço”).
Evolution sendText: POST /message/sendText/{instancia} com número e texto (referência). Antes, um setPresence de “digitando” por dois ou três segundos torna a conversa humana.
Handoff: uma coluna humano_assumiu no contato. Se está true, o fluxo nem chama o Claude. Um comando no próprio WhatsApp da equipe (“#eu”) liga a coluna; outro (“#bot”) devolve ao agente.

Passo a passo no n8n

1. Webhook de entrada

Nó Webhook (POST) recebendo o payload da Evolution. Primeira coisa: descartar fromMe = true (senão o agente responde a si mesmo em loop), descartar @g.us (grupos) e descartar eventos sem texto.

2. Identificar o contato do jeito certo

Detalhe que custa horas: a Evolution pode entregar o mesmo contato com dois identificadores, um terminado em @lid (quando a mensagem chega) e outro em @s.whatsapp.net (quando você envia). Se a chave da sua tabela for o JID cru, o histórico se parte em dois e o agente “esquece” a conversa. Normalize para o número puro antes de gravar.

3. Juntar mensagens picadas

Gente escreve “oi” / “tudo bem?” / “queria saber do plano” em três mensagens. Responder cada uma gera três respostas e a sensação de robô. Guarde a mensagem, espere de 5 a 8 segundos, e só siga se não chegou outra do mesmo contato nesse intervalo. No n8n isso é um nó Wait mais uma consulta de “última mensagem deste contato”.

4. Montar o contexto

Busque no Supabase as últimas 20 mensagens do contato e a ficha dele. Se humano_assumiu for verdadeiro, pare aqui. Se for primeiro contato, o contexto é só a ficha vazia.

5. Chamar o Claude

Prompt de sistema fixo (a seção seguinte diz o que vai nele), histórico como turnos alternados de usuário e assistente, mensagem nova por último. Peça resposta curta, em texto corrido, sem markdown (WhatsApp não renderiza cabeçalho nem tabela; negrito com asterisco funciona). Se o modelo devolver uma chamada de ferramenta, execute e devolva o resultado antes de enviar qualquer texto. Como o prompt de sistema é o mesmo em toda chamada, ele é o candidato natural ao prompt caching da API, que cobra uma fração pelo trecho repetido.

6. Enviar

setPresence “composing”, pausa proporcional ao tamanho da resposta, sendText. Respostas com mais de quatro linhas: quebre em duas mensagens.

7. Registrar

Grave a mensagem do cliente e a resposta na tabela mensagens, atualize ultima_interacao e o estágio do contato (novo, qualificando, agendado, humano). Sem esse registro você não tem memória nem métrica.

8. Monitorar a conexão

O evento CONNECTION_UPDATE avisa quando a instância cai (celular sem internet, sessão expirada). Um fluxo separado manda o alerta no WhatsApp da equipe. Agente que caiu e ninguém viu é pior que não ter agente: o cliente escreveu e ficou no vácuo.

O que vai no prompt de sistema

É o documento mais importante do projeto e cabe numa página. Blocos, nesta ordem:

Identidade: nome do agente, empresa, o que a empresa faz em uma frase, tom (informal, direto, sem emoji em excesso).
Base de conhecimento: serviços, preços publicados, horário, endereço, perguntas frequentes com as respostas oficiais. Só o que está publicado; o que não está, o agente diz que uma pessoa passa.
Lista fechada do que pode fazer (decisão 2) e gatilhos de transferência (decisão 3), escritos como regras.
Formato: respostas de 1 a 3 frases, uma pergunta por vez, sem markdown, sem se apresentar de novo a cada mensagem.
O que nunca fazer: prometer prazo ou desconto que não está na base, inventar dado, pedir documento sensível, continuar quando o cliente pediu humano.

Teste com 30 conversas reais antigas antes de ligar (na WW Mídia o prompt do agente foi ajustado assim, com as conversas de lead que já tinham chegado pelo site): cole a conversa como histórico e veja o que o agente responderia. Metade dos ajustes do prompt sai daí.

Quanto custa por conversa

Preço da API da Anthropic por milhão de tokens (tabela oficial, consultada em setembro de 2026): Claude Sonnet 5 custa US$ 2 de entrada e US$ 10 de saída; Claude Haiku 4.5, US$ 1 e US$ 5; Claude Opus 5, US$ 5 e US$ 25. Uma conversa de 20 trocas com prompt de sistema de 1.500 tokens e respostas de 60 tokens consome, somando o histórico reenviado a cada chamada, algo em torno de 60 mil tokens de entrada e 1.200 de saída: cerca de US$ 0,13 no Sonnet 5 sem cache, menos com cache do prompt de sistema. Em reais, centavos. O custo real do projeto é montar e ajustar o prompt e o fluxo, uma vez, e o servidor da Evolution e do n8n, que é fixo.

O que a evidência mostra sobre IA no atendimento

O estudo mais citado é Generative AI at Work (Brynjolfsson, Li e Raymond), com dados de 5.172 atendentes de suporte: acesso a um assistente de IA aumentou a produtividade (problemas resolvidos por hora) em 15% na média, com ganho muito maior para atendentes menos experientes e ganho pequeno, com leve queda de qualidade, para os mais experientes. Dois recados para o desenho do agente:

O ganho medido é de IA ajudando gente, não substituindo. Por isso o handoff não é detalhe: é onde o valor está.
O ganho é maior nos casos raros, em que o humano tem menos prática. O agente que responde bem a “quanto custa” é comum; o que resolve a pergunta estranha das 23h é o que o cliente lembra.

Onde esses agentes quebram

Loop consigo mesmo. Esqueceu de filtrar fromMe e o agente responde a própria resposta. Primeiro filtro do fluxo.
Histórico partido pelo @lid versus @s.whatsapp.net. Normalize o identificador.
Três respostas para três mensagens picadas. Espera de alguns segundos antes de responder.
Áudio e imagem sem tratamento. Cliente manda áudio e o agente responde “não entendi”. Ou transcreva (a Evolution entrega a mídia) ou peça por texto, mas decida antes.
Agente que não sabe que caiu. Sem CONNECTION_UPDATE ligado, ninguém percebe.
Humano e agente respondendo juntos. Sem a coluna humano_assumiu, o vendedor responde e o bot responde por cima.
Prompt com markdown. Cabeçalho, lista com hífen e tabela chegam como símbolos soltos no WhatsApp.
Disparo ativo num número comum. É o jeito mais rápido de perder o número. Inbound sim, disparo em massa não.

Quando não vale a pena

Menos de 20 conversas por dia. Resposta rápida do próprio WhatsApp Business e uma pessoa atenta resolvem.
Toda conversa é negociação. Se não existe preço publicado nem pergunta repetida, o agente vira porteiro que só transfere.
Ninguém vai assumir a transferência. Agente sem humano atrás é a mesma coisa que caixa postal.

Perguntas frequentes

Evolution API é oficial do WhatsApp?

Não. É um projeto de código aberto que expõe o WhatsApp como API REST. Ela conecta de dois jeitos: em um número comum, por QR code, como o WhatsApp Web; ou em cima da Cloud API oficial da Meta, com número verificado e cobrança por conversa. O primeiro é gratuito e sujeito aos termos de uso do WhatsApp; o segundo é o caminho oficial.

Um agente de IA respondendo no WhatsApp pode derrubar o número?

Responder quem escreveu para a empresa é o mesmo uso da resposta automática do WhatsApp Business e não costuma gerar denúncia. O que derruba número é disparo ativo em massa para quem não pediu, proibido pelos termos do WhatsApp. Se o negócio depende do número, use a Cloud API oficial via Evolution.

O Claude lembra da conversa anterior com o cliente?

Não. Cada chamada à API começa do zero. A memória é do fluxo: o n8n busca as últimas mensagens daquele contato no Supabase e envia junto com a mensagem nova. Por isso a chave do contato precisa estar normalizada, senão o histórico se parte.

Quanto custa um agente de IA no WhatsApp com Claude?

Em API, centavos por conversa: uma conversa de 20 trocas fica perto de US$ 0,13 no Claude Sonnet 5 sem cache, menos com cache do prompt de sistema, pelos preços de setembro de 2026. A Evolution API e o n8n são gratuitos e rodam no seu servidor; na Cloud API oficial, resposta em texto dentro da janela de atendimento não é cobrada. O investimento é montar o fluxo e ajustar o prompt uma vez.

O agente pode marcar reunião e consultar preço sozinho?

Sim, definindo ferramentas na chamada ao Claude: uma função “agendar” que o n8n executa na agenda, uma “buscar_preco” que consulta a tabela, uma “transferir” que liga o modo humano. O modelo decide quando chamar; o n8n executa e devolve o resultado. Só entra na lista o que você quer que ele faça sozinho.

Como passar a conversa do agente para uma pessoa?

Uma coluna no cadastro do contato, ligada por gatilho (cliente pediu, assunto fora da lista, duas mensagens sem entender) ou por comando da equipe no próprio WhatsApp. Ligada, o fluxo nem chama o Claude. A equipe recebe o resumo da conversa e um prazo; se ninguém assumir, o agente avisa o cliente do prazo real.

Qual modelo do Claude usar no WhatsApp?

Para atendimento com base de conhecimento fechada, Claude Sonnet 5 é o equilíbrio entre qualidade e custo; Haiku 4.5 custa metade e serve para classificação e triagem; Opus 5 para casos em que a conversa exige raciocínio longo. Comece com um, meça as transferências e as respostas erradas nas 30 primeiras conversas, e troque se precisar.

Resumo

Evolution recebe e envia; n8n decide; Supabase lembra; Claude lê e escreve. O prompt de sistema e o handoff são o projeto.
Agente responde quem escreveu. Disparo ativo em número comum derruba o número; na Cloud API, com opt-in.
Centavos por conversa em API; o custo é a montagem.
A evidência (5.172 atendentes, +15%) é de IA ajudando gente. Desenhe para isso.

Automação na esteira de um infoproduto: como a WW Mídia decide quem sobe para o alto ticket

Como Implementar Agentes de IA Autônomos com n8n e Claude

Agente de IA no WhatsApp para Vendas B2B com Evolution API

Como criar um agente de IA no WhatsApp com Claude e Evolution API: arquitetura, passo a passo no n8n e custo por conversa