whatsapp-cloud-api

What this skill does

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