Capítulo 21 — Comunicação Omnichannel

21.1 Objetivo do Capítulo

Este capítulo detalha o módulo de Comunicação Omnichannel da Plataforma de Relacionamento Digital com o Cidadão, descrevendo como a plataforma gerencia o envio, o recebimento, a rastreabilidade e a governança de comunicações com cidadãos em múltiplos canais — de forma desacoplada dos domínios de negócio que as originam.

O módulo de comunicação não é um simples adaptador de e-mail ou SMS. É a camada que abstrai provedores, respeita preferências e consentimentos, versionna templates, rastreia entregas, processa falhas com retry e oferece ao gestor visibilidade sobre o engajamento dos cidadãos com as comunicações enviadas pelo órgão.

21.2 Papel da Comunicação Omnichannel

A comunicação é o ponto de contato entre a plataforma e o cidadão após cada evento relevante. Ela transforma fatos de negócio em mensagens úteis e contextualidazas:

Qualquer domínio produz evento relevante
    │
RabbitMQ recebe o evento
    │
Communication Service consome e orquestra:
    ├── Resolve template para o evento e o tenant
    ├── Carrega preferências e consentimentos do cidadão
    ├── Seleciona canal de entrega
    ├── Renderiza conteúdo com variáveis
    ├── Aciona adaptador do canal
    ├── Registra tentativa e status
    └── Processa callback de entrega
    │
Cidadão recebe mensagem no canal preferido
    │
Métricas de engajamento disponíveis no painel do gestor

O domínio de Solicitações não implementa cliente de SMS. O domínio de BPM não implementa template de e-mail. Cada domínio registra o fato; o Communication Service decide o quê, quando, como e para onde enviar.

21.3 Princípios da Comunicação Omnichannel

1. Desacoplamento — os domínios de negócio publicam eventos ou comandos; o Communication Service resolve canal, template e entrega sem que o produtor precise conhecer esses detalhes;
2. Canal como detalhe de implementação — a lógica de comunicação é agnóstica ao canal; um template pode ser renderizado para e-mail, SMS, push ou WhatsApp conforme a preferência do cidadão;
3. Preferências respeitadas — o canal de entrega considera a preferência registrada do cidadão, respeitando consentimentos e distinções entre comunicações obrigatórias e opcionais;
4. Rastreabilidade end-to-end — cada comunicação registra: origem, tentativas, canal, status de entrega e resposta do cidadão;
5. Resiliência — falhas de entrega em um canal não comprometem o fluxo de negócio; retry e fallback de canal são tratados pelo próprio módulo;
6. Templates versionados — mudanças de conteúdo seguem ciclo de vida controlado, sem alterar comunicações históricas;
7. Separação de categorias — comunicações necessárias ao serviço são diferenciadas de campanhas opcionais; o cidadão não pode revogar o consentimento de comunicações transacionais obrigatórias, mas pode revogar o de campanhas;
8. Isolamento por tenant — templates, configurações, histórico e métricas de comunicação de um tenant são inacessíveis por outro.

21.4 Atores da Comunicação Omnichannel

21.5 Canais Disponíveis

Canais são habilitados por tenant. Um tenant pode operar com portal e e-mail apenas, enquanto outro habilita todos os canais. A adição de novos canais é feita por novo adaptador sem alterar a lógica central.

21.6 Estrutura Funcional

┌──────────────────────────────────────────────────────────────┐
│  TEMPLATES E CONTEÚDO                                         │
│  Criação, versionamento, aprovação e renderização de templates│
├──────────────────────────────────────────────────────────────┤
│  ORQUESTRAÇÃO DE ENVIO                                        │
│  Resolução de canal, renderização, disparo e registro         │
├──────────────────────────────────────────────────────────────┤
│  NOTIFICAÇÕES TRANSACIONAIS                                   │
│  Comunicações automáticas geradas por eventos de negócio     │
├──────────────────────────────────────────────────────────────┤
│  CENTRAL DE MENSAGENS                                         │
│  Caixa unificada do cidadão e histórico de comunicações      │
├──────────────────────────────────────────────────────────────┤
│  CAMPANHAS                                                    │
│  Criação, aprovação, execução e métricas de campanhas        │
├──────────────────────────────────────────────────────────────┤
│  PREFERÊNCIAS E CONSENTIMENTOS                                │
│  Canais preferidos, opt-in, opt-out e políticas de LGPD      │
└──────────────────────────────────────────────────────────────┘

21.7 Templates e Conteúdo

21.7.1 Modelo de Template

Um template representa o conteúdo base de um tipo de comunicação para um canal específico:

Template
  id
  tenantId
  name
  purpose          (TRANSACTIONAL, INSTITUTIONAL, CAMPAIGN)
  channel          (PORTAL, EMAIL, SMS, PUSH, WHATSAPP)
  language
  status           (DRAFT, REVIEW, APPROVED, ACTIVE, DEPRECATED)
  currentVersionId

TemplateVersion
  id
  templateId
  tenantId
  version
  subject          (para e-mail)
  bodyText         (texto simples ou SMS)
  bodyHtml         (para e-mail e portal)
  bodyPush         (título e corpo curto para push)
  variables        (lista de variáveis declaradas com tipo e obrigatoriedade)
  createdAt
  approvedAt
  approvedBy

21.7.2 Variáveis de Template

Templates declaram variáveis que são resolvidas no momento da renderização:

Olá, {{cidadao_nome}}.

Sua solicitação {{protocolo_numero}} foi atualizada.
Situação atual: {{situacao_label}}.

Acesse: {{link_acompanhamento}}

Variáveis com dados pessoais são minimizadas — apenas o necessário para a comunicação.

21.7.3 Ciclo de Vida

Rascunho → Em revisão → Aprovado → Ativo → Depreciado

Apenas versões ativas são utilizadas no envio. A depreciação não afeta comunicações históricas — o registro da comunicação preserva a versão utilizada. A publicação de nova versão não desativa a anterior automaticamente; a depreciação é ação explícita.

21.7.4 Preview e Teste

Antes da aprovação, o gestor visualiza o template renderizado com dados de exemplo e pode enviar um teste para endereço ou número de validação configurado. O teste é registrado separadamente do histórico de comunicações ao cidadão.

21.7.5 Templates WhatsApp

Templates enviados pelo canal WhatsApp devem ser previamente aprovados pelo Meta. A plataforma gerencia o ciclo de aprovação: submissão, status de aprovação recebido via callback, ativação automática após aprovação, registro de rejeição com motivo.

21.8 Orquestração de Envio

21.8.1 Fluxo de Envio Transacional

Domínio publica evento (ex.: request.submitted.v1)
    │
Communication Service consome
    │
Resolve regra de comunicação para o tipo de evento e o tenant
    │
Resolve template ativo para o evento e o canal selecionado
    │
Carrega preferências do cidadão (canal preferido, idioma)
    │
Verifica consentimento quando a categoria exige
    │
Renderiza conteúdo com variáveis do evento
    │
Registra Communication com status REQUESTED
    │
Aciona adaptador do canal selecionado
    │
Registra CommunicationAttempt com status SENT ou FAILED
    │
Processa callback de entrega do provedor (assíncrono)
    │
Atualiza status: DELIVERED, READ, FAILED
    │
Publica evento communication.delivered.v1 ou communication.failed.v1

21.8.2 Comando de Comunicação Direta

Para comunicações iniciadas manualmente (atendente enviando mensagem ao cidadão no CRM), o Communication Service recebe um comando explícito:

POST /communications
{
  "tenantId": "tenant-abc",
  "recipientId": "citizen-xyz",
  "channel": "EMAIL",
  "templateId": "tmpl-001",
  "variables": {
    "protocolo_numero": "2026/001234",
    "situacao_label": "Em análise"
  },
  "correlationId": "corr-xyz",
  "causationId": "interaction-456"
}

21.8.3 Seleção de Canal

O canal de entrega é determinado por: preferência registrada do cidadão para a categoria de comunicação, canal especificado no comando quando é comunicação manual, regra de canal obrigatório para o tipo de evento (ex.: alertas de segurança sempre por e-mail, independente de preferência), disponibilidade e status do canal no momento do envio.

21.8.4 Fallback de Canal

Quando o canal preferido falha após as retentativas configuradas, a política de fallback é avaliada:

E-mail falhou após 3 tentativas
    │
Fallback habilitado para o tipo de comunicação?
    ├── Sim → Tentar canal alternativo (ex.: portal)
    └── Não → Registrar falha e alertar

O fallback não é automático para todos os tipos — comunicações sensíveis podem não ter fallback para evitar entrega em canal não autorizado.

21.9 Notificações Transacionais

Notificações transacionais são comunicações automáticas geradas por eventos de domínio. São obrigatórias para a execução do serviço e não dependem de consentimento de campanha.

21.9.1 Catálogo de Notificações Transacionais

21.9.2 Lembretes e Alertas Temporais

Além de notificações por eventos, a plataforma envia lembretes temporais:

• lembrete de agendamento (24h e 1h antes, configurável);
• alerta de documento com validade próxima ao vencimento;
• alerta de prazo de complementação próximo ao vencimento;
• lembrete de solicitação aguardando complementação há N dias.

Esses alertas são gerados por jobs agendados que consultam o estado atual e publicam comandos de comunicação quando o critério é atendido.

21.10 Central de Mensagens

A Central de Mensagens é a caixa de mensagens interna do cidadão no portal e no aplicativo.

21.10.1 Funcionalidades para o Cidadão

• listar mensagens recebidas (recentes, não lidas, arquivadas);
• visualizar detalhe da mensagem;
• marcar como lida;
• arquivar mensagem;
• responder quando o canal permite resposta bidirecional;
• filtrar por data, tipo e situação;
• acessar protocolo ou solicitação vinculada diretamente da mensagem.

21.10.2 Funcionalidades para o Atendente / Gestor

• visualizar histórico de comunicações do cidadão no contexto do tenant;
• consultar status de entrega de cada comunicação;
• reenviar comunicação quando autorizado e configurado;
• iniciar nova comunicação a partir da ficha do cidadão.

21.10.3 Mensagens In-App

Além do canal Portal (mensagens na caixa da central), a plataforma suporta notificações in-app: alertas visuais que aparecem na interface enquanto o cidadão está navegando, sem exigir acesso à central de mensagens.

21.11 Campanhas de Comunicação

Campanhas são comunicações ativas, segmentadas e não necessariamente associadas a um evento transacional imediato. Requerem aprovação antes da execução e respeitam consentimentos de comunicação.

21.11.1 Ciclo de Vida de Campanha

Rascunho → Revisão → Aprovada → Agendada → Em execução → Concluída
                                               │
                                            Pausada
                                               │
                                         Retomada ou Cancelada

21.11.2 Configuração de Campanha

21.11.3 Execução

Ao iniciar a execução, a campanha:

1. obtém o público do Segmentation Service (lista de recipientIds);
2. valida consentimentos individuais;
3. gera comandos de comunicação em lote, processados pelo Communication Service;
4. registra métricas progressivas de envio, entrega e interação.

Campanhas de grande volume são processadas em jobs paralelos para evitar sobrecarga dos adaptadores de canal e respeitar rate limits de provedores.

21.11.4 Métricas de Campanha

21.12 Preferências e Consentimentos

21.12.1 Categorias de Comunicação

A plataforma distingue quatro categorias:

21.12.2 Gestão de Preferências pelo Cidadão

O cidadão gerencia suas preferências no portal e no aplicativo:

• canal preferido por categoria de comunicação;
• horário preferido para receber notificações (quando o provedor suporta);
• opt-in e opt-out por categoria;
• histórico de consentimentos com data e canal de registro.

21.12.3 Opt-out

O opt-out de uma campanha ou categoria é registrado imediatamente e aplicado antes do próximo envio. O cancelamento de envios já em processamento pode não ser total para campanhas de grande volume em execução — a plataforma garante que novos lotes respeitam o opt-out registrado.

21.12.4 Comunicações e LGPD

• a finalidade de cada categoria de comunicação é documentada;
• consentimentos de campanha são revogáveis;
• o histórico de consentimentos é auditável;
• dados pessoais em comunicações são minimizados — o template usa apenas o necessário para contextualizar a mensagem;
• comunicações de segurança não dependem de consentimento e não são opt-out — são necessárias à proteção da conta do cidadão.

21.13 Resiliência e Tratamento de Falhas

21.13.1 Falhas Transitórias

Falhas transitórias de canal (timeout, HTTP 5xx do provedor, indisponibilidade temporária) accionam retry com backoff exponencial e jitter:

Tentativa 1 → falha transitória
    │
Retry 1 → aguardar 1 minuto
    │
Retry 2 → aguardar 5 minutos
    │
Retry 3 → aguardar 15 minutos
    │
Falha permanente → DLQ + alerta + registro de status FAILED

21.13.2 Falhas Permanentes

Falhas permanentes (endereço de e-mail inválido, número de telefone inexistente, token de push inativo) são registradas sem retry:

• status da tentativa: FAILED_PERMANENT;
• motivo registrado: tipo de erro do provedor;
• preferência de canal pode ser atualizada automaticamente quando o erro indica canal inativo.

21.13.3 Bounces e Respostas do Provedor

Bounces de e-mail são processados via callback do provedor:

• hard bounce (endereço inválido): e-mail marcado como inválido nos contatos do cidadão; alerta ao tenant;
• soft bounce (caixa cheia, indisponibilidade): retentativa após intervalo.

Tokens de push inativos (app desinstalado) são removidos automaticamente ao receber erro correspondente do APNS ou FCM.

21.13.4 Idempotência

O Communication Service é idempotente por communicationId. Receber o mesmo comando de comunicação mais de uma vez (por retry no RabbitMQ) não gera envio duplicado ao cidadão. A deduplicação usa o identificador único da comunicação como chave de idempotência.

21.14 Adaptadores de Canal

Cada canal é encapsulado em um adaptador que implementa a interface de canal da plataforma:

interface ChannelAdapter {
    SendResult send(ChannelMessage message);
    boolean supportsChannel(ChannelType channel);
}

Adaptadores disponíveis:

A troca de provedor de e-mail ou SMS é realizada substituindo o adaptador específico sem alterar a lógica do Communication Service.

21.15 Modelo de Dados

Communication
  id
  tenantId
  recipientId        (cidadão)
  category           (TRANSACTIONAL, INSTITUTIONAL, CAMPAIGN, SECURITY)
  channel            (PORTAL, EMAIL, SMS, PUSH, WHATSAPP)
  templateId
  templateVersionId
  variables          (JSONB com variáveis utilizadas na renderização)
  subject            (e-mail)
  bodyRendered       (conteúdo renderizado, minimizado se contém PII)
  status             (REQUESTED, SENT, DELIVERED, READ, FAILED, CANCELLED)
  causationId        (evento que originou a comunicação)
  correlationId
  requestedAt
  sentAt
  deliveredAt
  readAt

CommunicationAttempt
  id
  communicationId
  tenantId
  channel
  attemptNumber
  provider
  providerMessageId
  status
  failureReason
  attemptedAt
  responseAt

ProviderCallback
  id
  communicationId
  tenantId
  channel
  provider
  eventType          (DELIVERED, READ, BOUNCED, FAILED, OPT_OUT)
  rawPayload
  processedAt

CitizenCommunicationPreference
  id
  citizenId
  tenantId
  category
  channel            (canal preferido para a categoria)
  optIn              boolean
  updatedAt
  consentRegisteredAt
  consentChannel     (onde o opt-in foi registrado)

21.16 Eventos Publicados

21.17 Integrações com Outros Módulos

21.18 Configuração por Tenant

Cada tenant configura sua comunicação de forma independente:

• canais habilitados e suas credenciais;
• templates por tipo de evento e canal;
• regras de comunicação: quais eventos disparam quais templates;
• políticas de fallback de canal por categoria;
• política de horário de envio (janelas permitidas para campanhas);
• aprovadores de campanhas e templates;
• opt-in padrão por categoria para novos cidadãos.

21.19 Métricas Operacionais

21.20 Rastreabilidade com o Anexo III

O módulo atende aos itens do Bloco 1 do Anexo III relacionados à comunicação:

21.21 Benefícios do Módulo

• domínios de negócio desacoplados de provedores de comunicação;
• single responsibility: o Communication Service decide como entregar;
• templates versionados preservam rastreabilidade do conteúdo enviado;
• preferências e consentimentos respeitados automaticamente, sem lógica nos domínios;
• resiliência com retry, fallback e DLQ sem impacto nos fluxos de negócio;
• troca de provedor por substituição de adaptador;
• métricas de engajamento centralizadas para todos os canais;
• campanhas com ciclo de aprovação que reduz risco de comunicações não autorizadas;
• isolamento completo por tenant.

21.22 Riscos e Mitigações

21.23 Decisões Arquiteturais

21.24 Considerações Finais

A comunicação omnichannel é o instrumento pelo qual a plataforma mantém o cidadão informado sobre tudo o que acontece com suas solicitações, agendamentos, documentos e manifestações — sem exigir que ele entre no portal para verificar atualizações. Quando bem executada, ela transforma a experiência de um serviço público digital em uma relação de confiança: o cidadão sabe que receberá notícias quando algo acontecer.

O desacoplamento entre os domínios de negócio e os provedores de canal, combinado com templates versionados, preferências respeitadas e rastreabilidade completa, garante que a comunicação evolua com a plataforma sem criar dependências que fragilizem a operação.

O Capítulo 22 detalha o módulo de Agendamentos, descrevendo como a plataforma gerencia agendas, disponibilidade, marcação e controle de concorrência.

21.25 Controle de Versão

21.26 Rastreabilidade PRODEMGE

• [ANX-III] Bloco 1 — Relacionamento e Atendimento Multicanal: itens 1.1, 1.7, 1.8, 1.9 e 1.11 cobertos conforme seção 21.20.
• [ANX-IV] — Capacidades técnicas de comunicação omnichannel, templates, campanhas, rastreabilidade de entrega e integração com provedores externos.
• [ANX-V] — Sustentabilidade: adaptadores desacoplados permitem troca de provedor; versionamento de templates; resiliência por retry e DLQ.
• [PNR] — Plano de Negócio Referencial: plataforma com capacidade de comunicação ativa em múltiplos canais, campanhas segmentadas e rastreamento de engajamento do cidadão.
• [EDITAL] — Edital CP001/2026: módulo de comunicação integrado às jornadas do cidadão, com múltiplos canais e métricas de desempenho.