WACrew

Blog

Como criar um agente de IA para WhatsApp com Claude

Passo a passo para criar um agente de IA no WhatsApp com Claude, da conexão ao envio. Ferramentas, laço do agente, revisão antes de responder e o atalho com MCP.

Por Rodrigo Sumioshi 6 min de leitura
Neste artigo
  1. 1. Escolha como conectar ao WhatsApp
  2. 2. Defina as ferramentas do agente
  3. 3. Rode o laço do agente
  4. 4. Escreva as instruções do agente
  5. 5. Controle o que sai para o cliente
  6. O atalho: usar um servidor MCP pronto
  7. Checklist antes de colocar no ar

Montar um agente de IA que atende no WhatsApp parece um projeto grande, mas ele se divide em quatro partes bem separadas. Primeiro, receber as mensagens. Depois, dar ao modelo as ferramentas certas. Em seguida, rodar o laço em que o Claude decide o que fazer. Por último, controlar o que sai para o cliente.

Este guia passa por cada parte com código em TypeScript e mostra, no fim, um atalho para quem não quer escrever tudo do zero.

1. Escolha como conectar ao WhatsApp

Existem dois caminhos, com regras bem diferentes.

API oficial da Meta (WhatsApp Business Platform). Você cadastra um número no Meta for Developers, recebe as mensagens por webhook e envia por HTTP. É o caminho aprovado para empresas, com cobrança por uso e regras de modelo de mensagem fora da janela de 24 horas. Explicamos o recebimento em webhooks de WhatsApp.

WhatsApp Web, via biblioteca. Bibliotecas como o Baileys conectam a sua própria conta como um aparelho vinculado, por QR code. É mais simples para começar e funciona com grupos, mas não é oficial. Use só com quem já conversa com você e nunca para disparo em massa. O texto sobre API de WhatsApp não oficial e banimento mostra o que cada projeto diz sobre o risco.

Para o agente, tanto faz o caminho. O que importa é que, no fim, você tenha uma função que recebe mensagens e outra que envia.

2. Defina as ferramentas do agente

Um agente sem ferramentas é só um chatbot que escreve bem. As ferramentas são o que deixa o Claude consultar contexto e agir. Para atendimento, comece com estas três.

  • ler_historico: últimas mensagens da conversa;
  • buscar_cliente: dados do cliente no seu sistema;
  • responder: envia a mensagem final.

Na API do Claude, cada ferramenta tem um nome, uma descrição e o esquema JSON dos argumentos (documentação de tool use):

const ferramentas = [
  {
    name: "ler_historico",
    description: "Lê as últimas mensagens de uma conversa do WhatsApp, da mais antiga para a mais nova.",
    input_schema: {
      type: "object",
      properties: {
        chat: { type: "string", description: "Identificador da conversa" },
        limite: { type: "number", description: "Quantas mensagens trazer" },
      },
      required: ["chat"],
    },
  },
  {
    name: "responder",
    description: "Envia uma resposta para a conversa. Use só quando a resposta estiver pronta.",
    input_schema: {
      type: "object",
      properties: { chat: { type: "string" }, texto: { type: "string" } },
      required: ["chat", "texto"],
    },
  },
];

Capriche nas descrições. É por elas que o modelo decide qual ferramenta usar e quando.

3. Rode o laço do agente

O agente é um laço. Você manda a conversa e as ferramentas, o Claude responde pedindo uma ferramenta (stop_reason: "tool_use"), você executa e devolve o resultado como tool_result. Repete até ele terminar.

import Anthropic from "@anthropic-ai/sdk";

const claude = new Anthropic(); // lê ANTHROPIC_API_KEY do ambiente

async function atender(chat: string, novaMensagem: string) {
  const mensagens: Anthropic.MessageParam[] = [
    { role: "user", content: `Conversa ${chat}. Mensagem nova do cliente: ${novaMensagem}` },
  ];

  for (let volta = 0; volta < 8; volta++) {
    const resposta = await claude.messages.create({
      model: "claude-sonnet-5-5",
      max_tokens: 1024,
      system: INSTRUCOES,
      tools: ferramentas,
      messages: mensagens,
    });

    mensagens.push({ role: "assistant", content: resposta.content });
    if (resposta.stop_reason !== "tool_use") return;

    const resultados = [];
    for (const bloco of resposta.content) {
      if (bloco.type !== "tool_use") continue;
      const saida = await executar(bloco.name, bloco.input);
      resultados.push({ type: "tool_result" as const, tool_use_id: bloco.id, content: saida });
    }
    mensagens.push({ role: "user", content: resultados });
  }
}

Três detalhes desse código evitam dor de cabeça. O limite de voltas impede um laço infinito. O histórico guarda tanto o pedido de ferramenta quanto o resultado, na ordem certa. E a função executar é sua, então é ali que ficam as validações.

4. Escreva as instruções do agente

O system é onde você diz quem o agente é e o que ele pode decidir sozinho. Um bom ponto de partida para atendimento:

Você responde clientes no WhatsApp em nome de uma empresa de software.
Antes de responder, leia o histórico da conversa.
Responda curto, em português do Brasil, sem listas nem negrito.
Nunca prometa prazo, preço ou desconto. Nesses casos, diga que vai verificar e encerre sem responder.
Se o cliente estiver irritado ou o pedido for ambíguo, não responda.

Repare que as regras de "não responder" são tão importantes quanto as de responder. Um agente de atendimento que fala demais causa mais problema que um que fica quieto.

5. Controle o que sai para o cliente

É aqui que a maioria dos agentes de WhatsApp falha. O texto sai correto, mas com cara de robô: abre com "Ótima pergunta!", fecha se colocando à disposição, usa travessão e lista com marcadores num balão de chat. O cliente percebe.

Três camadas ajudam:

  1. Revisão em código antes do envio. Regras simples barram os vícios mais comuns. A biblioteca botsmell, de código aberto, faz isso para português e inglês e devolve uma sugestão para cada problema, que você manda de volta ao modelo para reescrever.
  2. Modo de confirmação. No começo, a ferramenta responder não envia. Ela mostra o texto para uma pessoa aprovar.
  3. Ritmo humano. Resposta em dois segundos para uma mensagem longa denuncia automação. Um atraso proporcional ao tamanho e um "digitando" antes do envio deixam a conversa natural.

O atalho: usar um servidor MCP pronto

Se o objetivo é ter um agente funcionando, e não aprender a montar cada peça, dá para pular boa parte do código acima. O WACrew é um projeto de código aberto que já faz a conexão, guarda o histórico, transcreve áudio e entrega as respostas com revisão e ritmo humano. Ele traz um servidor MCP com 36 ferramentas.

Com o painel rodando, você conecta o Claude Code com um comando:

claude mcp add wacrew \
  -e WAC_CLOUD_URL=https://seu-painel.exemplo.com \
  -e WAC_CLOUD_USER=admin -e WAC_CLOUD_PASS=sua-senha \
  -- npx -y wacrew-mcp

A partir daí, o Claude passa a ter ferramentas como ler_mensagens, transcrever, preparar_resposta e responder. Cada conversa tem um modo: confirmar, o padrão, em que o agente mostra o texto e espera o seu OK, ou autônomo. O passo a passo completo está em como conectar o WhatsApp ao Claude Code com MCP.

Checklist antes de colocar no ar

  • O agente lê o histórico antes de responder?
  • Existe um limite de voltas no laço?
  • Prazo, preço e reclamação voltam para uma pessoa?
  • O texto passa por uma revisão antes do envio?
  • Cada envio fica registrado, com o que o agente leu antes?
  • Você testou em uma conversa interna antes de ligar com clientes?

Com essas respostas em "sim", o agente está pronto para o primeiro cliente de verdade. Para entender melhor a diferença entre esse tipo de sistema e um chatbot comum, veja o que é um agente de IA.