メニュー
Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/BEKO2210/Firstbrain --skill whatsapp-cloud-apiコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Arquitecto de Soluciones Principal y Consultor Tecnológico de Andru.ia. Diagnostica y traza la hoja de ruta óptima para proyectos de IA en español.
Security audit, hardening, threat modeling (STRIDE/PASTA), Red/Blue Team, OWASP checks, code review, incident response, and infrastructure security for any project.
Ingeniero de Sistemas de Andru.ia. Diseña, redacta y despliega nuevas habilidades (skills) dentro del repositorio siguiendo el Estándar de Diamante.
| name | whatsapp-cloud-api |
| description | Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python. |
| type | skill |
| created | 2026-02-27T00:00:00.000Z |
| domain | communication-content |
| category | social-media |
| risk | critical |
| source | community |
| tags | ["skill","communication-content","social-media","whatsapp","cloud","api"] |
Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python.
Skill para implementar integracoes profissionais com WhatsApp Business usando a Cloud API oficial da Meta. Suporta Node.js/TypeScript e Python.
A WhatsApp Cloud API e a API oficial da Meta para envio e recebimento de mensagens via WhatsApp Business. Desde outubro 2025, e a unica opcao suportada (a API On-Premises foi descontinuada).
Versao da API: Graph API v21.0 (2026)
Base URL: https://graph.facebook.com/v21.0/{phone-number-id}/messages
Autenticacao: Bearer Token (System User Token para producao)
Pricing 2026 (por mensagem):
| Categoria | Custo | Quando cobrado |
|---|---|---|
| Marketing | $0.025-$0.1365 | Campanhas, promocoes |
| Utility | $0.004-$0.0456 | Confirmacoes de pedido, atualizacoes |
| Authentication | $0.004-$0.0456 | OTP, reset de senha |
| Service | GRATIS | Resposta dentro da janela de 24h |
Pre-requisitos:
Se o usuario nao tem conta Meta Business, leia references/setup-guide.md para o guia completo de setup do zero.
Use esta arvore para determinar o proximo passo:
O usuario precisa de setup inicial?
├── SIM → Leia references/setup-guide.md
└── NAO → Qual linguagem?
├── Node.js/TypeScript
└── Python
→ O que quer fazer?
├── Enviar mensagens → Secao "Tipos de Mensagem" abaixo
├── Receber mensagens → Secao "Webhooks" abaixo
├── Automatizar atendimento → Secao "Automacao" abaixo
├── WhatsApp Flows / Commerce → Secao "Features Avancados" abaixo
├── Gerenciar templates → references/template-management.md
└── Compliance / limites → Secao "Compliance & Quality" abaixo
Para iniciar um projeto do zero com boilerplate pronto, use o script:
python scripts/setup_project.py --language nodejs --path ./meu-projeto
## Ou
python scripts/setup_project.py --language python --path ./meu-projeto
WHATSAPP_TOKEN=seu_access_token_aqui
PHONE_NUMBER_ID=seu_phone_number_id
WABA_ID=seu_whatsapp_business_account_id
APP_SECRET=seu_app_secret
VERIFY_TOKEN=token_customizado_para_webhook
Node.js/TypeScript:
import axios from 'axios';
const GRAPH_API = 'https://graph.facebook.com/v21.0';
async function sendText(to: string, message: string) {
const response = await axios.post(
`${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`,
{
messaging_product: 'whatsapp',
to,
type: 'text',
text: { body: message }
},
{ headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } }
);
return response.data; // { messaging_product, contacts, messages: [{ id }] }
}
Python:
import httpx
import os
GRAPH_API = "https://graph.facebook.com/v21.0"
async def send_text(to: str, message: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.post(
f"{GRAPH_API}/{os.environ['PHONE_NUMBER_ID']}/messages",
json={
"messaging_product": "whatsapp",
"to": to,
"type": "text",
"text": {"body": message}
},
headers={"Authorization": f"Bearer {os.environ['WHATSAPP_TOKEN']}"}
)
return response.json() # {"messaging_product", "contacts", "messages": [{"id"}]}
Templates sao a unica forma de iniciar conversa com um cliente. Devem ser aprovados pela WhatsApp antes do uso.
{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "template",
"template": {
"name": "hello_world",
"language": { "code": "pt_BR" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "João" }
]
}
]
}
}
Use o script de teste para validar:
python scripts/send_test_message.py --to 5511999999999 --message "Teste de integracao"
| Tipo | Uso | Limite |
|---|---|---|
| Text | Mensagens simples de texto | 4096 chars |
| Template | Iniciar conversa / fora da janela 24h | 1600 chars body |
| Image | Fotos e imagens | 5MB |
| Document | PDFs, planilhas, docs | 100MB |
| Video | Videos | 16MB |
| Audio | Mensagens de voz | 16MB |
| Interactive Button | Botoes de resposta rapida | Max 3 botoes |
| Interactive List | Menu com opcoes em secoes | Max 10 opcoes |
| Location | Compartilhar localizacao | lat/long |
| Contact | Compartilhar contato | vCard format |
| Reaction | Reagir com emoji a mensagem | 1 emoji |
Exemplo - Botoes interativos (Node.js):
async function sendButtons(to: string, body: string, buttons: Array<{id: string, title: string}>) {
return axios.post(`${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`, {
messaging_product: 'whatsapp',
to,
type: 'interactive',
interactive: {
type: 'button',
body: { text: body },
action: {
buttons: buttons.map(b => ({
type: 'reply',
reply: { id: b.id, title: b.title }
}))
}
}
}, { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } });
}
// Uso:
await sendButtons('5511999999999', 'Como posso ajudar?', [
{ id: 'suporte', title: 'Suporte' },
{ id: 'vendas', title: 'Vendas' },
{ id: 'info', title: 'Informacoes' }
]);
Para exemplos completos de todos os tipos em Node.js e Python, leia references/message-types.md.
Webhooks permitem receber mensagens e atualizacoes de status em tempo real.
Quando voce configura o webhook no Meta Developers, a Meta envia um GET para verificar:
// Node.js (Express)
app.get('/webhook', (req, res) => {
const mode = req.query['hub.mode'];
const token = req.query['hub.verify_token'];
const challenge = req.query['hub.challenge'];
if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
res.status(200).send(challenge);
} else {
res.sendStatus(403);
}
});
Toda notificacao de webhook vem assinada no header X-Hub-Signature-256. Valide SEMPRE antes de processar:
import crypto from 'crypto';
function validateSignature(rawBody: Buffer, signature: string): boolean {
const expectedSig = crypto
.createHmac('sha256', process.env.APP_SECRET!)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(`sha256=${expectedSig}`),
Buffer.from(signature)
);
}
Importante: Usar crypto.timingSafeEqual (Node.js) ou hmac.compare_digest (Python) para prevenir timing attacks. Nunca use comparacao simples de strings.
Requisitos:
Para setup completo com exemplos Node.js e Python, leia references/webhook-setup.md.
Use botoes ou listas para criar um menu de opcoes na primeira interacao:
## Python - Menu Com Lista Interativa
async def send_main_menu(to: str):
await send_interactive_list(
to=to,
header="Bem-vindo!",
body="Selecione o que precisa:",
button_text="Ver opcoes",
sections=[{
"title": "Atendimento",
"rows": [
{"id": "suporte", "title": "Suporte Tecnico", "description": "Ajuda com problemas"},
{"id": "vendas", "title": "Vendas", "description": "Conhecer nossos produtos"},
{"id": "financeiro", "title": "Financeiro", "description": "Boletos e pagamentos"},
]
}]
)
Gerencie conversas com uma maquina de estados. Cada cliente tem um estado atual que determina como a proxima mensagem sera processada:
INICIO → MENU_PRINCIPAL → SUPORTE → AGUARDANDO_DETALHES → ESCALACAO_HUMANO
→ VENDAS → CATALOGO → CHECKOUT
→ FINANCEIRO → SEGUNDA_VIA_BOLETO
Combine WhatsApp com Claude para respostas inteligentes:
Para padroes completos de automacao, leia references/automation-patterns.md.
Formularios interativos multi-tela dentro do WhatsApp. O cliente preenche campos sem sair do app. Definidos em JSON com screens, components e actions.
Use cases: cadastros, agendamentos, pesquisas NPS, selecao de produtos.
Ate 500 produtos no catalogo WhatsApp. Envie mensagens de produto individual ou multi-produto com checkout in-app.
Crie, liste e delete templates programaticamente. Ate 6000 traducoes por conta. Aprovacao em minutos.
Broadcasting unidirecional para subscribers ilimitados. Localizado na aba "Atualizacoes" do WhatsApp.
Anuncios no Facebook/Instagram com botao que abre conversa no WhatsApp. 99% de taxa de abertura.
Rastreie entrega: pending → server → device → read. Receba via webhook de status updates.
Para detalhes completos de features avancados, leia references/advanced-features.md.
Para gerenciamento de templates via API, leia references/template-management.md.
O WhatsApp monitora a qualidade das suas mensagens e atribui um rating:
| Rating | Significado | Acao |
|---|---|---|
| Verde | Boa qualidade, poucos bloqueios | Manter — elegivel para upgrade |
| Amarelo | Qualidade media, atencao necessaria | Revisar conteudo e frequencia |
| Vermelho | Qualidade baixa, risco de suspensao | Acao imediata: reduzir volume |
Sinais positivos: Alta taxa de resposta, engajamento, poucos bloqueios Sinais negativos: Bloqueios, reports de spam, baixo engajamento
Desde outubro 2025, limites sao por Business Portfolio (nao por numero):
| Tier | Conversas/24h | Como alcancar |
|---|---|---|
| Inicial | 250 | Conta nova / nao verificada |
| Tier 1 | 1,000 | Auto-upgrade: 50%+ do limite por 7 dias |
| Tier 2 | 10,000 | Auto-upgrade: 50%+ do limite por 7 dias |
| Tier 3 | 100,000 | Auto-upgrade: 50%+ do limite por 7 dias |
| Unlimited | Ilimitado | Auto-upgrade: 50%+ do limite por 7 dias |
Mudancas 2026: Tiers 2K e 10K serao removidos. Apos verificacao de negocio, limite imediato de 100K.
Para guia completo de compliance, leia references/compliance.md.
| Problema | Causa Provavel | Solucao |
|---|---|---|
| 401 Unauthorized | Token expirado ou invalido | Gerar novo System User Token |
| 400 Bad Request | Payload malformado | Verificar JSON contra exemplos |
| Template rejeitado | Conteudo viola politicas | Revisar e resubmeter com alteracoes |
| Webhook nao recebe | URL invalida ou sem HTTPS | Usar ngrok (dev) ou certificado SSL (prod) |
| Rate limit exceeded | Ultrapassou 80 msg/s | Implementar queue com retry |
| Quality rating baixo | Muitos bloqueios/reports | Reduzir volume, melhorar conteudo |
| Mensagem nao entregue | Numero invalido ou nao no WhatsApp | Validar numero antes de enviar |
| Numero nao verificado | OTP nao completado | Repetir verificacao via SMS ou ligacao |
Para validar sua configuracao:
python scripts/validate_config.py
| Arquivo | Quando ler |
|---|---|
references/setup-guide.md | Setup inicial — criar conta Meta, configurar API |
references/message-types.md | Exemplos completos de todos os tipos de mensagem |
references/webhook-setup.md | Configurar webhooks com seguranca HMAC |
references/automation-patterns.md | Chatbot, filas, state machine, integracao IA |
references/compliance.md | LGPD/GDPR, opt-in, quality rating, tier system |
references/api-reference.md | Endpoints, erros, rate limits, pricing 2026 |
references/advanced-features.md | Flows, Commerce, Channels, Ads, Status Tracking |
references/template-management.md | CRUD de templates via API |
| Script | O que faz |
|---|---|
scripts/setup_project.py | Cria projeto com boilerplate (Node.js ou Python) |
scripts/validate_config.py | Valida credenciais e conexao com a API |
scripts/send_test_message.py | Envia mensagem teste para validar setup |
| Diretorio | Conteudo |
|---|---|
assets/boilerplate/nodejs/ | Projeto TypeScript/Express completo |
assets/boilerplate/python/ | Projeto Python/Flask completo |
assets/examples/ | Exemplos de payloads JSON (templates, webhooks, flows) |
instagram - Complementary skill for enhanced analysissocial-orchestrator - Complementary skill for enhanced analysistelegram - Complementary skill for enhanced analysisassets/boilerplate/nodejs/.env.exampleassets/boilerplate/python/.env.exampleassets/boilerplate/nodejs/package.json, ...)assets/boilerplate/python/app.py, ...)assets/boilerplate/nodejs/src/index.ts, ...)assets/boilerplate/python/requirements.txt