Guia de Configuração - WhatsApp Adapters¶

Este guia explica as duas opções de integração WhatsApp disponíveis no ifriend-agents.

📊 Comparação Rápida¶

Aspecto	Evolution API	Meta Cloud API (Oficial)
Status	Não oficial	✅ Oficial do Meta
Custo	Gratuito	Pago após limite gratuito
Setup	Self-hosted (Docker)	Meta Business Account
Aprovação	Não requer	Requer aprovação Meta
Estabilidade	Pode quebrar	Garantida com SLA
Suporte	Comunidade	Suporte oficial Meta
Ideal para	Desenvolvimento, MVP	Produção, empresas

🔀 Escolha seu Adapter¶

Opção 1: Evolution API (Recomendado para desenvolvimento)¶

Vantagens: - Gratuito e open-source - Rápido para começar - Não requer aprovação do Meta - Suporta múltiplas instâncias

Quando usar: - Desenvolvimento e testes - MVPs e protótipos - Projetos pessoais - Quando não há budget

Configuração:

# .env
MESSAGING_PLATFORMS=telegram,whatsapp_evolution
WHATSAPP_EVOLUTION_BASE_URL=http://localhost:8080
WHATSAPP_EVOLUTION_API_KEY=sua-chave-secreta
WHATSAPP_EVOLUTION_INSTANCE=ifriend-bot

📖 Guia completo: Evolution API Setup

Opção 2: WhatsApp Cloud API - Meta (Recomendado para produção)¶

Vantagens: - API oficial do Meta/Facebook - SLA e suporte empresarial - Maior estabilidade - Features oficiais primeiro

Quando usar: - Produção - Aplicações empresariais - Quando é necessário SLA - Conformidade regulatória

Configuração:

# .env
MESSAGING_PLATFORMS=telegram,whatsapp_official
WHATSAPP_OFFICIAL_ACCESS_TOKEN=EAAxxxxxxxxxx
WHATSAPP_OFFICIAL_PHONE_ID=123456789
WHATSAPP_OFFICIAL_VERIFY_TOKEN=meu-token-secreto
WHATSAPP_OFFICIAL_API_VERSION=v19.0
WHATSAPP_OFFICIAL_APP_SECRET=abc123  # Opcional mas recomendado

📖 Guia completo: WhatsApp Official Setup

🚀 Usar Ambos Simultaneamente¶

Você pode ter ambos adapters ativos ao mesmo tempo:

# .env
MESSAGING_PLATFORMS=telegram,whatsapp_evolution,whatsapp_official

# Evolution API
WHATSAPP_EVOLUTION_BASE_URL=http://evolution:8080
WHATSAPP_EVOLUTION_API_KEY=chave-evolution
WHATSAPP_EVOLUTION_INSTANCE=dev-bot

# Official API
WHATSAPP_OFFICIAL_ACCESS_TOKEN=EAAxxxxxx
WHATSAPP_OFFICIAL_PHONE_ID=123456789
WHATSAPP_OFFICIAL_VERIFY_TOKEN=token-oficial

Webhooks diferentes: - Evolution: https://seu-dominio.com/webhook/whatsapp/evolution/webhook - Official: https://seu-dominio.com/webhook/whatsapp/official/webhook

Use case comum: - Evolution para desenvolvimento/testes - Official para produção - Números diferentes para cada ambiente

📡 Diferenças nos Webhooks¶

Evolution API Webhook¶

{
  "event": "messages.upsert",
  "instance": "ifriend-bot",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "message": {
      "conversation": "Olá!"
    }
  }
}

Configuração: - Eventos: messages.upsert - Autenticação: API Key própria

Meta Cloud API Webhook¶

GET (Verificação inicial):

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

POST (Mensagens):

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "5511999999999",
          "text": {"body": "Olá!"}
        }]
      }
    }]
  }]
}

Configuração: - Verificação: GET com verify_token - Assinatura: X-Hub-Signature-256 (HMAC) - Subscrição: Campo "messages"

🧪 Testando os Adapters¶

Testar Evolution API¶

python tests/test_whatsapp_evolution.py

Testar Official API¶

export WHATSAPP_TEST_NUMBER=5511999999999
python tests/test_whatsapp_official.py

🔄 Migração entre Adapters¶

De Evolution para Official¶

Configure as variáveis WHATSAPP_OFFICIAL_*
Mude MESSAGING_PLATFORMS=whatsapp_official
Atualize webhook URL no Meta Developer Portal
Teste com o script de teste

De Official para Evolution¶

Configure Evolution API via Docker
Configure variáveis WHATSAPP_EVOLUTION_*
Mude MESSAGING_PLATFORMS=whatsapp_evolution
Atualize webhook na Evolution API

📚 Documentação Adicional¶

⚠️ Considerações Importantes¶

Evolution API¶

⚠️ Não é oficial - pode parar de funcionar com updates do WhatsApp
⚠️ Requer servidor próprio (VPS, Cloud Run, etc)
✅ Ideal para começar rapidamente
✅ Sem custos de API

Meta Cloud API¶

✅ Garantia de funcionamento
✅ Suporte oficial
⚠️ Requer processo de aprovação
⚠️ Custos após limite gratuito (1000 conversas/mês)
⚠️ Requer Meta Business Account

🆘 Troubleshooting¶

Evolution não conecta¶

# Verifique se Evolution API está rodando
curl http://localhost:8080

# Verifique logs
docker logs evolution_api

Official retorna 401¶

Verifique se Access Token é permanente
Confirme Phone Number ID
Teste token: curl -H "Authorization: Bearer TOKEN" https://graph.facebook.com/v19.0/me

Webhook não recebe mensagens¶

Evolution: Verifique configuração do webhook na instância
Official: Verifique subscrição no Developer Portal
Ambos: Confirme que URL está acessível publicamente

💡 Recomendação¶

Para começar: Use Evolution API (setup em 10 minutos)
Para produção: Migre para WhatsApp Official quando estiver pronto

Ambos compartilham a mesma interface (MessagingAdapter), então migrar é apenas trocar variáveis de ambiente! 🎯