API de WhatsApp para agentes de IA: conectando Claude, n8n e LangChain

Os três usam a mesma API REST: https://api.zapzapapi.com/api/v1/{instanceId}/..., autenticada por dois cabeçalhos, x-api-key e x-api-secret (autenticação). Se o seu framework lê OpenAPI, a especificação é pública em OpenAPI do ZapZap. A página agentes de IA junta as três opções num lugar só.

MCP (Model Context Protocol) deixa um cliente de IA descobrir ferramentas de um servidor e chamá-las durante a conversa. O zapzap-mcp expõe 25 ferramentas curadas (enviar texto e mídia, enquetes, botões, checar números, buscar mensagens, grupos, webhooks) em vez de mais de 150 endpoints crus, para o modelo errar menos na escolha.

O código é aberto, está em github.com/zapzapapi/zapzap-mcp e ainda não está publicado no npm. Por isso a instalação é a partir do repositório: clone, instale e compile (Node 18 ou mais novo). Depois aponte o cliente para o arquivo compilado.

Dois comportamentos importantes. As ferramentas de envio são marcadas como não idempotentes e destrutivas, então o cliente MCP pede confirmação a cada envio. E ZAPZAP_READ_ONLY=true remove todas as ferramentas de escrita, que é o padrão certo na primeira semana (já vem ligado nos exemplos abaixo).

Peça algo como: confira se minha instância está conectada e diga quais destes três números têm WhatsApp. Aprove cada chamada manualmente até confiar. Se preferir escrever o seu próprio servidor, o passo a passo do servidor MCP tem o código em TypeScript.

git clone https://github.com/zapzapapi/zapzap-mcp
cd zapzap-mcp
npm install
npm run build
# Claude Code:
claude mcp add zapzap -e ZAPZAP_API_KEY=your-api-key -e ZAPZAP_API_SECRET=your-api-secret -e ZAPZAP_READ_ONLY=true -- node "$(pwd)/dist/src/index.js"

{
  "mcpServers": {
    "zapzap": {
      "command": "node",
      "args": ["/path/to/zapzap-mcp/dist/src/index.js"],
      "env": {
        "ZAPZAP_API_KEY": "your-api-key",
        "ZAPZAP_API_SECRET": "your-api-secret",
        "ZAPZAP_READ_ONLY": "true"
      }
    }
  }
}

O fluxo tem cinco nós. 1) Webhook recebe o evento messages da instância (registre a URL de produção no endpoint de webhook). 2) Code extrai número, texto e id da mensagem e descarta eventos com fromMe verdadeiro; sem isso o agente responde às próprias respostas em loop. 3) AI Agent com memória em janela, usando o número do contato como chave de sessão, para cada cliente ter a própria conversa; coloque a regra de passagem para humano no prompt de sistema, por exemplo responder com uma frase fixa quando o cliente pedir uma pessoa. 4) IF detecta essa frase fixa e marca o contato como com humano. 5) HTTP Request chama POST /api/v1/{instanceId}/send/text com number e text.

Existe também um nó da comunidade, o n8n-nodes-zapzap (versão 0.1.3 no npm). Nós de comunidade não verificados só rodam em n8n self-hosted; no n8n Cloud use o HTTP Request com os mesmos cabeçalhos. O passo a passo completo está em agente de IA no WhatsApp com n8n, e há fluxos prontos nos templates de n8n.

Uma ferramenta é uma função com nome, descrição e argumentos tipados. O modelo decide quando chamar; a função decide o que é permitido. As travas ficam na função, nunca no prompt. O exemplo abaixo tem duas ferramentas: checar números e enviar texto só para uma lista permitida, com envio desligado até você definir ZAPZAP_ENABLE_SEND=true.

Ligue as ferramentas a um agente com LangChain 1.x (create_agent) ou com o decorator tool do CrewAI, e confira a documentação da sua versão, porque os dois projetos mudam rápido. Aprovação humana antes do envio real vem dos recursos de interrupção ou human-input do seu framework. A versão completa está no guia de LangChain e CrewAI.

import os
import re
import requests
from langchain_core.tools import tool

BASE = "https://api.zapzapapi.com/api/v1"
INSTANCE = os.environ["ZAPZAP_INSTANCE_ID"]
HEADERS = {
    "x-api-key": os.environ["ZAPZAP_API_KEY"],
    "x-api-secret": os.environ["ZAPZAP_API_SECRET"],
}
ALLOWED = {n.strip() for n in os.environ.get("ZAPZAP_ALLOWED", "").split(",") if n.strip()}
SEND_ENABLED = os.environ.get("ZAPZAP_ENABLE_SEND") == "true"


def _post(path: str, body: dict) -> dict:
    r = requests.post(f"{BASE}/{INSTANCE}{path}", json=body, headers=HEADERS, timeout=20)
    r.raise_for_status()
    return r.json()


@tool
def check_whatsapp_numbers(numbers: list[str]) -> str:
    """Check which phone numbers are registered on WhatsApp.
    Numbers: country code plus digits only, for example 5511999999999."""
    clean = [n for n in numbers if re.fullmatch(r"\d{10,15}", n)]
    if not clean:
        return "No valid numbers. Use country code and digits only."
    return str(_post("/chat/check", {"numbers": clean}))


@tool
def send_whatsapp_text(number: str, text: str) -> str:
    """Send a WhatsApp text to ONE allowed recipient. Never invent numbers."""
    if not re.fullmatch(r"\d{10,15}", number):
        return "Invalid number format."
    if number not in ALLOWED:
        return "Blocked: this number is not on the allowed list."
    if len(text) > 1000:
        return "Blocked: text too long."
    if not SEND_ENABLED:
        return f"Safe mode, not sent. Would send to {number}: {text[:80]}"
    return str(_post("/send/text", {"number": number, "text": text}))

from langchain.agents import create_agent

agent = create_agent(
    model="provider:model-name",   # fill in the provider you have a key for
    tools=[check_whatsapp_numbers, send_whatsapp_text],
    system_prompt="You help the support team. Only message people on the allowed list.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "Is 5511999999999 on WhatsApp?"}]})

API não oficial vai contra os termos do WhatsApp e um número pode ser limitado ou banido. Agente não reduz esse risco; pode aumentar se começar conversa fria em volume. Recursos anti-bloqueio, como digitando automático e ritmo de envio, reduzem o risco, não o eliminam, e ninguém honesto promete o contrário.

Use agentes para responder quem escreveu primeiro, apoiar o time e tarefas internas, e só mande mensagem para quem concordou em receber. Veja o guia anti-bloqueio e a política de uso aceitável. Se você precisa de canal oficial, use a Cloud API da Meta: o comparativo oficial x não oficial mostra quando cada uma vence.

R$15 por número ativo por mês, pré-pago, sem cobrança por mensagem (preços). Contas novas recebem crédito de boas-vindas ao verificar o telefone, conforme a campanha vigente. O início rápido leva da conta à primeira mensagem.