Configuração WhatsApp com Evolution API¶

Guia completo para integrar WhatsApp ao ifriend-agents usando Evolution API.

📋 Visão Geral¶

A Evolution API é uma solução open-source que permite conectar ao WhatsApp usando: - WhatsApp Web (Baileys): Conexão gratuita via QR Code - WhatsApp Cloud API: API oficial do Meta para empresas

Este guia foca na implementação Baileys (gratuita e self-hosted).

🎯 Pré-requisitos¶

Docker instalado
Servidor com IP público ou ngrok para webhooks
WhatsApp instalado no celular

🚀 Instalação Evolution API¶

Opção 1: Docker Run (Desenvolvimento)¶

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

Opção 2: Docker Compose (Recomendado)¶

Crie docker-compose-evolution.yml:

version: '3.8'

services:
  evolution-api:
    image: atendai/evolution-api:latest
    container_name: evolution_api
    restart: always
    ports:
      - "8080:8080"
    environment:
      # === Autenticação ===
      AUTHENTICATION_API_KEY: ${EVOLUTION_API_KEY}

      # === Database (Opcional - Para persistência) ===
      DATABASE_ENABLED: true
      DATABASE_PROVIDER: postgresql
      DATABASE_CONNECTION_URI: postgresql://user:pass@postgres:5432/evolution
      DATABASE_SAVE_DATA_INSTANCE: true
      DATABASE_SAVE_DATA_NEW_MESSAGE: true

      # === Webhooks ===
      WEBHOOK_GLOBAL_URL: ${WEBHOOK_URL}/whatsapp/webhook
      WEBHOOK_GLOBAL_ENABLED: true
      WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS: true

      # === Logs ===
      LOG_LEVEL: INFO
      LOG_COLOR: true

    volumes:
      - evolution_instances:/evolution/instances
      - evolution_store:/evolution/store

  postgres:
    image: postgres:15-alpine
    container_name: evolution_postgres
    restart: always
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: evolution
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  evolution_instances:
  evolution_store:
  postgres_data:

Execute:

export EVOLUTION_API_KEY="sua-chave-secreta"
export WEBHOOK_URL="https://seu-dominio.com"

docker-compose -f docker-compose-evolution.yml up -d

🔧 Criar Instância WhatsApp¶

1. Verifique se API está rodando¶

curl http://localhost:8080

Resposta esperada:

{
  "status": 200,
  "message": "Welcome to the Evolution API, it is working!",
  "version": "2.x.x"
}

2. Crie uma instância¶

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

3. Obtenha QR Code¶

curl -X GET http://localhost:8080/instance/connect/ifriend-bot \
  -H "apikey: sua-chave-secreta"

Você receberá:

{
  "instance": {
    "instanceName": "ifriend-bot",
    "status": "open",
    "qrcode": {
      "code": "1@xxx...",
      "base64": "data:image/png;base64,..."
    }
  }
}

4. Escaneie QR Code¶

Abra o WhatsApp no celular
Vá em Configurações > Aparelhos conectados
Toque em Conectar um aparelho
Escaneie o QR Code (base64 ou acesse http://localhost:8080/manager)

⚙️ Configuração ifriend-agents¶

Adicione ao seu .env:

# WhatsApp Evolution API
WHATSAPP_BASE_URL=http://localhost:8080
WHATSAPP_API_KEY=sua-chave-secreta
WHATSAPP_INSTANCE_NAME=ifriend-bot

# Habilitar WhatsApp
MESSAGING_PLATFORMS=slack,whatsapp

🧪 Testar Integração¶

1. Envie mensagem de teste¶

curl -X POST http://localhost:8080/message/sendText/ifriend-bot \
  -H "apikey: sua-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Teste Evolution API"
  }'

2. Verifique webhook¶

Configure um endpoint temporário com ngrok:

ngrok http 8000

Atualize o webhook da instância:

curl -X PUT http://localhost:8080/webhook/set/ifriend-bot \
  -H "apikey: sua-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-ngrok.ngrok.io/whatsapp/webhook",
    "enabled": true,
    "events": ["messages.upsert"]
  }'

Envie mensagem para o número WhatsApp conectado e veja o webhook ser chamado.

📡 Formato do Webhook¶

Quando alguém envia mensagem, você receberá:

{
  "event": "messages.upsert",
  "instance": "ifriend-bot",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0ABC123456789"
    },
    "message": {
      "conversation": "Olá, preciso de ajuda!"
    },
    "messageType": "conversation",
    "messageTimestamp": 1706545234,
    "pushName": "João Silva"
  }
}

🎨 Formatação de Mensagens¶

WhatsApp suporta markdown básico:

# Negrito
*texto em negrito*

# Itálico
_texto em itálico_

# Riscado
~texto riscado~

# Monoespaçado
```código```

# Exemplo completo
await adapter.send_message(OutgoingMessage(
    text="*Atenção!*\n\n_Sua reserva foi confirmada._\n\n```ID: 12345```",
    channel_id="5511999999999"
))

🔍 Monitoramento¶

Ver status da instância¶

curl http://localhost:8080/instance/connectionState/ifriend-bot \
  -H "apikey: sua-chave-secreta"

Ver logs¶

docker logs -f evolution_api

Listar instâncias¶

curl http://localhost:8080/instance/fetchInstances \
  -H "apikey: sua-chave-secreta"

🚨 Troubleshooting¶

Instância desconecta constantemente¶

Verifique internet estável
Desabilite modo economia de bateria no celular
Use database persistence (PostgreSQL)

Mensagens não chegam¶

Confirme webhook URL está acessível
Verifique eventos habilitados no webhook
Teste webhook com curl

QR Code não aparece¶

Verifique se instância já está conectada

Delete instância e crie nova:

curl -X DELETE http://localhost:8080/instance/delete/ifriend-bot \
  -H "apikey: sua-chave-secreta"

Erro "Instance not found"¶

Confirme nome da instância
Verifique se criação foi bem sucedida
Liste todas instâncias

🔐 Segurança¶

API Key forte: Use senha complexa para AUTHENTICATION_API_KEY
HTTPS: Use reverse proxy (nginx/caddy) com SSL
Firewall: Restrinja acesso à porta 8080
Webhook assinado: Valide origem dos webhooks

Exemplo nginx:

server {
    listen 443 ssl;
    server_name evolution.seudominio.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

📚 Recursos Adicionais¶

🎯 Funcionalidades Avançadas¶

Enviar imagem¶

curl -X POST http://localhost:8080/message/sendMedia/ifriend-bot \
  -H "apikey: sua-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "mediatype": "image",
    "media": "https://exemplo.com/imagem.jpg",
    "caption": "Olha que foto legal!"
  }'

Enviar áudio¶

curl -X POST http://localhost:8080/message/sendWhatsAppAudio/ifriend-bot \
  -H "apikey: sua-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "audio": "https://exemplo.com/audio.mp3"
  }'

Indicador de presença¶

curl -X POST http://localhost:8080/chat/presence/ifriend-bot \
  -H "apikey: sua-chave-secreta" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "presence": "composing"
  }'

Tipos de presença: - available: Online - unavailable: Offline - composing: Digitando... - recording: Gravando áudio - paused: Pausou digitação

Configuração completa! Seu bot WhatsApp está pronto para uso. 🎉