Skip to content

WhatsApp & IA Conversacional ​

Visão Geral ​

O módulo WhatsApp (Domain/WhatsApp) integra o Decaelo com a Meta Cloud API (WhatsApp Business Platform) e o Laravel AI SDK para oferecer comunicação bidirecional inteligente entre igrejas e seus membros.

Funcionalidades principais:

  • Notificações outbound via templates aprovados pelo Meta
  • Chatbot conversacional com IA que responde de forma natural
  • Escalação automática para atendente humano
  • 3 níveis de acesso gateados por plano
  • Personalidade da IA customizável por igreja

Arquitetura ​

Fluxo Geral ​

Meta Cloud API ←→ Webhook Controller (central) ←→ Jobs (tenant-aware) ←→ WhatsAppAgent (Laravel AI SDK)
  • Webhook centralizado — rota pública fora do tenant middleware. Resolve o tenant pelo phone_number_id cadastrado em whatsapp_accounts
  • Filas dedicadas — whatsapp-inbound (processamento IA) e whatsapp-outbound (envio), workers Horizon separados
  • Agent do Laravel AI SDK — WhatsAppAgent com Tools, Middleware e Failover entre provedores

Número por Igreja ​

Cada igreja (tenant) possui seu próprio número de WhatsApp registrado na Meta Cloud API. O número pode ser o que a igreja já utiliza. Isso garante:

  • Identidade própria — mensagens saem do número da igreja
  • Roteamento trivial — phone_number_id mapeia diretamente para o tenant
  • Sem conflito de rate limits entre igrejas

Modelo de Dados ​

Banco Central:

TabelaDescrição
whatsapp_accountsCredenciais Meta por tenant (phone_number_id, access_token criptografado)

Banco Tenant (isolado por igreja):

TabelaDescrição
whatsapp_conversationsConversas com status (active, escalated, closed, expired)
whatsapp_messagesMensagens com direção, tipo, sender_id, status de entrega, tokens IA usados
whatsapp_templatesTemplates aprovados pelo Meta para mensagens outbound
ai_prompt_configurationsPersonalidade da IA, system prompt, saudação, fallback
whatsapp_credit_usageControle mensal de cota e créditos extras

Integração com Módulos Existentes ​

  • Communication — NotificationChannel::WhatsApp adicionado ao enum existente. SendNotificationAction estendido para despachar via WhatsApp respeitando preferências do membro
  • Feature Flags — whatsapp_basic, whatsapp_intermediate, whatsapp_complete, whatsapp_custom_prompt
  • Horizon — supervisor dedicado whatsapp com filas whatsapp-inbound e whatsapp-outbound
  • Reverb — broadcasting de conversas escaladas e status de mensagens para o painel admin
  • Auditing — todos os models do módulo são auditados automaticamente

Fluxo Inbound (Membro → Igreja) ​

1. Membro envia mensagem no WhatsApp
2. Meta POST /webhooks/whatsapp
3. WhatsAppWebhookController valida signature
4. Resolve tenant pelo phone_number_id
5. Dispatch ProcessInboundMessageJob (fila: whatsapp-inbound)
6. Job no contexto do tenant:
   a. Busca/cria conversa pelo telefone do remetente
   b. Vincula ao member (se encontrar pelo telefone)
   c. Salva mensagem
   d. Se conversa escalada → broadcast para painel do atendente
   e. Se conversa ativa → WhatsAppAgent processa com IA
7. Agent responde → dispatch SendOutboundMessageJob
8. Mensagem enviada via MetaCloudApiService

Áudio ​

Mensagens de áudio são baixadas via Meta API e transcritas usando o Laravel AI SDK (Transcription STT). O texto transcrito é processado como mensagem de texto normal.

Fluxo Outbound (Igreja → Membros) ​

Notificações via Template ​

Mensagens iniciadas pela igreja (fora da janela de 24h) exigem templates pré-aprovados pelo Meta.

1. Admin cria notificação no painel
2. SendNotificationAction verifica preferências do membro
3. Canal WhatsApp habilitado → dispatch SendWhatsAppTemplateJob
4. Job preenche placeholders do template com dados do membro/evento
5. MetaCloudApiService envia template

Janela de 24h ​

  • Membro envia mensagem → abre janela de 24h para respostas livres
  • Dentro da janela: IA e atendentes respondem livremente (free-form)
  • Fora da janela: apenas templates aprovados

IA Conversacional ​

Laravel AI SDK ​

O chatbot usa o WhatsAppAgent construído com o Laravel AI SDK:

php
class WhatsAppAgent implements Agent, Conversational, HasMiddleware
{
    use Promptable, RemembersConversations;

    public function tools(): iterable
    {
        return match ($this->accessLevel) {
            AiAccessLevel::Basic => $this->basicTools(),
            AiAccessLevel::Intermediate => $this->intermediateTools(),
            AiAccessLevel::Complete => $this->completeTools(),
        };
    }
}

Níveis de Acesso ​

Básico — informações públicas da igreja:

ToolDescrição
ConsultarHorariosCultoHorários de cultos e missas
ConsultarEventosProximosPróximos eventos públicos
ConsultarInfoIgrejaEndereço, telefone, redes sociais
ConsultarAvisosGeraisAvisos da liderança

Intermediário — dados do próprio membro:

ToolDescrição
ConsultarMeusDadosDados cadastrais do membro
ConsultarMeusCelulasCélulas/grupos que participa
ConsultarMinhasContribuicoesResumo de dízimos/ofertas
ConsultarMeusEventosEventos inscritos

Completo — ações executáveis:

ToolDescrição
RegistrarPedidoOracaoCria pedido no mural de oração
InscreverEmEventoInscreve em evento
ConfirmarPresencaConfirma presença
SolicitarAtestadoSolicita declaração de membro
EscalarParaHumanoTransfere para atendente

Middleware do Agent ​

MiddlewareFunção
InjectChurchPersonalityCarrega system prompt da igreja (template ou customizado)
CheckCreditQuotaVerifica e decrementa cota mensal
FilterByAccessLevelRemove tools fora do nível do plano
LogAiUsageRegistra tokens, provider, tempo de resposta

Personalidade da IA ​

  • Templates (plano menor): perfis prontos — Formal, Acolhedor, Jovem
  • System prompt customizável (plano premium): admin configura tom, saudação, nome do bot, informações da denominação

Failover ​

php
$response = $agent->prompt($message, provider: [Lab::OpenAI, Lab::Anthropic]);

Se o provider principal falhar (rate limit, timeout), o SDK automaticamente tenta o próximo.

Providers por Ambiente ​

AmbienteProviderModelo
Dev/TestOpenAIgpt-4o-mini
ProduçãoOpenAI (fallback: Anthropic)gpt-4o-mini (fallback: claude-haiku)

Escalação para Humano ​

1. IA não consegue resolver → chama tool EscalarParaHumano
2. Conversa marcada como 'escalated'
3. Notificação via Reverb → sino no painel admin
4. Atendente vê conversa com histórico completo
5. Atendente responde pelo painel → mensagem enviada via WhatsApp
6. Timeout (configurável, default 15min):
   → Ninguém respondeu → mensagem ao membro informando retorno
   → Cria tarefa interna de follow-up
7. Atendente pode "Devolver para IA" → conversa volta para status 'active'

Segurança ​

Webhook ​

  • Validação X-Hub-Signature-256 com HMAC SHA-256
  • Rate limiting no endpoint
  • verify_token para handshake inicial do Meta

Dados ​

  • access_token criptografado no banco (encrypted cast)
  • Mensagens isoladas por tenant (banco separado)
  • Áudio descartado após transcrição

Proteção contra Prompt Injection ​

  • Tools acessam dados APENAS do membro identificado pelo telefone
  • FilterByAccessLevel remove tools antes do provider — restrição estrutural, não por prompt
  • Tools de ação retornam intent → Action valida e executa

Identificação do Membro ​

  • Vinculação automática por telefone
  • Primeiro acesso a dados pessoais exige confirmação (últimos 4 dígitos do CPF ou data de nascimento)
  • Confirmação válida por 30 dias

Configuracao na Meta (Passo a Passo) ​

IMPORTANTE: Use um app Meta separado do Facebook Login. A Meta restringe apps que misturam autenticacao com mensageria.

1. Criar o App na Meta ​

  1. Acesse https://developers.facebook.com/
  2. My Apps > Create App
  3. Tipo: Business
  4. Nome: Decaelo WhatsApp (ou similar)
  5. Selecione ou crie um Business Portfolio

2. Adicionar WhatsApp Product ​

  1. No dashboard do app, clique Add Product > WhatsApp > Set Up
  2. Selecione o Business Portfolio
  3. A Meta criara automaticamente um WhatsApp Business Account (WABA) de teste

3. Configurar Webhook ​

  1. Va em WhatsApp > Configuration (menu lateral)
  2. Em Webhook:
    • Callback URL:
      https://decaelo.com.br/webhooks/whatsapp
    • Verify Token: gere um token aleatorio (ex: decaelo-whatsapp-verify-2026) e anote-o — sera usado ao cadastrar a conta no painel admin
  3. Clique Verify and Save
  4. Em Webhook Fields, marque:
    • messages — receber mensagens inbound
    • message_deliveries — status de entrega (optional)

4. Obter Credenciais ​

  1. Va em WhatsApp > API Setup
  2. Anote:
    • Phone Number ID — identificador do numero de teste
    • WhatsApp Business Account ID — WABA ID
    • Temporary Access Token — token de 24h para testes
  3. Para token permanente:
    • Va em Settings > Basic > anote o App Secret
    • Va em Business Settings > System Users > crie um system user
    • Gere um token permanente com permissao whatsapp_business_messaging

5. Configurar .env no Servidor ​

env
META_WHATSAPP_APP_SECRET=abc123def456  # App Secret do app WhatsApp (para validar webhook signature)

6. Rodar Migration do Banco Central ​

A tabela audits precisa existir no banco central para que o model WhatsAppAccount funcione (ele usa o trait Auditable). Essa migration ja esta inclusa e roda automaticamente com app:setup ou php artisan migrate.

Se o banco central ja existe e voce esta adicionando o WhatsApp pela primeira vez:

bash
docker compose exec app php artisan migrate

7. Cadastrar Conta no Painel Admin ​

  1. Acesse /admin/whatsapp-accounts
  2. Clique Nova Conta
  3. Preencha:
    • Tenant: selecione a igreja
    • Phone Number ID: do passo 4
    • WABA ID: do passo 4
    • Numero: numero de WhatsApp (ex: +5511999999999)
    • Access Token: token permanente do passo 4
    • Verify Token: o mesmo usado no webhook (passo 3)
    • Webhook Secret: App Secret (para validacao HMAC)
  4. Salve e ative

8. Testar ​

  1. No API Setup da Meta, envie uma mensagem de teste para seu numero
  2. Verifique nos logs: docker compose logs horizon --tail=20
  3. A mensagem deve aparecer no painel de conversas da igreja

9. Producao — Numero Real da Igreja ​

  1. WhatsApp > API Setup > Add Phone Number
  2. Registre o numero da igreja (sera verificado via SMS/ligacao)
  3. Atualize o Phone Number ID no painel admin
  4. Envie templates para aprovacao em WhatsApp > Message Templates

Resumo de URLs e Tokens ​

ItemValor
Webhook URLhttps://decaelo.com.br/webhooks/whatsapp
Webhook Verify TokenDefinido por voce ao cadastrar a conta
Webhook Secret (HMAC)App Secret do app WhatsApp na Meta
Access TokenToken permanente do System User
Callback do Social Loginhttps://decaelo.com.br/auth/facebook/callback (app separado!)

Troubleshooting ​

ProblemaCausaSolucao
419 Page Expired no webhookCSRF bloqueando POSTAdicionar webhooks/* em validateCsrfTokens(except:) no bootstrap/app.php
403 no webhook POSTHMAC signature nao confereVerificar que webhook_secret da conta = App Secret do app WhatsApp na Meta
403 no webhook GET (verificacao)verify_token nao encontrado no bancoCadastrar a conta no painel admin ANTES de configurar webhook na Meta
Table 'tenantalfa.whatsapp_accounts' doesn't existModel sem getConnectionName()WhatsAppAccount deve retornar config('tenancy.database.central_connection')
Database connection [central] not configuredCodigo usa ::on('central') hardcodedUsar WhatsAppAccount::where(...) (model resolve a connection sozinho)
Table 'decaelo.audits' doesn't existMigration de audits so existe em tenant/Rodar php artisan migrate (migration central de audits adicionada)
Jobs nao processam (Horizon silencioso)APP_ENV nao configurado no horizon.phpAdicionar environment em config/horizon.php com as queues whatsapp-*
Recipient phone number not in allowed listModo dev da Meta, numero nao na allowlistAdicionar numero em API Setup > "Ate" na Meta. Nao ocorre em producao
Numero truncado no fromBug da Meta com numero de teste americanoUsar numero real da igreja em producao resolve

Feature Flags ​

FlagDescrição
whatsapp_basicNotificações + IA nível básico
whatsapp_intermediateIA com acesso a dados do membro
whatsapp_completeIA com ações executáveis
whatsapp_custom_promptSystem prompt customizável

Páginas do Painel Admin ​

PáginaRotaDescrição
Conversas/whatsapp/conversationsLista de conversas com filtro por status
Chat/whatsapp/conversations/{ulid}Chat em tempo real (atendente)
Templates/whatsapp/templatesGestão de templates Meta
Configuração IA/whatsapp/configurationPersonalidade, prompts, saudação
Créditos/whatsapp/creditsUso mensal e compra de créditos extras

Permissões ​

PermissãoDescrição
whatsapp.viewVisualizar conversas
whatsapp.replyResponder como atendente
whatsapp.manageGerenciar templates e configuração IA
whatsapp.creditsVisualizar e comprar créditos