codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/whatsapp-cloud-api/references/api-reference.md

@@ -0,0 +1,566 @@
+# API Reference - WhatsApp Cloud API
+
+Referencia tecnica completa dos endpoints, autenticacao, codigos de erro, rate limits e pricing da WhatsApp Cloud API (Graph API v21.0).
+
+---
+
+## Indice
+
+1. [Autenticacao](#autenticacao)
+2. [Base URL e Headers](#base-url-e-headers)
+3. [Endpoints - Mensagens](#endpoints---mensagens)
+4. [Endpoints - Midia](#endpoints---midia)
+5. [Endpoints - Templates](#endpoints---templates)
+6. [Endpoints - Phone Numbers](#endpoints---phone-numbers)
+7. [Endpoints - Business Profile](#endpoints---business-profile)
+8. [Webhook Events](#webhook-events)
+9. [Codigos de Erro](#codigos-de-erro)
+10. [Rate Limits](#rate-limits)
+11. [Pricing 2026](#pricing-2026)
+12. [Versionamento](#versionamento)
+
+---
+
+## Autenticacao
+
+### Token Temporario (Desenvolvimento)
+
+Obtido no Meta Developers Dashboard. Expira em 24 horas.
+
+### System User Token (Producao)
+
+Token permanente criado via Business Settings:
+1. Business Settings → System Users → Add
+2. Atribuir role "Admin" ao app
+3. Gerar token com permissoes:
+   - `whatsapp_business_messaging` (enviar/receber mensagens)
+   - `whatsapp_business_management` (gerenciar templates, perfil)
+
+### Header de Autenticacao
+
+```
+Authorization: Bearer {ACCESS_TOKEN}
+Content-Type: application/json
+```
+
+---
+
+## Base URL e Headers
+
+```
+Base URL: https://graph.facebook.com/v21.0
+```
+
+Headers obrigatorios em todas as requests:
+```http
+Authorization: Bearer {ACCESS_TOKEN}
+Content-Type: application/json
+```
+
+### IDs Necessarios
+
+| ID                  | Onde encontrar                           | Formato          |
+|---------------------|------------------------------------------|------------------|
+| Phone Number ID     | WhatsApp > API Setup no dashboard        | Numerico         |
+| WABA ID             | WhatsApp > API Setup no dashboard        | Numerico         |
+| App Secret          | App Settings > Basic                      | String hex       |
+| Business ID         | Business Settings > Business Info         | Numerico         |
+
+---
+
+## Endpoints - Mensagens
+
+### Enviar Mensagem
+
+```
+POST /{phone-number-id}/messages
+```
+
+**Request Body (texto):**
+```json
+{
+  "messaging_product": "whatsapp",
+  "recipient_type": "individual",
+  "to": "5511999999999",
+  "type": "text",
+  "text": {
+    "preview_url": false,
+    "body": "Olá! Como posso ajudar?"
+  }
+}
+```
+
+**Response (sucesso):**
+```json
+{
+  "messaging_product": "whatsapp",
+  "contacts": [
+    { "input": "5511999999999", "wa_id": "5511999999999" }
+  ],
+  "messages": [
+    { "id": "wamid.HBgNNTUxMTk5..." }
+  ]
+}
+```
+
+**Tipos suportados no campo `type`:**
+- `text` - Mensagem de texto
+- `template` - Template message
+- `image` - Imagem
+- `document` - Documento
+- `video` - Video
+- `audio` - Audio
+- `sticker` - Sticker
+- `location` - Localizacao
+- `contacts` - Contatos
+- `interactive` - Botoes, listas, flows
+- `reaction` - Reacao com emoji
+
+### Marcar como Lida
+
+```
+POST /{phone-number-id}/messages
+```
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "status": "read",
+  "message_id": "wamid.HBgNNTUxMTk5..."
+}
+```
+
+---
+
+## Endpoints - Midia
+
+### Upload de Midia
+
+```
+POST /{phone-number-id}/media
+Content-Type: multipart/form-data
+```
+
+**Form fields:**
+- `messaging_product`: "whatsapp"
+- `file`: arquivo binario
+- `type`: MIME type (ex: "image/jpeg")
+
+**Response:**
+```json
+{
+  "id": "media_id_aqui"
+}
+```
+
+### Download de Midia
+
+```
+GET /{media-id}
+```
+
+**Response:**
+```json
+{
+  "url": "https://lookaside.fbsbx.com/...",
+  "mime_type": "image/jpeg",
+  "sha256": "hash_aqui",
+  "file_size": 12345,
+  "id": "media_id"
+}
+```
+
+Depois, faca GET na `url` retornada com o mesmo Authorization header para baixar o arquivo.
+
+### Deletar Midia
+
+```
+DELETE /{media-id}
+```
+
+### Limites de Midia
+
+| Tipo      | Formatos Aceitos                    | Tamanho Max |
+|-----------|-------------------------------------|-------------|
+| Image     | JPEG, PNG                           | 5 MB        |
+| Document  | PDF, DOC, DOCX, XLS, XLSX, PPT, TXT| 100 MB      |
+| Video     | MP4, 3GP                            | 16 MB       |
+| Audio     | AAC, AMR, MP3, MP4, OGG             | 16 MB       |
+| Sticker   | WEBP                                | 500 KB      |
+
+---
+
+## Endpoints - Templates
+
+### Listar Templates
+
+```
+GET /{waba-id}/message_templates
+```
+
+**Query parameters:**
+- `limit` - Numero de resultados (default: 25)
+- `status` - Filtrar por status: APPROVED, PENDING, REJECTED
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "name": "hello_world",
+      "status": "APPROVED",
+      "category": "UTILITY",
+      "language": "pt_BR",
+      "components": [
+        {
+          "type": "BODY",
+          "text": "Olá {{1}}, seu pedido {{2}} foi confirmado!"
+        }
+      ],
+      "id": "template_id"
+    }
+  ],
+  "paging": { "cursors": { "before": "...", "after": "..." } }
+}
+```
+
+### Criar Template
+
+```
+POST /{waba-id}/message_templates
+```
+
+```json
+{
+  "name": "order_confirmation",
+  "category": "UTILITY",
+  "language": "pt_BR",
+  "components": [
+    {
+      "type": "HEADER",
+      "format": "TEXT",
+      "text": "Confirmação de Pedido"
+    },
+    {
+      "type": "BODY",
+      "text": "Olá {{1}}, seu pedido #{{2}} foi confirmado! Valor: R$ {{3}}",
+      "example": {
+        "body_text": [["João", "12345", "99,90"]]
+      }
+    },
+    {
+      "type": "FOOTER",
+      "text": "Obrigado por comprar conosco!"
+    },
+    {
+      "type": "BUTTONS",
+      "buttons": [
+        {
+          "type": "URL",
+          "text": "Rastrear Pedido",
+          "url": "https://example.com/track/{{1}}",
+          "example": ["12345"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Deletar Template
+
+```
+DELETE /{waba-id}/message_templates
+```
+
+```json
+{
+  "name": "template_name_to_delete"
+}
+```
+
+**Nota:** Nao e possivel editar um template apos submissao. Para alterar, delete e crie um novo.
+
+**Limite:** Ate 6,000 traducoes de templates por conta.
+
+Para guia completo de gerenciamento de templates, leia `references/template-management.md`.
+
+---
+
+## Endpoints - Phone Numbers
+
+### Listar Numeros
+
+```
+GET /{waba-id}/phone_numbers
+```
+
+**Response:**
+```json
+{
+  "data": [
+    {
+      "verified_name": "Minha Empresa",
+      "code_verification_status": "VERIFIED",
+      "display_phone_number": "+55 11 99999-9999",
+      "quality_rating": "GREEN",
+      "id": "phone_number_id"
+    }
+  ]
+}
+```
+
+### Obter Info do Numero
+
+```
+GET /{phone-number-id}?fields=verified_name,code_verification_status,display_phone_number,quality_rating,messaging_limit_tier
+```
+
+---
+
+## Endpoints - Business Profile
+
+### Obter Perfil
+
+```
+GET /{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,websites,profile_picture_url
+```
+
+### Atualizar Perfil
+
+```
+POST /{phone-number-id}/whatsapp_business_profile
+```
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "about": "Atendimento de Seg a Sex, 8h-18h",
+  "address": "Rua Example, 123 - São Paulo, SP",
+  "description": "Empresa líder em soluções digitais",
+  "email": "contato@empresa.com",
+  "websites": ["https://www.empresa.com"]
+}
+```
+
+---
+
+## Webhook Events
+
+### Estrutura do Payload
+
+```json
+{
+  "object": "whatsapp_business_account",
+  "entry": [
+    {
+      "id": "WABA_ID",
+      "changes": [
+        {
+          "value": {
+            "messaging_product": "whatsapp",
+            "metadata": {
+              "display_phone_number": "5511999999999",
+              "phone_number_id": "PHONE_NUMBER_ID"
+            },
+            "contacts": [
+              { "profile": { "name": "João" }, "wa_id": "5511888888888" }
+            ],
+            "messages": [...],
+            "statuses": [...]
+          },
+          "field": "messages"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Tipos de Mensagem Recebida
+
+| Campo `type`     | Conteudo                    | Campos relevantes               |
+|------------------|-----------------------------|----------------------------------|
+| `text`           | Mensagem de texto           | `text.body`                      |
+| `image`          | Imagem                      | `image.id`, `image.mime_type`    |
+| `document`       | Documento                   | `document.id`, `document.filename`|
+| `video`          | Video                       | `video.id`, `video.mime_type`    |
+| `audio`          | Audio/voz                   | `audio.id`, `audio.mime_type`    |
+| `location`       | Localizacao                 | `location.latitude`, `.longitude`|
+| `contacts`       | Contato compartilhado       | `contacts[].name`, `.phones`     |
+| `interactive`    | Resposta de botao/lista     | `interactive.button_reply.id` ou `interactive.list_reply.id` |
+| `reaction`       | Reacao com emoji            | `reaction.emoji`, `.message_id`  |
+| `sticker`        | Sticker                     | `sticker.id`, `sticker.mime_type`|
+
+### Status Updates
+
+```json
+{
+  "statuses": [
+    {
+      "id": "wamid.HBgNNTUxMTk5...",
+      "status": "delivered",
+      "timestamp": "1234567890",
+      "recipient_id": "5511999999999"
+    }
+  ]
+}
+```
+
+Valores de `status`: `sent` → `delivered` → `read` → `failed`
+
+---
+
+## Codigos de Erro
+
+### Erros Comuns
+
+| Codigo | Mensagem                          | Causa                            | Solucao                              |
+|--------|-----------------------------------|----------------------------------|--------------------------------------|
+| 0      | AuthException                     | Token invalido ou expirado        | Gerar novo token                     |
+| 3      | API Method                        | Metodo HTTP incorreto             | Verificar POST vs GET                |
+| 4      | Too many calls                    | Rate limit excedido               | Implementar retry com backoff        |
+| 10     | Permission denied                 | Token sem permissao necessaria    | Adicionar permissao ao System User   |
+| 100    | Invalid parameter                 | Payload malformado                | Verificar JSON contra documentacao   |
+| 131026 | Message undeliverable             | Numero nao esta no WhatsApp       | Validar numero antes de enviar       |
+| 131047 | Re-engagement message             | Fora da janela de 24h sem template| Usar template message                |
+| 131051 | Unsupported message type          | Tipo de mensagem nao suportado    | Verificar campo `type`               |
+| 131053 | Media upload error                | Arquivo invalido ou muito grande  | Verificar formato e tamanho          |
+| 132000 | Template param count mismatch     | Numero errado de parametros       | Conferir template e parametros       |
+| 132001 | Template does not exist           | Template nao encontrado           | Verificar nome e idioma do template  |
+| 132005 | Template hydration failed         | Erro ao preencher variaveis       | Verificar formato dos parametros     |
+| 133010 | Phone number not registered       | Numero nao verificado             | Completar verificacao OTP            |
+| 135000 | Generic error                     | Erro interno do WhatsApp          | Retry apos alguns segundos           |
+
+### Tratamento de Erros
+
+```typescript
+async function sendWithRetry(payload: any, maxRetries = 3): Promise<any> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await axios.post(
+        `${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`,
+        payload,
+        { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } }
+      );
+      return response.data;
+    } catch (error: any) {
+      const errorCode = error.response?.data?.error?.code;
+      const errorMessage = error.response?.data?.error?.message;
+
+      // Erros que nao devem ser retentados
+      if ([100, 131026, 131051, 132000, 132001].includes(errorCode)) {
+        throw new Error(`WhatsApp API Error ${errorCode}: ${errorMessage}`);
+      }
+
+      // Rate limit ou erro temporario - retry com backoff
+      if (attempt < maxRetries && [4, 135000].includes(errorCode)) {
+        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
+        await new Promise(resolve => setTimeout(resolve, delay));
+        continue;
+      }
+
+      throw error;
+    }
+  }
+}
+```
+
+---
+
+## Rate Limits
+
+### Throughput (Mensagens por Segundo)
+
+| Tier              | Limite          |
+|-------------------|-----------------|
+| Standard          | 80 msg/s        |
+| Unlimited tier    | 1,000 msg/s     |
+
+### Conversas por 24 Horas
+
+| Tier         | Limite/24h | Como alcancar                         |
+|--------------|-----------|----------------------------------------|
+| Inicial      | 250       | Conta nova ou nao verificada           |
+| Tier 1       | 1,000     | 50%+ do limite por 7 dias + quality ok |
+| Tier 2       | 10,000    | 50%+ do limite por 7 dias + quality ok |
+| Tier 3       | 100,000   | 50%+ do limite por 7 dias + quality ok |
+| Unlimited    | Ilimitado | 50%+ do limite por 7 dias + quality ok |
+
+**Importante:** Limites sao por Business Portfolio (desde outubro 2025), nao por numero.
+
+### Outros Limites
+
+- Templates: 6,000 traducoes por conta
+- Botoes interativos: max 3 por mensagem
+- Lista interativa: max 10 opcoes, max 3 secoes
+- Texto: max 4,096 caracteres
+- Template body: max 1,600 caracteres
+- Webhooks: responder 200 em ate 5 segundos
+
+---
+
+## Pricing 2026
+
+Desde julho 2025, o modelo e **por mensagem** (nao mais por conversa).
+
+### Custos por Categoria
+
+| Categoria      | Faixa de Preco      | Desconto Volume | Janela 24h    |
+|----------------|---------------------|-----------------|---------------|
+| Marketing      | $0.025 - $0.1365    | Nao             | Cobrado       |
+| Utility        | $0.004 - $0.0456    | Sim             | GRATIS        |
+| Authentication | $0.004 - $0.0456    | Sim             | Cobrado       |
+| Service        | GRATIS              | N/A             | GRATIS        |
+
+### Exemplos por Regiao (Marketing)
+
+| Regiao          | Custo/msg |
+|-----------------|-----------|
+| Brasil          | ~$0.05    |
+| India           | ~$0.01    |
+| EUA/Canada      | ~$0.025   |
+| Europa Ocidental| ~$0.10+   |
+
+### Janela de 24 Horas
+
+- Abre quando o cliente envia uma mensagem
+- Durante a janela: templates de **utility** sao GRATIS
+- Service messages (respostas) sao SEMPRE gratis
+- Marketing e authentication sao cobrados mesmo na janela
+
+### Mudancas Janeiro 2026
+
+- Franca e Egito: reducao nos custos de marketing
+- India: aumento nos custos de marketing
+- America do Norte: reducao em utility e authentication
+
+---
+
+## Versionamento
+
+### Versao Atual
+
+**Graph API v21.0** (lancada janeiro 2026)
+
+### Compatibilidade
+
+- Meta mantem backward compatibility por pelo menos 12 meses
+- Versoes antigas recebem aviso de deprecacao antes da remocao
+- Sempre especifique a versao na URL: `https://graph.facebook.com/v21.0/`
+
+### Mudancas Planejadas 2026
+
+| Feature                   | Timeline | Descricao                                      |
+|---------------------------|----------|-------------------------------------------------|
+| BSUID                     | 2026     | Business-Scoped User ID substitui phone numbers |
+| Usernames                 | 2026     | WhatsApp introduz usernames para privacidade     |
+| Tier removal (2K/10K)     | Q2 2026  | Limite imediato de 100K apos verificacao         |
+| Business Portfolio Pacing | Q1 2026  | Pausa automatica de campanhas baseada em feedback|
+
+### Boas Praticas de Versionamento
+
+- Monitore o blog de desenvolvedores da Meta para mudancas
+- Teste em sandbox antes de atualizar versao em producao
+- Use variaveis de ambiente para a versao da API (facil rollback)
+- Mantenha logs de chamadas para debug de compatibilidade