Skip to content

WhatsApp Adapter - Evolution API Migration

📅 Data

Janeiro 2026

🎯 Mudança Principal

Migração do adaptador WhatsApp de Twilio para Evolution API (self-hosted).

✨ Benefícios

1. Custo Zero

  • ❌ Twilio: ~$0.005 por mensagem
  • ✅ Evolution API: Gratuito (self-hosted)

2. Controle Total

  • Self-hosted: você controla os dados
  • Sem dependência de serviços terceiros
  • Sem limites de taxa artificiais

3. Recursos Avançados

  • ✅ Edição de mensagens (Evolution API)
  • ✅ Deleção de mensagens (Evolution API)
  • ✅ Indicador de presença/digitação (Evolution API)
  • ✅ Suporte a grupos
  • ❌ Limitado no Twilio

4. Facilidade de Configuração

  • Docker one-liner para testar
  • Interface web de gerenciamento
  • Documentação completa em português

🔄 O Que Mudou

Configuração (.env)

Antes (Twilio): 

WHATSAPP_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHATSAPP_AUTH_TOKEN=your-twilio-auth-token
WHATSAPP_NUMBER=+5511999999999

Depois (Evolution API): 

WHATSAPP_BASE_URL=http://localhost:8080
WHATSAPP_API_KEY=sua-chave-secreta
WHATSAPP_INSTANCE_NAME=ifriend-bot

Dependências

Antes: 

twilio>=8.11.0

Depois: 

# httpx já incluído em requirements.txt
# Nenhuma dependência adicional necessária

Webhook Format

Antes (Twilio): 

# Form-encoded data
{
    "From": "whatsapp:+5511999999999",
    "To": "whatsapp:+551188888888",
    "Body": "texto da mensagem",
    "MessageSid": "SM123..."
}

Depois (Evolution API): 

{
    "event": "messages.upsert",
    "instance": "ifriend-bot",
    "data": {
        "key": {
            "remoteJid": "5511999999999@s.whatsapp.net",
            "fromMe": false,
            "id": "message_id"
        },
        "message": {
            "conversation": "texto da mensagem"
        },
        "messageType": "conversation",
        "messageTimestamp": 1234567890,
        "pushName": "Nome do usuário"
    }
}

📝 Implementação

Arquivos Modificados

  1. messaging/adapters/whatsapp_adapter.py
  2. Substituído cliente Twilio por httpx
  3. Implementado autenticação via API key
  4. Parse de webhook Evolution API

  5. Adicionado suporte a edição/deleção de mensagens

  6. messaging/README.md

  7. Atualizado status: ⚠️ Exemplo → ✅ Produção
  8. Alterado dependência: twilio → httpx

  9. Adicionado link para guia de configuração

  10. .env.example

  11. Removido vars Twilio
  12. Adicionado vars Evolution API

  13. Comentário com link para documentação

  14. requirements-messaging.txt

  15. Removido twilio>=8.11.0
  16. Adicionado comentário indicando httpx

Arquivos Criados

  1. docs/guides/WHATSAPP_EVOLUTION_API_SETUP.md
  2. Guia completo de instalação
  3. Configuração Docker/Docker Compose
  4. Criação de instância
  5. Configuração de webhooks
  6. Troubleshooting

  7. Exemplos de uso avançado

  8. tests/test_whatsapp_evolution.py

  9. Script de teste de conexão
  10. Teste de envio de mensagem
  11. Validação de webhook format

🚀 Como Migrar

Passo 1: Instalar Evolution API

docker run -d \
    --name evolution_api \
    -p 8080:8080 \
    -e AUTHENTICATION_API_KEY=minha-chave-secreta \
    atendai/evolution-api:latest

Passo 2: Criar Instância

curl -X POST http://localhost:8080/instance/create \
  -H "apikey: minha-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "ifriend-bot",
    "qrcode": true,
    "webhook": {
      "url": "https://seu-dominio.com/whatsapp/webhook",
      "enabled": true,
      "events": ["messages.upsert"]
    }
  }'

Passo 3: Conectar WhatsApp

# Obter QR Code
curl http://localhost:8080/instance/connect/ifriend-bot \
  -H "apikey: minha-chave-secreta"

# Escanear com WhatsApp no celular

Passo 4: Atualizar .env

# Remover (comentar) vars Twilio
# WHATSAPP_ACCOUNT_SID=...
# WHATSAPP_AUTH_TOKEN=...
# WHATSAPP_NUMBER=...

# Adicionar vars Evolution API
WHATSAPP_BASE_URL=http://localhost:8080
WHATSAPP_API_KEY=minha-chave-secreta
WHATSAPP_INSTANCE_NAME=ifriend-bot

Passo 5: Testar

# Teste de conexão
python tests/test_whatsapp_evolution.py

# Ou enviar via curl
curl -X POST http://localhost:8080/message/sendText/ifriend-bot \
  -H "apikey: minha-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Teste de migração concluído!"
  }'

🔍 Compatibilidade

Mantido (100% compatível)

  • ✅ Interface MessagingAdapter
  • ✅ Métodos send_message(), parse_webhook_request()
  • ✅ Formato markdown
  • ✅ Path webhook /whatsapp/webhook
  • ✅ Platform name whatsapp

Novo (Recursos adicionais)

  • 🆕 send_typing_indicator() - funcional
  • 🆕 update_message() - funcional
  • 🆕 delete_message() - funcional
  • 🆕 Suporte a mensagens de grupo
  • 🆕 Metadados expandidos (pushName, timestamp, etc)

Removido

  • ❌ Dependência de conta Twilio
  • ❌ Limite de taxa Twilio
  • ❌ Custos por mensagem

📚 Recursos

✅ Checklist de Migração

  • [ ] Evolution API instalado e rodando
  • [ ] Instância criada e conectada via QR Code
  • [ ] Webhook configurado e testado
  • [ ] .env atualizado com novas variáveis
  • [ ] Dependência twilio removida (se não usar para outros fins)
  • [ ] Teste de envio de mensagem bem-sucedido
  • [ ] Teste de recepção via webhook bem-sucedido
  • [ ] Monitoramento configurado (logs, status)
  • [ ] Backup de configuração anterior (se necessário rollback)
  • [ ] Documentação interna atualizada

🤝 Suporte

Migração completa! WhatsApp agora roda com custo zero e controle total. 🎉