WhatsApp Cloud API - Integração Profissional

Visão Geral

Integração com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automação de atendimento. Boilerplates Node.js e Python.

Quando Usar Esta Habilidade

• Quando o usuário mencionar "whatsapp" ou tópicos relacionados
• Quando o usuário mencionar "whatsapp business" ou tópicos relacionados
• Quando o usuário mencionar "api whatsapp" ou tópicos relacionados
• Quando o usuário mencionar "chatbot whatsapp" ou tópicos relacionados
• Quando o usuário mencionar "mensagem whatsapp" ou tópicos relacionados
• Quando o usuário mencionar "template whatsapp" ou tópicos relacionados

Não Usar Esta Habilidade Quando

• A tarefa não está relacionada à API Cloud do WhatsApp
• Uma ferramenta mais simples e específica pode lidar com a solicitação
• O usuário precisa de assistência de propósito geral sem conhecimento de domínio

Como Funciona

Habilidade para implementar integrações profissionais com WhatsApp Business usando a API Cloud oficial da Meta. Suporta Node.js/TypeScript e Python.

Visão Geral

A WhatsApp Cloud API é a API oficial da Meta para envio e recebimento de mensagens via WhatsApp Business. A partir de outubro de 2025, é a única opção suportada (a API On-Premises foi descontinuada).

Versão da API: Graph API v21.0 (2026) URL Base: https://graph.facebook.com/v21.0/{phone-number-id}/messages Autenticação: Bearer Token (System User Token para produção)

Preços 2026 (por mensagem):

Pré-requisitos:

• Conta Meta Business Suite (gratuita)
• App no Meta for Developers com produto WhatsApp
• Número de telefone verificado
• System User Token (permanente)

Se o usuário não tiver uma conta Meta Business, leia references/setup-guide.md para o guia completo de configuração do zero.

Árvore de Decisão

Use esta árvore para determinar o próximo 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 Variáveis 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']}"}
        )

…