Envio de Campanhas

1. Visão Geral

A funcionalidade Envio de Campanhas permite realizar disparos de comunicação em massa através dos canais Push e WhatsApp, utilizando uma lista de destinatários importada por arquivo CSV.

A funcionalidade tem como objetivo centralizar o gerenciamento de campanhas, permitindo:

• Criação de campanhas de comunicação;

• Seleção de templates previamente configurados;

• Importação de destinatários via arquivo CSV;

• Personalização de mensagens através de macros;

• Aprovação controlada antes do disparo;

• Monitoramento de processamento e resultados.

2. Objetivo

Capacitar desenvolvedores e stakeholders técnicos com uma compreensão clara do fluxo, arquitetura e requisitos para o uso eficaz do módulo de envio de campanhas, garantindo a integração e operação adequadas dentro do ecossistema Mosia Omnichannel.

2.1 Cenário anterior

Antes da disponibilização da funcionalidade, os clientes realizavam comunicações em massa utilizando processos manuais ou ferramentas externas.

Os principais problemas identificados eram:

• Necessidade de gerar listas manualmente;

• Dificuldade para personalizar mensagens por beneficiário;

• Ausência de rastreabilidade dos disparos;

• Falta de controle de aprovação antes do envio;

• Dificuldade para identificar entregas, falhas e interações.

Em muitos cenários, o envio era realizado sem validações adequadas, aumentando a possibilidade de comunicação para destinatários incorretos.

2.2 - Riscos identificados

Segurança

• Usuários sem autorização poderiam realizar disparos em massa;

• Ausência de controle de permissões poderia expor informações de beneficiários.

Fraude

• Disparos indevidos utilizando a base de beneficiários;

• Alteração incorreta de listas de destinatários.

Operacional

• Envios sem aprovação;

• Falta de rastreabilidade sobre quem criou e quem autorizou a campanha.

Experiência do usuário

• Mensagens sem personalização;

• Falta de acompanhamento do status de entrega.

3. Pré-requisitos

Para acessar e utilizar a funcionalidade de envio de campanhas, o perfil de usuário logado no painel da plataforma deve possuir a permissão específica para envio de campanha habilitada. Esta permissão é configurada no painel de administração de usuários.

Requisito	Responsável	Verificação

Requisito	Responsável	Verificação
Perfil/permissão necessária	Administrador	Open
Templates de WhatsApp ou Push cadastrados e aprovados	Administrador	Cadastro de Templates de WhatsApp / Push

4. Arquitetura

A funcionalidade opera com os seguintes componentes e fluxos lógicos:

• Front-end: Interface do usuário para configuração, upload e monitoramento.

• Back-end: Gerencia o fluxo de criação, aprovação, processamento e disparo das campanhas.

• Serviço de Armazenamento: Para templates, arquivos CSV e dados de campanha.

• Serviços de Envio de Mensagens:

  • Push: Integração com um serviço de notificações push.

  • WhatsApp: Integração com a API do WhatsApp Business.

• Base de Dados: Armazena informações de campanhas, destinatários e métricas.

• Serviço de Notificação: Envio de e-mails de status.

• Módulo de contatos: Base de contatos utilizada para campanhas WhatsApp.

5. Fluxos de Envio de Campanha

O fluxo principal para o envio de qualquer tipo de campanha (Push ou WhatsApp) é composto por cinco etapas sequenciais:

Open

1. Configuração Inicial: Definição do tipo e nome da campanha, e ambiente.

2. Seleção de Template: Escolha de um template de mensagem pré-definido.

3. Upload de Arquivo CSV: Importação da lista de destinatários.

4. Mapeamento de Variáveis: Associação das colunas do CSV com os campos obrigatórios e macros do template.

5. Revisão e Submissão: Validação final e envio para aprovação.

Após a submissão, a campanha entra em um fluxo de aprovação e processamento.

5.1. Interface do Usuário (Dashboard)

A funcionalidade de envio de campanha é acessível via menu: Mensageria > Envio de Campanha.

Open

Elementos principais da interface:

1. Botão Atualizar: Atualiza a lista de campanhas e seus status.

2. Filtro Status: Permite filtrar campanhas pelos seguintes status:

• • Rascunho

  • Pendente Aprovação

  • Processando

  • Concluída

  • Falha

  • Cancelada

3. Filtro Canal: Permite filtrar campanhas por tipo:

• • WhatsApp

  • Push

4. Botões de Criação:

• • + Sandbox: Cria uma nova campanha no ambiente de homologação/teste.

  • + Produção: Cria uma nova campanha diretamente no ambiente de produção.

5.2. Detalhes do Fluxo

5.2.1. Criação da Campanha (Etapa 1: Configuração)

1. O usuário clica em + Sandbox ou + Produção.

2. Seleção do Tipo de Campanha: Escolhe entre WhatsApp ou Push.

3. Nome da Campanha: Define um nome para identificação.

   • Exemplo: Envio de Campanha: Vacinação

Open

5.2.2. Seleção de Template (Etapa 2: Template)

1. O usuário seleciona um template de mensagem pré-criado na plataforma.

2. Tipos de Templates:

   • Mensagem Fixa: Template com conteúdo estático.

   • Com Macros: Template que permite a inserção de variáveis (macros) para personalização do conteúdo.

3. Referência: Para detalhes sobre a criação, gerenciamento e utilização de templates e macros, consulte a documentação específica de Macros e Templates

Open

5.2.3. Upload de Arquivo CSV (Etapa 3: Envio do Arquivo CSV)

1. O usuário faz o upload de um arquivo .csv contendo a lista de destinatários.

2. Processamento: Após o upload, o sistema processa o arquivo e exibe as colunas detectadas, preparando para o mapeamento.

3. Arquivo exemplo:

   campanha_vacinacao_push.csv

    

Open

4. Estrutura:

Open

5.2.4. Mapeamento de Variáveis (Etapa 4: Mapeamento)

Nesta etapa, o usuário associa as colunas do arquivo CSV aos campos obrigatórios do sistema e às macros definidas no template.

Campos Obrigatórios Comuns (Push e WhatsApp):

• Chave Única: Campo do CSV que identifica de forma exclusiva cada destinatário.

  • Exemplos: CPF, Matrícula, ID de Beneficiário.

• Nome: Campo do CSV que contém o nome do destinatário.

Open

Campos Obrigatórios Adicionais (Apenas para Campanhas WhatsApp):

• Email: Campo do CSV com o endereço de e-mail do destinatário.

• Telefone: Campo do CSV com o número de telefone/celular do destinatário.

  • Justificativa: Estes campos são necessários para criar ou atualizar os contatos na base "Mobile Saúde" da plataforma, permitindo o registro do histórico de comunicação.

Open

Mapeamento de Macros:

• Se o template selecionado contiver macros (ex: {{nome_beneficiario}}, {{mensagem}}), o usuário deve selecionar a coluna correspondente no CSV para cada macro.

  • Exemplo: A macro {{nome_beneficiario}} seria mapeada para a coluna nome do CSV. A macro {{mensagem}} poderia ser mapeada para uma coluna assunto do CSV.

• Observação: Templates não precisam necessariamente ter macros; a mensagem pode ser totalmente fixa.

Open

5.2.5. Revisão e Submissão (Etapa 5: Resumo e Envio)

1. A plataforma apresenta um resumo detalhado da campanha, incluindo:

   • Nome da Campanha

   • Canal (Push ou WhatsApp)

   • Template Selecionado

   • Nome do Arquivo CSV

   • Prévia da Mensagem (mostrando como as macros seriam preenchidas com dados de exemplo do CSV).

2. Um checklist de validação é exibido para confirmar que todas as configurações foram realizadas:

   • Nome definido [CHECK]

   • Canal selecionado [CHECK]

   • Template selecionado [CHECK]

   • Arquivo carregado [CHECK]

   • Mapeamento configurado [CHECK]

3. O usuário clica em Submeter para Aprovação.

Open

5.2.6. Processo de Aprovação

1. Após a submissão, a campanha assume o status Pendente Aprovação.

2. Segregação de Função: O usuário que criou a campanha não pode aprová-la. É necessário que um usuário com a permissão de Autorizador (ou perfil similar) realize a aprovação.

3. O usuário Autorizador acessa o painel, localiza a campanha Pendente Aprovação, entra nos detalhes da campanha e seleciona Aprovar Campanha -> Aprovar e Disparar.

4. Uma vez aprovada, a campanha é colocada em uma fila de processamento e seu status muda para Processando.

5.2.7. Acompanhamento e Métricas Pós-Disparo

Open

1. Notificação: Após a conclusão do processamento (seja sucesso ou falha), o usuário criador da campanha recebe uma notificação por e-mail.

2. Atualização de Status: O status da campanha é atualizado para Concluída ou Falha no painel.

3. Visualização de Métricas: Ao acessar os detalhes da campanha concluída, são exibidas:

   • Dados Gerais: Data de Criação, Data de Processamento, Criador da Campanha, Aprovador da Campanha.

   • Métricas Agregadas:

     • Total de Destinatários

     • Total Disparado

     • Total Não Disparado (Falha no envio interno da plataforma, por exemplo)

     • Enviadas (para o provedor de serviço)

     • Fora do Envio (motivos internos de exclusão)

     • Entregues (ao dispositivo/destinatário)

     • Lidas

     • Clicadas

     • Respondidas

   • Gráfico de Funil de Conversão: Representação visual das métricas (Enviadas, Falhas, Entregues, Lidas, Clicadas, Respondidas).

   • Detalhamento por Destinatário: Uma lista individual com:

     • Identificador (Chave Única)

     • Status (Enviado, Não Enviado, Erro, Entregue em [data/hora], Lido em [data/hora], Clicado em [data/hora]).

5.2.8. Relatórios

Open

1. Download do Resultado: A plataforma oferece um botão para Download do Resultado da Campanha em formato CSV.

2. Conteúdo do CSV de Relatório:

   • Chave Única

   • Status (Final do destinatário)

   • Data de Envio

   • Data de Leitura

   • Data de Clique

   • Data de Entrega

   • Falha no Envio (se houver, com descrição)

   • Canal (WhatsApp ou Push)

   • Ambiente (Sandbox ou Produção)

Open

6. Regras de Negócio e Diferenças por Canal

6.1. Campanhas Push

• Destino: Disparo de notificações push para dispositivos.

• Mapeamento Obrigatório: Apenas Chave Única e Nome são campos mandatórios no mapeamento do CSV.

• Dados Requeridos no CSV: Destinatários com uma Chave Única e Nome.

6.2. Campanhas WhatsApp

• Destino: Envio de mensagens via WhatsApp.

• Mapeamento Obrigatório:

  • Chave Única

  • Nome

  • Email

  • Telefone

• Propósito dos Campos Adicionais (Email/Telefone): Estes dados são utilizados para criar ou atualizar os contatos na base "Mobile Saúde" da plataforma, garantindo um histórico completo de comunicação e perfil do contato.

• Dados Requeridos no CSV: Destinatários com Chave Única, Nome, Email e Telefone.

7. Observações Técnicas

• Formato CSV: A aderência rigorosa ao formato CSV delimitado por vírgulas é crucial para o correto parsing do arquivo de destinatários. Caracteres especiais e formatação incorreta podem levar a falhas no upload ou mapeamento.

• Sistema de Macros: O sistema de macros oferece flexibilidade para personalizar mensagens. A sintaxe e as macros disponíveis são definidas na documentação de .

• Processamento Assíncrono: O disparo das campanhas é um processo assíncrono e pode levar tempo, especialmente para grandes volumes de destinatários. A notificação por e-mail e o acompanhamento do status no painel são os métodos recomendados para verificar a conclusão.

• Segregação de Funções: A separação dos papéis de criador e aprovador de campanha é uma medida de controle e governança, garantindo que as campanhas sejam revisadas antes do disparo.

• Ambientes (Sandbox vs. Produção): A possibilidade de criar campanhas em ambientes distintos é fundamental para testes e validações antes do disparo em massa para usuários reais.