codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/whatsapp-cloud-api/SKILL.md

@@ -0,0 +1,488 @@
+---
+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.
+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

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/.env.example

@@ -0,0 +1,20 @@
+# WhatsApp Cloud API Configuration
+# Obtenha estes valores em: https://developers.facebook.com > App > WhatsApp > API Setup
+
+# Token de acesso (System User Token para producao)
+WHATSAPP_TOKEN=your_access_token_here
+
+# ID do numero de telefone (encontrado no API Setup)
+PHONE_NUMBER_ID=your_phone_number_id
+
+# ID da conta WhatsApp Business (encontrado no API Setup)
+WABA_ID=your_waba_id
+
+# App Secret (encontrado em App Settings > Basic)
+APP_SECRET=your_app_secret
+
+# Token customizado para verificacao do webhook (voce define)
+VERIFY_TOKEN=your_custom_verify_token
+
+# Porta do servidor
+PORT=3000

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "whatsapp-cloud-api",
+  "version": "1.0.0",
+  "description": "WhatsApp Cloud API integration with Express and TypeScript",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "dotenv": "^16.4.0",
+    "express": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/src/index.ts

@@ -0,0 +1,125 @@
+import express from 'express';
+import dotenv from 'dotenv';
+import { WhatsAppClient } from './whatsapp-client';
+import { TemplateManager } from './template-manager';
+import {
+  validateHMAC,
+  rawBodyMiddleware,
+  handleWebhookVerification,
+  parseWebhookPayload,
+  extractMessageContent,
+} from './webhook-handler';
+import { WhatsAppConfig, IncomingMessage, StatusUpdate } from './types';
+
+dotenv.config();
+
+// === Configuration ===
+
+const config: WhatsAppConfig = {
+  token: process.env.WHATSAPP_TOKEN!,
+  phoneNumberId: process.env.PHONE_NUMBER_ID!,
+  wabaId: process.env.WABA_ID!,
+  appSecret: process.env.APP_SECRET!,
+  verifyToken: process.env.VERIFY_TOKEN!,
+};
+
+const whatsapp = new WhatsAppClient(config);
+const templates = new TemplateManager(config);
+
+// === Express Setup ===
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Raw body capture MUST come before express.json()
+app.use(express.json({ verify: rawBodyMiddleware }));
+
+// === Webhook Routes ===
+
+// GET - Webhook verification (Meta sends challenge)
+app.get('/webhook', handleWebhookVerification(config.verifyToken));
+
+// POST - Receive messages and status updates
+app.post('/webhook', validateHMAC(config.appSecret), async (req, res) => {
+  // Respond 200 immediately (WhatsApp requires response within 5 seconds)
+  res.sendStatus(200);
+
+  try {
+    const { messages, statuses } = parseWebhookPayload(req.body);
+
+    for (const message of messages) {
+      await handleIncomingMessage(message);
+    }
+
+    for (const status of statuses) {
+      handleStatusUpdate(status);
+    }
+  } catch (error) {
+    console.error('Error processing webhook:', error);
+  }
+});
+
+// === Message Handler ===
+
+async function handleIncomingMessage(message: IncomingMessage): Promise<void> {
+  const from = message.from;
+  const content = extractMessageContent(message);
+
+  console.log(`Message from ${from}: [${content.type}] ${content.text || content.buttonId || ''}`);
+
+  // Mark as read
+  await whatsapp.markAsRead(message.id);
+
+  // TODO: Implement your message handling logic here
+  // Example: Echo back the message
+  switch (content.type) {
+    case 'text':
+      await whatsapp.sendText(from, `Recebi sua mensagem: "${content.text}"`);
+      break;
+
+    case 'button':
+      await whatsapp.sendText(from, `Voce selecionou: ${content.text}`);
+      break;
+
+    case 'list':
+      await whatsapp.sendText(from, `Voce escolheu: ${content.text}`);
+      break;
+
+    case 'image':
+    case 'document':
+    case 'video':
+    case 'audio':
+      await whatsapp.sendText(from, `Recebi sua midia (${content.type}).`);
+      break;
+
+    default:
+      await whatsapp.sendText(from, 'Desculpe, nao entendi. Como posso ajudar?');
+      break;
+  }
+}
+
+// === Status Handler ===
+
+function handleStatusUpdate(status: StatusUpdate): void {
+  console.log(`Status update: ${status.id} -> ${status.status}`);
+
+  if (status.status === 'failed') {
+    console.error(`Message delivery failed:`, status.errors);
+  }
+}
+
+// === Health Check ===
+
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+// === Start Server ===
+
+app.listen(PORT, () => {
+  console.log(`WhatsApp webhook server running on port ${PORT}`);
+  console.log(`Webhook URL: http://localhost:${PORT}/webhook`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+});
+
+export { whatsapp, templates };