Para agentes de IA e automação
WhatsApp para agentes de IA: API REST, nó n8n e MCP
Um agente de IA precisa de três coisas para usar o WhatsApp: ferramentas para enviar, um jeito de receber e regras de segurança. Veja o que a ZapZap oferece hoje, o que ainda não existe e como ligar um agente à sua instância.
Como um agente de IA usa o WhatsApp?
Um agente envia mensagens chamando a API REST da ZapZap como uma ferramenta (por exemplo, send/text e send/media) e recebe as respostas por webhook. A autenticação é por dois cabeçalhos, x-api-key e x-api-secret, e o arquivo OpenAPI descreve todos os endpoints para o agente ler.
Hoje isso funciona por três caminhos: a API REST com OpenAPI, o nó da comunidade n8n-nodes-zapzap para fluxos no n8n e o agente de IA embutido por instância. O servidor MCP da ZapZap ainda não foi publicado; esta página diz isso com clareza na seção abaixo.
Formas de ligar um agente ao WhatsApp
A tabela mostra o que existe hoje (consulta em 27/10/2026) e o que não existe.
| Caminho | Situação | Para quê |
|---|---|---|
| API REST e OpenAPI | Disponível: 150+ endpoints, arquivo OpenAPI em pt, en e es | Qualquer agente ou framework que chame HTTP como ferramenta |
| Nó n8n-nodes-zapzap | Disponível no npm (nó da comunidade, versão 0.1.3), não verificado pelo n8n | Fluxos de agente no n8n, em instalação própria |
| Webhook com assinatura | Disponível: eventos messages e messages_update, retentativas e assinatura HMAC | Entregar a resposta do cliente ao agente |
| Agente de IA por instância | Disponível no painel e na API (agent-edit) | Atendimento sem montar o agente por fora |
| Servidor MCP | Ainda não publicado | Quando existir, ligaria clientes MCP direto às ferramentas |
| Pacotes LangChain e CrewAI | Ainda não publicados | Hoje, use a API como ferramenta HTTP |
Primeira chamada, para testar a ferramenta
Antes de colocar a API na mão de um agente, teste o envio com cURL. Crie a conta, conecte um número por QR code e copie o ID da instância, a chave e o segredo.
curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/send/text \
-H "Content-Type: application/json" \
-H "x-api-key: SUA_API_KEY" \
-H "x-api-secret: SEU_API_SECRET" \
-d '{"number":"5511999999999","text":"Olá! Aqui é o assistente da clínica."}'Dê ao agente só as ferramentas de que ele precisa, com credenciais em variáveis de ambiente, e nunca no prompt.
Ferramentas que o agente pode receber
Cada linha é um endpoint real da referência. Comece com poucas.
| Ferramenta | Endpoint | Observação |
|---|---|---|
| Enviar texto | POST /api/v1/{instanceId}/send/text | Campos number e text |
| Enviar mídia | POST /api/v1/{instanceId}/send/media | Campos number, type, file (URL), text, docName |
| Verificar números | POST /api/v1/{instanceId}/chat/check | Campo numbers; devolve se está no WhatsApp |
| Ver status da instância | GET /api/v1/{instanceId}/instance/status | Para o agente saber se pode enviar |
| Configurar webhook | PUT /api/v1/instances/{id}/webhook | Define a URL que recebe as mensagens |
E o MCP?
O Model Context Protocol (MCP) é um padrão para expor ferramentas a clientes de IA. A ZapZap ainda não publicou um servidor MCP: não há pacote nem comando de instalação, e esta página não inventa um.
Enquanto isso, o arquivo OpenAPI da ZapZap tem um identificador por operação, o que permite gerar um servidor MCP a partir dele. O post servidor MCP de WhatsApp para Claude e Cursor mostra o desenho. Quando houver um servidor oficial, ele será anunciado aqui.
Limites e boas práticas para agentes
- Envie só para quem aceitou receber (opt-in). Um agente que escreve para quem não pediu aumenta o risco de denúncia e de bloqueio.
- Defina um ritmo: o agente deve respeitar intervalos entre mensagens e limites por contato. Não existe número de mensagens por dia que seja garantidamente seguro.
- Deixe o humano no circuito: regras de passagem para atendente, confirmação antes de ações irreversíveis e registro de cada envio.
- Guarde credenciais fora do prompt e dê ao agente apenas as ferramentas necessárias. Operações destrutivas, como apagar instância, não devem ficar à disposição dele.
- Lembre que a ZapZap é uma API não oficial: viola os termos do WhatsApp e o número pode ser limitado ou bloqueado. O recurso anti-bloqueio reduz o risco, sem eliminá-lo.
Perguntas frequentes
A ZapZap tem servidor MCP?
Ainda não. Não publicamos um servidor MCP nem pacote de instalação. Hoje o agente usa a API REST como ferramenta, o nó n8n-nodes-zapzap ou o agente de IA da própria instância.
Posso usar a API com qualquer framework de agentes?
Pode. Se o framework chama HTTP como ferramenta, ele chama a API da ZapZap com os cabeçalhos x-api-key e x-api-secret. O arquivo OpenAPI descreve os campos de cada endpoint.
O nó do n8n é verificado?
É um nó da comunidade (n8n-nodes-zapzap, versão 0.1.3 em 27/10/2026), ainda não verificado pelo n8n. Nós não verificados só funcionam em n8n com instalação própria, segundo a documentação do n8n.
Como o agente recebe a resposta do cliente?
Por webhook: configure a URL da sua aplicação e ligue o evento messages. Valide a assinatura e ignore mensagens com fromMe verdadeiro.
O uso por agente muda o risco de bloqueio?
Não elimina nem cria um risco novo, mas um agente pode enviar rápido demais ou para quem não pediu. Defina ritmo, opt-in e limites, e lembre que nenhuma API não oficial garante que o número não será bloqueado.
Quanto custa?
R$15 por número ativo ao mês, pré-pago, sem cobrança por mensagem. O consumo de IA do agente embutido é debitado do saldo. O custo do modelo do seu próprio agente é com o seu provedor.
Continue por aqui
Endpoints, campos e exemplos
Nó da comunidade, HTTP Request e templates
Agente por instância com passagem para humano
Assinatura, idempotência e retry
Passo a passo do fluxo
O que reduz o risco e o que não reduz
Dê WhatsApp ao seu agente
Crie a conta, conecte um número e teste a primeira chamada. R$15 por número ativo ao mês, sem cobrança por mensagem.