Exemplos de Uso - Multi-Platform Bot¶

🎯 Casos de Uso¶

1. Bot Apenas para Slack (Atual)¶

# .env
MESSAGING_PLATFORMS=slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
SESSION_BACKEND=redis
MEMORY_BACKEND=cloudsql

python unified_bot.py

Webhook Slack: https://seu-dominio.com/webhook/slack/events

2. Bot Multi-Plataforma (Slack + Telegram + WhatsApp)¶

# .env
MESSAGING_PLATFORMS=slack,telegram,whatsapp

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...

# Telegram
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

# WhatsApp (Twilio)
WHATSAPP_ACCOUNT_SID=AC...
WHATSAPP_AUTH_TOKEN=...
WHATSAPP_NUMBER=+5511999999999

SESSION_BACKEND=redis
MEMORY_BACKEND=cloudsql

# Instalar dependências adicionais
pip install python-telegram-bot twilio

# Rodar bot
python unified_bot.py

Webhooks: - Slack: https://seu-dominio.com/webhook/slack/events - Telegram: https://seu-dominio.com/webhook/telegram/webhook - WhatsApp: https://seu-dominio.com/webhook/whatsapp/webhook

3. Auto-Detecção de Plataformas¶

Se você não definir MESSAGING_PLATFORMS, o bot detecta automaticamente baseado nas env vars:

# .env
# MESSAGING_PLATFORMS não definido
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
TELEGRAM_BOT_TOKEN=123:ABC...

O bot detectará e ativará: Slack + Telegram

4. Teste Local com Apenas Telegram¶

# .env
MESSAGING_PLATFORMS=telegram
TELEGRAM_BOT_TOKEN=...
SESSION_BACKEND=inmemory
MEMORY_BACKEND=inmemory

# Usar ngrok para expor localhost
ngrok http 8080

# Configurar webhook do Telegram
curl -X POST \
  "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://abc123.ngrok.io/webhook/telegram/webhook"

# Rodar bot
python unified_bot.py

🔧 Uso Programático¶

Criar Adapter Manualmente¶

from messaging import AdapterFactory
from messaging.adapters import SlackAdapter

# Opção 1: Via factory
factory = AdapterFactory()
factory.register_from_config("slack", {
    "bot_token": "xoxb-...",
    "signing_secret": "..."
})

slack = factory.get_adapter("slack")
await slack.setup()

# Opção 2: Criar diretamente
slack_adapter = SlackAdapter({
    "bot_token": "xoxb-...",
    "signing_secret": "..."
})
await slack_adapter.setup()

Processar Mensagem Manualmente¶

from messaging import IncomingMessage, OutgoingMessage
from messaging.processor import ConversationProcessor

# Criar mensagem de entrada
incoming = IncomingMessage(
    platform="slack",
    user_id="U123",
    channel_id="C456",
    thread_id="1234567890.123456",
    text="Quero comprar um tour",
    is_direct_message=False
)

# Processar
processor = ConversationProcessor(runner)
await processor.process_message(incoming, slack_adapter)

Enviar Mensagem Proativa¶

# Criar mensagem de saída
outgoing = OutgoingMessage(
    text="Seu pedido foi confirmado! 🎉",
    channel_id="C456",
    thread_id="1234567890.123456"
)

# Enviar via adapter
await slack_adapter.send_message(outgoing)

🚀 Deploy¶

Docker¶

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8080

CMD ["python", "unified_bot.py"]

# Build
docker build -t ifriend-bot .

# Run
docker run -p 8080:8080 \
  -e SLACK_BOT_TOKEN=xoxb-... \
  -e SLACK_SIGNING_SECRET=... \
  -e TELEGRAM_BOT_TOKEN=... \
  -e REDIS_URL=redis://redis:6379 \
  ifriend-bot

Docker Compose¶

version: '3.8'

services:
  bot:
    build: .
    ports:
      - "8080:8080"
    environment:
      - MESSAGING_PLATFORMS=slack,telegram
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
      - SLACK_SIGNING_SECRET=${SLACK_SIGNING_SECRET}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - SESSION_BACKEND=redis
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Google Cloud Run¶

# Build e push
gcloud builds submit --tag gcr.io/PROJECT_ID/ifriend-bot

# Deploy
gcloud run deploy ifriend-bot \
  --image gcr.io/PROJECT_ID/ifriend-bot \
  --platform managed \
  --region us-central1 \
  --set-env-vars SLACK_BOT_TOKEN=xoxb-... \
  --set-env-vars SLACK_SIGNING_SECRET=... \
  --set-env-vars TELEGRAM_BOT_TOKEN=... \
  --set-env-vars SESSION_BACKEND=redis \
  --set-env-vars REDIS_URL=...

🧪 Testes¶

Teste de Health Check¶

curl http://localhost:8080/

Resposta esperada:

{
  "status": "ok",
  "app": "ifriend_agent",
  "platforms": ["slack", "telegram"],
  "adapters": {
    "slack": {
      "name": "slack",
      "webhook": "/slack/events"
    },
    "telegram": {
      "name": "telegram",
      "webhook": "/telegram/webhook"
    }
  },
  "backends": {
    "session": "redis",
    "memory": "cloudsql"
  }
}

Teste de Webhook Slack¶

# Simular evento de mensagem
curl -X POST http://localhost:8080/webhook/slack/events \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "type": "message",
      "user": "U123",
      "text": "Hello",
      "channel": "D456",
      "ts": "1234567890.123456"
    }
  }'

Teste de Webhook Telegram¶

curl -X POST http://localhost:8080/webhook/telegram/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "update_id": 123,
    "message": {
      "message_id": 456,
      "from": {"id": 789, "first_name": "User"},
      "chat": {"id": 789, "type": "private"},
      "text": "Hello"
    }
  }'

📊 Monitoramento¶

Logs Estruturados¶

O bot já produz logs estruturados:

2025-01-02 10:00:00 - messaging.factory - INFO - ✅ Plataformas registradas: slack, telegram
2025-01-02 10:00:01 - messaging.adapters.slack_adapter - INFO - 🤖 Slack Bot User ID: U123
2025-01-02 10:00:02 - messaging.processor - INFO - 📨 Mensagem recebida de slack: user=U456, text='Quero comprar um tour...'
2025-01-02 10:00:05 - messaging.processor - INFO - ✅ Resposta enviada para U456 via slack (canal)

Adicionar Métricas (Prometheus)¶

from prometheus_client import Counter, Histogram

# Métricas
messages_received = Counter(
    'messages_received_total',
    'Total messages received',
    ['platform']
)

processing_time = Histogram(
    'message_processing_seconds',
    'Time to process message',
    ['platform']
)

# No processor
async def process_message(self, message, adapter):
    messages_received.labels(platform=message.platform).inc()

    with processing_time.labels(platform=message.platform).time():
        # ... processar mensagem

🔐 Segurança¶

Validação de Assinaturas¶

Cada adapter deve validar assinaturas:

# Slack: slack-bolt já valida automaticamente
# Telegram: validar token no parse_webhook_request
# WhatsApp: validar signature da Twilio

Rate Limiting¶

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@app.post("/webhook/{path:path}")
@limiter.limit("100/minute")
async def unified_webhook(...):
    # ...

📝 FAQ¶

Como adicionar suporte a Discord?¶

Veja exemplo completo em MESSAGING_ARCHITECTURE.md

Posso usar apenas o bot antigo (slack_bot.py)?¶

Sim! O slack_bot.py original continua funcional. Use-o se precisar apenas de Slack.

Como migrar gradualmente?¶

Rode ambos bots em paralelo (portas diferentes)
Configure Slack webhook para unified_bot.py
Teste por alguns dias
Quando estável, desative slack_bot.py

Performance da arquitetura nova?¶

Mesma performance. A camada de abstração adiciona <1ms de overhead (negligível comparado com latência de rede e processamento do agente).

Dúvidas? Consulte MESSAGING_ARCHITECTURE.md