Sistema de Notificações
O centro nervoso da comunicação Romeo. Orquestra mensagens em 5 canais, respeita preferências do usuário e garante que nenhum evento importante passe despercebido.
- Versão
- 1.0
- Atualizado
- junho/2026
- Canais
- 5 ativos
- Status
- produção
Resumo
O Sistema de Notificações é a camada que conecta eventos do Romeo aos usuários finais. Cada ação relevante — novo lead, visita agendada, contrato assinado — gera um evento que o sistema processa, roteia e entrega no canal mais adequado.
O objetivo é entregar a informação certa, no momento certo, pelo canal certo. Isso significa respeitar preferências do usuário, evitar spam e garantir que notificações críticas nunca se percam.
PrincípioUma notificação não entregue é pior que nenhuma notificação. O sistema prioriza confiabilidade sobre velocidade — melhor atrasar 30s do que perder a mensagem.
Arquitetura do sistema
O sistema segue uma arquitetura event-driven com filas de processamento. Eventos entram, são enriquecidos, roteados e despachados para os canais apropriados.
Ação no sistema gera evento tipado (ex: LeadCreated, VisitScheduled)
Sistema adiciona contexto: dados do usuário, preferências, histórico
Regras decidem: quais canais, qual prioridade, qual template
Notificação entra em fila por canal (WhatsApp, Email, Push, etc.)
Worker consome fila e envia via provider (Twilio, SendGrid, FCM)
Confirmação de entrega/leitura atualiza status da notificação
Garantia de entrega: cada notificação tem retry automático (3 tentativas com backoff exponencial). Após falhas, vai para dead-letter queue e alerta o time de operações.
Tipos de notificação
Notificações são categorizadas por natureza e propósito. Isso permite tratamento diferenciado em termos de urgência, canal preferido e agrupamento.
| Tipo | Descrição | Exemplos |
|---|---|---|
| Transacional | Confirmações de ações do usuário | Proposta enviada, contrato assinado, pagamento confirmado |
| Alerta | Eventos que requerem atenção imediata | Lead perdendo SLA, documento vencendo, falha de pagamento |
| Lembrete | Eventos futuros agendados | Visita amanhã, contrato vence em 30 dias, renovação próxima |
| Informativo | Atualizações e novidades | Novo imóvel na carteira, relatório semanal, feature release |
| Marketing | Comunicação promocional (opt-in) | Campanha sazonal, upsell de serviços, convite para eventos |
| Sistema | Notificações técnicas | Manutenção programada, atualização de termos, mudança de API |
AgrupamentoNotificações do mesmo tipo e contexto são agrupadas em digest. Em vez de 10 emails sobre novos leads, o usuário recebe 1 resumo a cada hora.
Níveis de prioridade
Nem toda notificação é igual. O sistema define 4 níveis de prioridade que impactam velocidade de entrega, redundância de canais e persistência.
P1 — Crítica
| Aspecto | Comportamento |
|---|---|
| Latência | < 30 segundos |
| Canais | Todos habilitados (push + WhatsApp + SMS + email) |
| Retry | 5 tentativas, intervalo curto (10s, 30s, 1m, 5m, 15m) |
| Persistência | Não pode ser silenciada; aparece até ser lida |
| Exemplos | Fraude detectada, falha crítica, contrato expirado |
P2 — Alta
| Aspecto | Comportamento |
|---|---|
| Latência | < 2 minutos |
| Canais | Push + canal preferido do usuário |
| Retry | 3 tentativas, intervalo médio |
| Persistência | Fica em inbox até ser marcada como lida |
| Exemplos | Novo lead quente, proposta recebida, SLA próximo |
P3 — Normal
| Aspecto | Comportamento |
|---|---|
| Latência | < 15 minutos |
| Canais | Canal preferido do usuário |
| Retry | 2 tentativas |
| Persistência | Pode ser agrupada em digest |
| Exemplos | Visita confirmada, documento enviado, comentário em negociação |
P4 — Baixa
| Aspecto | Comportamento |
|---|---|
| Latência | Próximo digest (1h ou diário) |
| Canais | Email ou in-app apenas |
| Retry | 1 tentativa |
| Persistência | Sempre agrupada; pode ser suprimida |
| Exemplos | Relatório semanal, dicas do sistema, novidades do produto |
Preferências do usuário
Cada usuário controla como quer ser notificado. O sistema respeita essas preferências, mas pode sobrescrevê-las para notificações críticas (P1).
| Configuração | Opções | Padrão |
|---|---|---|
| Canal preferido | WhatsApp, Email, Push, SMS | |
| Horário silencioso | Início e fim (ex: 22h–7h) | Desabilitado |
| Digest de baixa prioridade | Imediato, Horário, Diário | Horário |
| Notificações de marketing | Habilitado, Desabilitado | Habilitado |
| Som/vibração (mobile) | Todos, Só alta prioridade, Nenhum | Todos |
| Preview no lock screen | Completo, Resumido, Oculto | Resumido |
Horário silenciosoDurante o horário silencioso, notificações P2–P4 são enfileiradas e entregues ao final do período. P1 sempre passam — se é 3h da manhã e há fraude, o usuário precisa saber.
Granularidade: além das configurações globais, usuários podem configurar por tipo de notificação (ex: "quero leads por WhatsApp, mas relatórios só por email").
Orquestração multicanal
O Romeo opera 5 canais de notificação. A orquestração decide qual usar baseado em tipo, prioridade, preferências e disponibilidade do canal.
| Canal | Melhor para | Limitações | Custo |
|---|---|---|---|
| Comunicação rápida, conversacional | Janela de 24h, templates aprovados | R$ 0,08–0,50/msg | |
| Conteúdo longo, documentos, histórico | Pode ir para spam, baixa urgência | R$ 0,001/msg | |
| Push (mobile) | Alertas instantâneos, alta urgência | Requer app instalado, pode ser silenciado | Gratuito |
| Push (web) | Usuários desktop, tempo real | Requer opt-in no browser, menos confiável | Gratuito |
| SMS | Fallback crítico, usuários offline | 160 chars, alto custo, sem mídia | R$ 0,10–0,20/msg |
Cascata de fallback
Para notificações P1 e P2, o sistema usa cascata: se o canal primário falha ou não tem confirmação de leitura em X minutos, tenta o próximo.
Primeiro disparo sempre via push. Se usuário tem app, é o mais rápido e barato.
Se push não foi lido, escala para WhatsApp. Alta taxa de abertura, chega mesmo com app fechado.
Último recurso para P1. SMS chega mesmo sem internet, mas tem custo alto. Usado só em emergências.
Deduplicação: se usuário leu no primeiro canal, os fallbacks são cancelados automaticamente. Ninguém recebe a mesma notificação 3 vezes.
Métricas e observabilidade
O sistema de notificações é monitorado em tempo real. Métricas são usadas para otimização contínua e alertas de degradação.
KPIs principais
| Métrica | Meta | Alerta |
|---|---|---|
| Taxa de entrega (delivery rate) | > 99.5% | < 98% |
| Taxa de abertura (open rate) | > 60% (push), > 40% (email) | < 50% / < 30% |
| Latência P50 (tempo até entrega) | < 5s (push), < 30s (WhatsApp) | > 15s / > 2min |
| Latência P99 | < 30s (push), < 5min (WhatsApp) | > 1min / > 10min |
| Taxa de opt-out | < 0.5% / mês | > 1% / mês |
| Notificações em dead-letter | < 0.1% | > 0.5% |
Dashboard de operações
O time de operações tem acesso a dashboard em tempo real com:
- Volume de notificações por canal (últimas 24h, 7d, 30d)
- Mapa de calor de horários de pico
- Filas por canal com tamanho e idade da mais antiga
- Taxa de erro por provider (Twilio, SendGrid, FCM)
- Top 10 templates mais usados e suas métricas
Alertas automáticosQuando métricas saem do threshold, o sistema alerta via Slack e PagerDuty. Degradação de entrega > 5% aciona oncall imediatamente.