whatsapp-cloud-api

# 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.