Arquitetura WhatsApp & IA

Visão Geral da Arquitetura

A integração WhatsApp + IA segue a abordagem monolítica integrada com filas dedicadas — mesmo stack Docker, sem microserviços adicionais.

┌─────────────────────────────────────────────────────────────┐
│                    META CLOUD API                           │
│              (WhatsApp Business Platform)                   │
└──────────┬──────────────────────────────┬───────────────────┘
           │ Webhook (inbound)            │ HTTP API (outbound)
           ▼                              ▲
┌──────────────────────┐     ┌────────────────────────┐
│ WhatsAppWebhook      │     │ MetaCloudApiService    │
│ Controller           │     │ (send messages)        │
│ (rota CENTRAL)       │     └────────────┬───────────┘
└──────────┬───────────┘                  │
           │ resolve tenant               │
           │ pelo phone_number_id         │
           ▼                              │
┌──────────────────────┐                  │
│ ProcessInboundJob    │                  │
│ (fila: whatsapp)     │                  │
│ tenant-aware         │                  │
└──────────┬───────────┘                  │
           │                              │
           ▼                              │
┌──────────────────────────────┐          │
│ WhatsAppAgent                │          │
│ (Laravel AI SDK)             │          │
│ ┌──────────────────────┐     │          │
│ │ Tools (por nível)    │     │          │
│ │ Middleware (pipeline) │     │          │
│ │ Failover (providers) │     │          │
│ └──────────────────────┘     │          │
└──────────┬───────────────────┘          │
           ▼                              │
┌──────────────────────┐                  │
│ SendOutboundJob      ├──────────────────┘
│ (fila: whatsapp)     │
└──────────────────────┘

Decisões Arquiteturais

Por que monolítico e não microserviço?

Critério	Monolítico	Microserviço IA
Acesso a dados do tenant	Direto (Eloquent)	API intermediária necessária
Deploy	Mesmo Docker stack	Container + infra adicional
Latência	Sem rede extra	HTTP entre serviços
Feature flags	Reutiliza sistema existente	Replicar lógica
Custo infra	Zero adicional	Servidor/container extra
Escalabilidade IA	Workers Horizon dedicados	Escala independente

Mitigação do único risco (performance): filas dedicadas whatsapp-inbound e whatsapp-outbound no Horizon com workers separados. Processamento IA não compete com jobs normais do app.

Por que Laravel AI SDK?

• Interface unificada para OpenAI, Anthropic, Gemini e outros
• Agents com Tools nativos — perfeito para function calling do chatbot
• RemembersConversations — persistência de histórico automática
• Failover em uma linha: provider: [Lab::OpenAI, Lab::Anthropic]
• Middleware para interceptar prompts (personalidade, créditos, access level)
• Broadcasting + Queueing integrados com Reverb e Horizon
• Agent::fake() para testes sem chamar APIs reais

Por que Meta Cloud API oficial?

• Sem risco de ban (APIs não-oficiais podem perder acesso)
• Templates aprovados para mensagens outbound
• Webhooks confiáveis com signature verification
• Gratuito para conversas iniciadas pelo usuário (1.000/mês por WABA)
• Suporte a áudio, imagem, documento

Por que número por igreja?

• Identidade própria — mensagens saem do número da igreja
• Roteamento trivial — phone_number_id mapeia para tenant
• Rate limits isolados por igreja
• A igreja pode usar o número que já possui

Estrutura de Domínio

app/Domain/WhatsApp/
├── Models/          → 6 models (1 central + 5 tenant)
├── Enums/           → 8 enums
├── Actions/         → 11 actions
├── Jobs/            → 5 jobs
├── Services/        → 1 service (MetaCloudApiService)
├── Ai/
│   ├── Agents/      → WhatsAppAgent
│   ├── Tools/       → 13 tools (4 basic + 4 intermediate + 5 complete)
│   └── Middleware/   → 4 middleware
├── Events/          → 4 events
├── Notifications/   → 1 notification
└── Http/
    ├── Controllers/ → 4 controllers
    └── Requests/    → 3 form requests

Webhook Centralizado

O webhook é a peça mais crítica da integração. Precisa funcionar fora do tenant middleware porque o Meta envia para um único URL sem informação de tenant.

POST /webhooks/whatsapp
  → Valida X-Hub-Signature-256 (HMAC SHA-256 com META_WHATSAPP_APP_SECRET)
  → Extrai phone_number_id da payload
  → Busca whatsapp_accounts WHERE phone_number_id = X
  → Resolve tenant_id
  → Dispatch job com tenant()->run()

Verificação inicial do Meta:

GET /webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=TOKEN&hub.challenge=CHALLENGE
  → Valida verify_token
  → Retorna hub.challenge

Pipeline de Processamento IA

Mensagem Inbound
  │
  ▼
InjectChurchPersonality (middleware)
  → Carrega ai_prompt_configurations do tenant
  → Injeta system prompt (template ou customizado)
  │
  ▼
CheckCreditQuota (middleware)
  → Verifica whatsapp_credit_usage do mês
  → Cota + créditos extras disponíveis?
  → Se não: rejeita com mensagem amigável
  │
  ▼
FilterByAccessLevel (middleware)
  → Remove tools que não pertencem ao nível do plano
  → Garante restrição estrutural (não depende de prompt)
  │
  ▼
WhatsAppAgent.prompt()
  → Provider primário (OpenAI gpt-4o-mini)
  → Failover automático (Anthropic claude-haiku)
  → Agent decide quais tools usar
  → Tools executam Actions do domínio
  │
  ▼
LogAiUsage (middleware)
  → Registra tokens consumidos, provider, tempo
  → Atualiza whatsapp_credit_usage
  │
  ▼
Resposta → SendOutboundMessageJob

Horizon — Configuração de Filas

'whatsapp' => [
    'connection' => 'database',
    'queue' => ['whatsapp-inbound', 'whatsapp-outbound'],
    'balance' => 'auto',
    'processes' => 3,
    'tries' => 3,
    'timeout' => 120,
],

• whatsapp-inbound: processamento IA (pode demorar 5-30s dependendo do provider)
• whatsapp-outbound: envio via Meta API (rápido, ~1-2s)
• Workers dedicados não competem com filas default, notifications, mass-email

Segurança

Camadas de Proteção

1. Webhook — signature validation, rate limiting, verify_token
2. Dados — access_token criptografado, isolamento por tenant DB
3. IA — tools filtradas estruturalmente por access level, não por prompt
4. Identificação — vinculação por telefone + confirmação para dados sensíveis
5. Audit — todos os models auditados via Laravel Auditing

Proteção contra Prompt Injection

A segurança contra prompt injection é estrutural, não depende de instrução no prompt:

• FilterByAccessLevel middleware remove tools ANTES de enviar ao provider
• Tools de consulta acessam APENAS dados do membro identificado pelo telefone
• Tools de ação retornam intent estruturado → Action valida e executa
• System prompt reforça restrições como camada adicional (defense in depth)

Escalabilidade

Horizontal

• Workers Horizon podem ser escalados independentemente
• Adicionar processos na config do Horizon ou novos containers

Por Tenant

• Cada igreja tem suas próprias filas (isolamento via tenant context nos jobs)
• Rate limits do Meta são por número (por igreja), sem conflito

Limites Conhecidos

• Meta Cloud API: 80 mensagens/segundo por número (suficiente para qualquer igreja)
• IA: limitado pelo rate limit do provider (mitigado por failover)