Skip to content

Configuração WhatsApp Cloud API (Meta - Oficial)

Guia completo para integrar o WhatsApp oficial do Meta ao ifriend-agents usando WhatsApp Cloud API.

📋 Visão Geral

WhatsApp Cloud API é a solução oficial do Meta/Facebook para empresas se comunicarem com clientes via WhatsApp de forma programática.

Vantagens: - ✅ API oficial com SLA e suporte - ✅ Estabilidade garantida - ✅ Features oficiais primeiro - ✅ Conformidade regulatória

Desvantagens: - ❌ Requer aprovação do Meta - ❌ Custos após limite gratuito - ❌ Setup mais complexo - ❌ Requer Meta Business Account

🎯 Pré-requisitos

  • Meta Business Account
  • Facebook App configurada
  • Número de telefone para WhatsApp Business
  • Cartão de crédito (para verificação, tier gratuito disponível)

🚀 Setup Passo a Passo

1. Criar Meta Business Account

  1. Acesse Meta Business Suite
  2. Clique em Create Account
  3. Preencha informações da empresa
  4. Verifique email

2. Criar App WhatsApp Business

  1. Acesse Meta for Developers
  2. Vá em My Apps → Create App
  3. Escolha Business como tipo
  4. Preencha:
  5. App name: ifriend-whatsapp
  6. Contact email: seu-email@empresa.com
  7. Business Account: Selecione a conta criada
  8. Clique em Create App

3. Adicionar WhatsApp Product

  1. No dashboard da app, encontre WhatsApp
  2. Clique em Set up
  3. Selecione sua Business Account
  4. Clique em Continue

4. Configurar Phone Number

Opção A: Usar número de teste (desenvolvimento)

O Meta fornece um número de teste: - Já está configurado automaticamente - Pode enviar para até 5 números cadastrados - Limite de 250 mensagens/dia

Adicionar números de teste: 1. No painel WhatsApp → API Setup 2. Em To, clique em Manage phone number list 3. Adicione números (formato: +5511999999999) 4. Cada número receberá código de verificação no WhatsApp

Opção B: Usar seu próprio número (produção)

  1. No painel WhatsApp → Phone Numbers
  2. Clique em Add phone number
  3. Selecione Own number
  4. Siga processo de verificação:
  5. SMS ou chamada de voz
  6. Insira código recebido
  7. Aguarde aprovação (geralmente algumas horas)

5. Gerar Access Token Permanente

⚠️ Importante: Token temporário expira em 24h. Gere um permanente!

Gerar token permanente:

  1. No painel WhatsApp → API Setup
  2. Em Temporary access token, clique no token para copiar (use apenas para testes)
  3. Para token permanente:
  4. Vá em Tools → Graph API Explorer
  5. Selecione sua app
  6. Em User or Page, selecione WhatsApp Business Account
  7. Permissions: whatsapp_business_messaging, whatsapp_business_management
  8. Clique em Generate Access Token
  9. IMPORTANTE: Salve em lugar seguro!

Alternativa via System User:

  1. Business Settings → System Users
  2. Crie um System User
  3. Adicione Assets → Selecione sua WhatsApp Business Account
  4. Gere token com validade longa (60 dias ou sem expiração)

6. Obter Phone Number ID

No painel WhatsApp → API Setup: - Copie o Phone number ID (não é o número de telefone!) - Formato: 123456789012345

7. Configurar Webhook

Gerar Verify Token

Crie um token secreto qualquer: 

# Exemplo de geração
openssl rand -base64 32
# Resultado: abc123def456xyz789

Configurar no Meta

  1. No painel WhatsApp → Configuration → Webhook
  2. Clique em Edit
  3. Preencha:
  4. Callback URL: https://seu-dominio.com/webhook/whatsapp/official/webhook
  5. Verify token: (o token que você gerou acima)
  6. Clique em Verify and save

⚠️ O Meta fará uma request GET com: 

GET /webhook/whatsapp/official/webhook?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=12345

Seu servidor deve retornar 12345 (o challenge) em texto plano.

Subscrever a Eventos

Após verificar o webhook: 1. Em Webhook fields, selecione: - ✅ messages (obrigatório) 2. Salve

8. Obter App Secret (Opcional mas Recomendado)

Para validar assinatura dos webhooks:

  1. Settings → Basic
  2. Copie App Secret
  3. Configure em WHATSAPP_OFFICIAL_APP_SECRET

⚙️ Configuração ifriend-agents

Adicione ao seu .env:

# WhatsApp Official (Meta Cloud API)
WHATSAPP_OFFICIAL_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxx
WHATSAPP_OFFICIAL_PHONE_ID=123456789012345
WHATSAPP_OFFICIAL_VERIFY_TOKEN=abc123def456xyz789
WHATSAPP_OFFICIAL_API_VERSION=v19.0
WHATSAPP_OFFICIAL_APP_SECRET=xxxxxxxxxxxxx  # Opcional

# Habilitar WhatsApp Official
MESSAGING_PLATFORMS=telegram,whatsapp_official

🧪 Testar Integração

1. Verificar Conexão

python tests/test_whatsapp_official.py

2. Enviar Mensagem de Teste

Com número de teste configurado:

export WHATSAPP_TEST_NUMBER=5511999999999
python tests/test_whatsapp_official.py

3. Testar Webhook

Envie mensagem do WhatsApp para o número configurado e verifique logs:

# Nos logs do servidor
📨 Mensagem recebida de whatsapp_official: user=5511999999999, text='Teste'...

📡 Formato do Webhook

GET - Verificação Inicial

GET /webhook/whatsapp/official/webhook?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=1234567890

Resposta esperada: 1234567890 (texto plano)

POST - Mensagem Recebida

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "5511999999999",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{
          "profile": {"name": "João Silva"},
          "wa_id": "5511999999999"
        }],
        "messages": [{
          "from": "5511999999999",
          "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYIDNFQjBBQkMxMjM0NTY3ODk",
          "timestamp": "1706545234",
          "type": "text",
          "text": {
            "body": "Olá, preciso de ajuda!"
          }
        }]
      },
      "field": "messages"
    }]
  }]
}

🎨 Tipos de Mensagens Suportadas

Texto Simples

await adapter.send_message(OutgoingMessage(
    text="Olá! Como posso ajudar?",
    channel_id="5511999999999"
))

Texto com Formatação

text = """
*Negrito*
_Itálico_
~Riscado~
```Código```

Funciona igual ao WhatsApp!
"""

Indicador de Digitação

await adapter.send_typing_indicator("5511999999999")

Marcar como Lido

await adapter.mark_message_as_read("wamid.xxx")

💰 Custos e Limites

Tier Gratuito

  • 1000 conversas por mês (gratuito)
  • Conversa = janela de 24h com o usuário

Após Limite Gratuito

Preços variam por região (valores aproximados em 2024):

Região Preço por Conversa
Brasil $0.05 - $0.10
EUA $0.03 - $0.08
Europa $0.04 - $0.09

Tipos de conversa: - Marketing: Você inicia (mais caro) - Utility: Notificações transacionais - Service: Cliente inicia (mais barato) - Authentication: Códigos de verificação

Limites de Taxa

  • Novos números: 250 conversas/dia
  • Após aprovação: Aumenta gradualmente
  • Limite máximo: Ilimitado (com aprovação)

🔐 Segurança

Validar Assinatura do Webhook

Configure WHATSAPP_OFFICIAL_APP_SECRET para validar que webhooks vêm do Meta:

# O adapter valida automaticamente se app_secret estiver configurado
signature = request.headers.get("X-Hub-Signature-256")
# Validação HMAC SHA256

Proteger Access Token

  • ✅ Nunca commite no código
  • ✅ Use variáveis de ambiente
  • ✅ Rotacione periodicamente
  • ✅ Use System User para tokens permanentes

📊 Monitoramento

Via Meta Business Manager

  1. WhatsApp Manager → Insights
  2. Visualize:
  3. Mensagens enviadas/recebidas
  4. Taxa de entrega
  5. Conversas ativas

Via API

curl -X GET "https://graph.facebook.com/v19.0/${PHONE_ID}/analytics" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

🚨 Troubleshooting

Erro 401 Unauthorized

  • ✅ Verifique se Access Token é válido
  • ✅ Confirme que token tem permissões corretas
  • ✅ Teste token: curl -H "Authorization: Bearer TOKEN" https://graph.facebook.com/v19.0/me

Webhook não Verifica

  • ✅ Confirme que endpoint GET retorna challenge
  • ✅ Verifique verify_token está correto
  • ✅ URL deve ser HTTPS (exceto localhost para testes)

Mensagens não Chegam

  • ✅ Número está na lista de permitidos (para número de teste)?
  • ✅ Webhook subscrito ao campo "messages"?
  • ✅ Verifique logs do servidor para webhooks recebidos

Erro 133: Número não está registrado

  • Usuário precisa ter WhatsApp instalado
  • Para número de teste: adicione na lista permitida

📚 Recursos Adicionais

🎓 Próximos Passos

  1. Desenvolvimento: Use número de teste
  2. Templates: Configure templates de mensagem no Business Manager
  3. Aprovação: Solicite aumento de limites
  4. Produção: Adicione número verificado
  5. Monitoring: Configure alertas de quota

💡 Dicas

  • Use número de teste para desenvolvimento (gratuito, sem aprovação)
  • System User tokens são mais seguros que User tokens
  • Valide assinatura do webhook em produção
  • Configure billing limits no Business Manager
  • Templates são obrigatórios para mensagens iniciadas pela empresa (após 24h)

Pronto para começar! 🚀

Para dúvidas, consulte a documentação oficial do Meta ou abra uma issue no repositório.