--- name: whatsapp-cloud-api-108bb7d56aa2 description: Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python. risk: critical source: community date_added: '2026-03-06' author: renat tags: - messaging - whatsapp - meta - webhooks tools: - claude-code - antigravity - cursor - gemini-cli - codex-cli --- # WhatsApp Cloud API - Integracao Profissional ## Overview Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python. ## When to Use This Skill - When the user mentions "whatsapp" or related topics - When the user mentions "whatsapp business" or related topics - When the user mentions "api whatsapp" or related topics - When the user mentions "chatbot whatsapp" or related topics - When the user mentions "mensagem whatsapp" or related topics - When the user mentions "template whatsapp" or related topics ## Do Not Use This Skill When - The task is unrelated to whatsapp cloud api - A simpler, more specific tool can handle the request - The user needs general-purpose assistance without domain expertise ## How It Works Skill para implementar integracoes profissionais com WhatsApp Business usando a Cloud API oficial da Meta. Suporta Node.js/TypeScript e Python. ## Overview 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:** - Conta Meta Business Suite (gratuita) - App no Meta for Developers com produto WhatsApp - Numero de telefone verificado - System User Token (permanente) Se o usuario nao tem conta Meta Business, leia `references/setup-guide.md` para o guia completo de setup do zero. --- ## Decision Tree 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: ```bash python scripts/setup_project.py --language nodejs --path ./meu-projeto ## Ou python scripts/setup_project.py --language python --path ./meu-projeto ``` --- ## 1. Configurar Variaveis De Ambiente ```env 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 ``` ## 2. Enviar Mensagem De Texto Simples **Node.js/TypeScript:** ```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:** ```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"}]} ``` ## 3. Enviar Template Message (Fora Da Janela De 24H) Templates sao a unica forma de iniciar conversa com um cliente. Devem ser aprovados pela WhatsApp antes do uso. ```json { "messaging_product": "whatsapp", "to": "5511999999999", "type": "template", "template": { "name": "hello_world", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "João" } ] } ] } } ``` ## 4. Verificar Entrega Use o script de teste para validar: ```bash python scripts/send_test_message.py --to 5511999999999 --message "Teste de integracao" ``` --- ## Tipos De Mensagem | 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):** ```typescript 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 Webhooks permitem receber mensagens e atualizacoes de status em tempo real. ## Verificacao (Get) - Obrigatorio Quando voce configura o webhook no Meta Developers, a Meta envia um GET para verificar: ```typescript // 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); } }); ``` ## Recebimento (Post) - Com Seguranca Hmac-Sha256 Toda notificacao de webhook vem assinada no header `X-Hub-Signature-256`. Valide SEMPRE antes de processar: ```typescript 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. ## Eventos Recebidos - **messages** - Mensagem do cliente (texto, midia, botao, localizacao) - **statuses** - Atualizado de status (sent → delivered → read) - **errors** - Erros de entrega **Requisitos:** - Endpoint HTTPS com certificado SSL valido - Responder com HTTP 200 em ate 5 segundos - Dev: use ngrok para teste local **Para setup completo com exemplos Node.js e Python**, leia `references/webhook-setup.md`. --- ## Menu Principal Interativo Use botoes ou listas para criar um menu de opcoes na primeira interacao: ```python ## 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"}, ] }] ) ``` ## State Machine Para Fluxos 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 ``` ## Janela De 24 Horas - **Dentro da janela (24h apos ultima mensagem do cliente):** Pode enviar qualquer tipo de mensagem gratuitamente - **Fora da janela:** Apenas template messages (cobradas por categoria) ## Integracao Com Ia (Claude Api) Combine WhatsApp com Claude para respostas inteligentes: 1. Receba mensagem via webhook 2. Envie para Claude API com contexto da conversa 3. Retorne resposta via WhatsApp 4. Mantenha escalacao para humano disponivel **Para padroes completos de automacao**, leia `references/automation-patterns.md`. --- ## Whatsapp Flows 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. ## Commerce & Catalogo Ate 500 produtos no catalogo WhatsApp. Envie mensagens de produto individual ou multi-produto com checkout in-app. ## Template Management Api Crie, liste e delete templates programaticamente. Ate 6000 traducoes por conta. Aprovacao em minutos. ## Whatsapp Channels Broadcasting unidirecional para subscribers ilimitados. Localizado na aba "Atualizacoes" do WhatsApp. ## Click-To-Whatsapp Ads Anuncios no Facebook/Instagram com botao que abre conversa no WhatsApp. 99% de taxa de abertura. ## Status Tracking 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`. --- ## Checklist Essencial - [ ] Opt-in explicito obtido antes de enviar mensagens - [ ] Mecanismo de opt-out implementado (keyword "SAIR" ou "STOP") - [ ] Registro de consentimento com timestamp, metodo e proposito - [ ] Conteudo dentro das politicas do WhatsApp (sem spam, sem conteudo proibido) - [ ] LGPD/GDPR compliance (base legal definida, direitos do titular) - [ ] Frequencia de mensagens adequada (nao excessiva) - [ ] Templates aprovados antes do uso - [ ] Verificacao de negocio completa (para limites maiores) ## Quality Rating 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 ## Tier System (Limites De Mensagem) 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`. --- ## Troubleshooting | 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: ```bash python scripts/validate_config.py ``` --- ## Referencias (Leia Conforme Necessidade) | 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 | ## Scripts | 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 | ## Boilerplate | 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) | ## Best Practices - Provide clear, specific context about your project and requirements - Review all suggestions before applying them to production code - Combine with other complementary skills for comprehensive analysis ## Common Pitfalls - Using this skill for tasks outside its domain expertise - Applying recommendations without understanding your specific context - Not providing enough project context for accurate analysis ## Related Skills - `instagram` - Complementary skill for enhanced analysis - `social-orchestrator` - Complementary skill for enhanced analysis - `telegram` - Complementary skill for enhanced analysis ## Limitations - Use this skill only when the task clearly matches the scope described above. - Do not treat the output as a substitute for environment-specific validation, testing, or expert review. - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing. --- Source attribution: renat Original contribution (preserved): https://github.com/DorianGallo/antigravity-awesome-skills-local/blob/1d91757e302534e71b833e8b5e3b57046d7142f0/skills/whatsapp-cloud-api/SKILL.md License: MIT + CC-BY-4.0 License information: https://creativecommons.org/licenses/by/4.0/ Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Antigravity User Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Creative Commons Attribution 4.0 International (CC BY 4.0) This file clarifies the license for original non-code repository content. - Original code and tooling remain licensed under the MIT License in `LICENSE`. - Original documentation and other non-code written content are licensed under the Creative Commons Attribution 4.0 International license unless a more specific upstream notice says otherwise. - Third-party attributions, upstream licenses, and exceptions are tracked in `docs/sources/sources.md`. Canonical license URL: https://creativecommons.org/licenses/by/4.0/ Review the full license text at the canonical URL before reuse. # Mega AI Hub resource metadata Creator / publisher: renat Original contribution (preserved): https://github.com/DorianGallo/antigravity-awesome-skills-local/blob/1d91757e302534e71b833e8b5e3b57046d7142f0/skills/whatsapp-cloud-api/SKILL.md Attribution basis: Explicit original-content license; package is not listed among upstream exceptions Fields of work: Sales, Marketing Roles: Customer Success Manager, Growth Marketer, Product Marketer, Social Media Manager, Influencer Marketer Specialties: API Tools: Whatsapp Business Cloud Api, Nodejs, Python Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 8601f5a2d5c9fd13e172bf90f4077ec679a7bd81208e0c546b7c713a18d76f56