Resumo: Instalar a Agent Skill da Whapi com um único comando evita os três erros mais comuns que agentes de IA cometem com a API do WhatsApp: Chat IDs errados, cabeçalhos de autenticação incorretos e polling em vez de webhooks. Ela codifica 7 categorias de referência e funciona com Cursor, Claude Code, Codex, GitHub Copilot e mais de 40 outros agentes.
Instalação: npx skills add Whapi-Cloud/whapi-whatsapp-api-skill · Requer Node.js 18+ · GitHub · Documentação
O que é uma Agent Skill?
Quando você pede ao Cursor ou ao Claude Code para construir um bot de WhatsApp, o agente recorre a dados de treinamento que cobrem milhares de APIs — nenhuma delas especificamente autoritativa para a Whapi.Cloud como ela existe hoje. O resultado é código que parece plausível mas falha silenciosamente em produção.
Uma Agent Skill é a solução. É um arquivo de conhecimento estruturado (SKILL.md) que fica no seu projeto e é carregado automaticamente no contexto do agente quando ele detecta uma tarefa relevante. Pense nela como instruções permanentes: "Ao desenvolver com a API do WhatsApp da Whapi.Cloud, use exatamente estes nomes de campo, padrões de autenticação e regras arquiteturais."
O padrão foi introduzido no final de 2025 por meio do vercel-labs/skills e hoje é suportado por mais de 40 agentes de IA. Você instala skills com um único comando npx skills add. Sem arquivos de configuração, sem boilerplate — o agente as detecta automaticamente.
MCP é a despensa — a Agent Skill é a receita. O servidor MCP da Whapi dá ao seu agente 165 ferramentas para chamar a API do WhatsApp. A Agent Skill ensina qual ferramenta chamar em cada situação, quais parâmetros usar e quais padrões evitar. Juntos, eles fecham os modos de falha mais comuns em código do WhatsApp gerado por IA.
O problema: o que agentes de IA erram sobre o WhatsApp
Agentes de codificação de IA são de uso geral. Sem um grounding específico, eles geram código que parece correto mas quebra em tempo de execução. Nenhum desses erros aparece em tempo de compilação — eles só surgem quando a API retorna 400 ou 401.
Estes são os dez erros mais comuns e o que a Whapi Agent Skill corrige:
| O que a IA escreve (errado) | O que a Whapi.Cloud exige (correto) | Impacto |
|---|---|---|
[email protected] |
[email protected] |
Formato antigo — todo envio retorna 400 |
{"message": "hello"} |
{"body": "hello"} |
Nome de campo errado — a mensagem é descartada silenciosamente |
{"chat_id": "..."} |
{"to": "..."} |
As ferramentas de envio usam to, não chat_id |
X-API-Key: your_token |
Authorization: Bearer your_token |
Cabeçalho de auth errado — 401 em toda requisição |
API_KEY=your_token |
API_TOKEN=your_token |
Nome de variável de ambiente errado — o servidor MCP nunca reconhece |
sendMessage() genérico |
sendMessageText, sendMessageImage, etc. |
Não existe ferramenta genérica — erro 400 |
Polling de getMessages em loop |
Webhook via updateChannelSettings |
Latência de 5+ segundos, consome o rate limit, perde eventos |
| Responder a todas as mensagens recebidas | Filtrar from_me: true antes de responder |
Sem esse filtro, o bot responde a si mesmo em loop |
sendBulkMessages(recipients: [...]) |
sendMessageText uma vez por destinatário, com delays |
Essa ferramenta não existe — endpoint alucinado |
{"webhookUrl": "https://..."} |
{"webhooks": [{"url": "...", "mode": "body", ...}]} |
A configuração do webhook deve usar o array aninhado webhooks[] |
Agent Skill vs. MCP: duas camadas, uma stack
Se você já usa o servidor MCP da Whapi, a Agent Skill adiciona a camada de conhecimento que o MCP sozinho não entrega. A Whapi.Cloud é o único provedor de API do WhatsApp que oferece as duas coisas.
| Agent Skill | Servidor MCP (whapi-mcp) | |
|---|---|---|
| O que fornece | Conhecimento: como usar a API corretamente | Capacidade: 165 ferramentas para chamar a API |
| Método de instalação | npx skills add ... |
Adicionar entrada no mcp.json |
| Exige conta na Whapi? | Não — é carregada como contexto | Sim — precisa de um API_TOKEN válido |
| Faz chamadas à API? | Não — é apenas um arquivo de referência | Sim — executa chamadas reais à API |
| Previne alucinações? | Sim — esse é o propósito principal | Parcialmente — os schemas das ferramentas ajudam, os padrões não |
O que a Whapi Agent Skill contém
A Whapi Agent Skill codifica 7 categorias de referência para que seu agente de IA chegue à API já conhecendo as regras. Cada arquivo de referência inclui exemplos corretos e incorretos, checklists anti-alucinação e notas específicas da Whapi.
1. Conceitos básicos (CRÍTICO)
Erros no formato do Chat ID são a causa isolada mais comum de erros 400 em código do WhatsApp gerado por IA. A skill codifica os três formatos:
- Conversa pessoal:
{phone}@s.whatsapp.net— p. ex.,[email protected] - Grupo:
{id}@g.us— obtenha viagetGroups; nunca construa o ID manualmente - Canal / Newsletter:
{id}@newsletter— obtenha viagetNewsletters
Também cobre a configuração do MCP e a autenticação Authorization: Bearer {token} com o nome correto da variável de ambiente API_TOKEN.
2. Envio de mensagens (CRÍTICO)
Uma árvore de decisão completa para que o agente escolha a ferramenta correta para cada tipo de conteúdo:
- Texto →
sendMessageText(campo:body) - Imagem JPG/PNG/WebP →
sendMessageImage(campo:media) - Vídeo MP4 →
sendMessageVideo - GIF (arquivo MP4) →
sendMessageGif - Vídeo circular →
sendMessageShort - Arquivo de áudio MP3/WAV →
sendMessageAudio - Mensagem de voz OGG Opus →
sendMessageVoice - Documento/PDF →
sendMessageDocument - Sticker WebP →
sendMessageSticker - Enquete →
sendMessagePoll - Botões/lista interativos →
sendMessageInteractive - Localização →
sendMessageLocation
3. Recebimento de mensagens (CRÍTICO)
Fazer polling de getMessages em loop é o antipadrão — o recebimento de mensagens do WhatsApp exige webhooks exclusivamente. A skill ensina a estrutura correta de configuração aninhada de webhooks e explica por que polling falha em escala: latência de 5+ segundos, consumo contínuo do rate limit, eventos perdidos entre intervalos de sondagem.
4. Grupos (ALTA)
Criar grupos, gerenciar participantes, gerar links de convite, atribuir papéis de admin. A skill cobre o ciclo de vida completo via createGroup, getGroups e ferramentas de gerenciamento de participantes. IDs de grupo usam o formato @g.us e devem ser obtidos pela API.
5. Canais / Newsletters (ALTA)
Criar Canais do WhatsApp, postar mensagens via Chat ID @newsletter, gerenciar assinantes e admins. Para audiências grandes do WhatsApp, um Canal é mais seguro do que um loop de broadcast — sem risco de ban, sem delays obrigatórios por mensagem.
6. Comunidades (MÉDIA)
Criar comunidades, vincular grupos, enviar anúncios pelo grupo dedicado de Anúncios. Os anúncios devem ir especificamente pelo grupo de Anúncios — não diretamente aos subgrupos.
7. Padrões de integração (ALTA)
Duas receitas prontas para produção:
- Padrão de bot: Configurar webhook → receber mensagem → filtrar
from_me: true→ responder. Funciona para bots de eco, respondedores por palavra-chave e assistentes com IA. - Padrão de broadcast: Loop por destinatário com delays obrigatórios, exigência de número aquecido, regras de personalização e checagem de cota via
getLimits.
Casos de uso: onde a skill ajuda hoje
Estes são cinco fluxos concretos em que a Whapi Agent Skill produz código correto já na primeira tentativa.
1. Bot de atendimento ao cliente no WhatsApp
Você pede ao Cursor para construir um bot de suporte. Sem a skill, o Cursor escreve um loop de polling e usa Chat IDs @c.us. Com a skill, ele gera um handler de webhook, filtra from_me e usa @s.whatsapp.net automaticamente. Filtre from_me: true em todo handler de resposta do bot, ou seu bot de WhatsApp vai mandar mensagens para si mesmo em loop infinito.
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.json
if "messages" not in data:
return {"status": "ok"}
for message in data["messages"]:
if message.get("from_me"):
continue # prevent infinite loop
if message.get("type") != "text":
continue
chat_id = message["chat_id"] # e.g., "[email protected]"
text = message["text"]["body"] # correct field name: body
reply(chat_id, f"Got it: {text}")2. Notificação de lead a partir de formulário web
Um novo lead envia um formulário. Seu agente envia uma mensagem de WhatsApp para o time de vendas. A skill garante que o agente use sendMessageText com o campo body e o Chat ID correto @s.whatsapp.net — não um endpoint de envio genérico alucinado.
3. Sistema de notificação para grupos
Você quer postar atualizações em um grupo de WhatsApp. A skill ensina ao agente que IDs de grupo usam o formato @g.us, que é preciso chamar getGroups para obter o ID (nunca construa manualmente) e que o parâmetro to recebe a string completa do Chat ID.
4. Broadcasting via Canal do WhatsApp
Você precisa alcançar centenas de assinantes. A skill destaca a abordagem de Canal antes do loop de broadcast — sem risco de ban, sem delays obrigatórios por mensagem, os assinantes entram por conta própria. Para audiências grandes, esse é o padrão correto.
5. Mensageria em massa controlada
Quando é necessário mandar mensagem direta para uma lista: no máximo 10 mensagens a cada 15 minutos, no mínimo 60–90 segundos entre envios, número aquecido obrigatório, conteúdo personalizado por destinatário. Enviar mensagens no WhatsApp sem delays de 60 segundos e sem personalização dispara a detecção antispam e a suspensão da conta. Chame getLimits primeiro para verificar a cota restante.
Instalação: um comando, todos os agentes
Instale a Whapi WhatsApp Agent Skill com um único comando:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skillRequisito: Node.js 18 ou superior.
Para apontar para um agente específico ou instalar globalmente:
# Install for Cursor only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent cursor
# Install for Claude Code only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent claude-code
# Install globally (available in all projects)
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --globalApós a instalação, a skill carrega automaticamente quando seu agente detecta uma tarefa relacionada ao WhatsApp. Se ela não ativar por conta própria:
- Cursor: Referencie
@.agents/skills/whapi/AGENTS.mdno chat, ou execute/whapi - Claude Code: Execute
/file .agents/skills/whapi/AGENTS.mdno início da sessão, ou execute/whapi - GitHub Copilot: Referencie
#.agents/skills/whapi/AGENTS.mdno chat
Configuração do servidor MCP (Cursor)
Para que o agente possa fazer chamadas reais à API do WhatsApp, adicione o servidor MCP da Whapi em %USERPROFILE%\.cursor\mcp.json:
{
"mcpServers": {
"whapi-mcp": {
"command": "npx",
"args": ["-y", "whapi-mcp@latest"],
"env": { "API_TOKEN": "YOUR_TOKEN" }
}
}
}Pegue seu token em panel.whapi.cloud/dashboard. Depois de salvar a configuração, reinicie o Cursor e chame checkHealth (sem argumentos) — um canal conectado retorna "status.text": "AUTH".
Guia completo de instalação: support.whapi.cloud/help-desk/ai-tools/agent-skills
O que ainda não está coberto — e o que está por vir
A versão atual foca nos fluxos mais comuns. Algumas áreas ainda não estão nos arquivos de referência da skill:
- Mensagens interativas (
sendMessageInteractive): Documentadas, mas marcadas como instáveis — a entrega varia entre versões do WhatsApp. Monitoradas ativamente. - Status / Stories do WhatsApp: Disponíveis no MCP (165 ferramentas), ainda não documentados nas categorias de referência da skill.
- Commerce / Pedidos / Produtos: Fluxos de catálogo e pedidos do WhatsApp estão disponíveis na API, mas ainda não na biblioteca de padrões da skill.
- Manuseio avançado de mídia: Casos de borda com codificação de arquivos, limites de tamanho e streaming de áudio ainda não estão cobertos.
- Chamadas de WhatsApp: Detecção de chamadas recebidas via webhooks está listada; padrões de gerenciamento de chamadas estão pendentes.
Agent Skills codificam anos de tentativa e erro com APIs em um único arquivo para que agentes de IA pulem direto para a implementação correta. A Whapi Agent Skill é um documento vivo que cresce a cada fluxo de desenvolvimento que documentamos. Contribuições são bem-vindas.
Primeiros passos com a Whapi.Cloud
A Whapi Agent Skill é gratuita e de código aberto. Para usá-la contra a API real do WhatsApp, você precisa de uma conta na Whapi.Cloud — há um sandbox gratuito disponível sem prazo de validade, cobrindo 5 conversas ativas e 150 mensagens por dia. Sem aprovação da Meta, sem restrições de templates.
- Crie uma conta gratuita em whapi.cloud
- Pareie seu número do WhatsApp via QR code
- Copie o token do seu canal no dashboard
- Execute:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill - Adicione a entrada do servidor MCP na configuração do seu agente
- Peça ao seu agente: "Envie uma mensagem de WhatsApp usando WHAPI"
O agente vai carregar a skill, verificar a conexão com checkHealth e te guiar pelo primeiro envio com os nomes de campo corretos, o formato de Chat ID e o cabeçalho de auth. Seu primeiro envio funcional de WhatsApp, da instalação da skill até a confirmação de entrega, leva menos de dez minutos.
GitHub: github.com/Whapi-Cloud/whapi-whatsapp-api-skill
Documentação: support.whapi.cloud/help-desk/ai-tools/agent-skills
Integração MCP: whapi.cloud/mcp-whatsapp-api
