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:

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

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:

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:

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.

{
  "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:

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):

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:

// 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:

import crypto from 'crypto';

function validateSignature

whatsapp-cloud-api

Como adicionar

Cole no README do seu repo

Skills relacionadas

frontend-design

mcp-builder

webapp-testing

web-artifacts-builder

Receba novas skills de Design e Frontend toda segunda