Construa com IA: como montar o WhatsApp dos clientes da agência com Claude Code, OpenAPI e MCP

Quatro peças. O llms.txt resume o produto, o preço, os limites e os links para o agente. A especificação OpenAPI e a coleção Postman descrevem os endpoints, em português, inglês e espanhol. O servidor MCP, de código aberto (github.com/zapzapapi/zapzap-mcp), dá ao agente ferramentas prontas, e os SDKs oficiais (Node.js, Python e PHP, pelo GitHub zapzapapi) cobrem a integração em código. Veja a página de agentes de IA e o guia do servidor MCP.

Coloque no arquivo de instruções do projeto (CLAUDE.md, AGENTS.md ou as regras do Cursor) os links da OpenAPI e do llms.txt, o base URL e os nomes das variáveis de ambiente. Nunca cole a chave e o segredo da API no prompt nem no repositório: o agente só precisa saber que existem ZAPZAP_API_KEY e ZAPZAP_API_SECRET.

Um trecho de instruções que funciona: "A API de WhatsApp é a ZapZap. Especificação: https://zapzapapi.com/openapi/zapzap-openapi.pt.json. Resumo para IA: https://zapzapapi.com/llms.txt. Base: https://api.zapzapapi.com/api/v1. Autenticação: cabeçalhos x-api-key e x-api-secret, lidos de ZAPZAP_API_KEY e ZAPZAP_API_SECRET. Use somente endpoints presentes na especificação e diga quando um recurso não existir."

Prompts que funcionam são pequenos e verificáveis. Para um CRM mínimo: "Crie um script Node.js que receba o webhook de mensagens recebidas da ZapZap e grave numa tabela leads (telefone, nome, primeira mensagem, instância, data). Use só os campos que a especificação descreve, valide o payload e responda 200 rápido." Para relatório: "Leia as instâncias com GET /instances e, para cada uma, as campanhas com GET /{instanceId}/sender/listfolders. Gere um JSON com os contadores log_total, log_delivered, log_read e log_failed." Para lembretes: "Agende uma mensagem com POST /{instanceId}/sender/simple usando scheduled_for em milissegundos."

Peça sempre o teste no fim: "escreva um teste que rode contra uma instância de homologação". E mande o agente citar de qual operação da OpenAPI tirou cada chamada, o que torna a revisão de um minuto.

O trecho abaixo é a base de quase tudo: listar as instâncias da conta e checar o status de cada uma. Ele usa apenas operações documentadas, e serve de ponto de partida para um painel interno de saúde dos números dos clientes.

const BASE = "https://api.zapzapapi.com/api/v1";
const headers = {
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

const instances = await (await fetch(BASE + "/instances", { headers })).json();
for (const inst of instances) {
  const r = await fetch(BASE + "/" + inst.id + "/instance/status", { headers });
  console.log(inst.name, r.ok ? await r.json() : "HTTP " + r.status);
  await new Promise((res) => setTimeout(res, 1000));
}

Quatro projetos de alto retorno para agência: um painel de saúde dos números dos clientes (quais caíram, quais precisam reconectar), um CRM mínimo alimentado por webhook, um relatório mensal por cliente (veja automatizar relatórios) e um agendador de retornos e lembretes (veja agendar mensagens de compromisso). Para o fluxo de leads de anúncio por cliente, veja acompanhar leads de anúncios.

Comece pelo painel de saúde: é só leitura, tem pouco risco e já entrega valor na primeira semana.

Revise todo envio. Um agente que gera código que envia mensagem pode, por erro, mandar a mesma mensagem a uma lista inteira ou ignorar o ritmo. Exija atrasos entre envios, uma trava de volume por execução e um modo de teste que escreve em log em vez de enviar. Não aprove código que dispare para lista sem consentimento, conforme o uso aceitável.

Trate também a segurança: chave e segredo só no back-end, nunca no navegador, e uma chave por ambiente. Para as páginas de nicho, veja agências com IA e revenda com a marca do cliente.