O mapa de notificações é o documento que lista, antes do desenvolvimento, cada aviso que o sistema manda: o evento que dispara, quem recebe, por qual canal, em que momento, com que texto, o que acontece se não chegar e quem não deve receber. No app de saúde que estamos modelando, ele tem 78 notificações, e só 3 delas o usuário pode desligar. Feito antes do código, ele evita aviso para quem está afastado, código por WhatsApp parado à espera da aprovação da Meta e dado sensível na tela bloqueada do celular.
O que é um mapa de notificações#
O mapa de notificações é o documento que lista todos os avisos que um sistema manda, um por linha, antes de alguém escrever o código. Cada linha diz o que dispara o aviso, quem recebe, por qual canal, em que momento, com que texto e o que acontece se ele não chegar. Ele sai do escopo e serve de especificação para quem programa e de roteiro para quem testa.
No escopo, os avisos costumam aparecer espalhados, numa frase como "o cliente é avisado" no meio da descrição de um módulo. O mapa junta todas essas frases num lugar só e faz cada uma responder às mesmas perguntas.
Cada notificação recebe um código fixo, como AUTH-01 ou PAG-03, que acompanha o aviso no código-fonte, nos registros do servidor e nos testes. Quando um aviso sai do produto, o código dele é aposentado e não volta a ser usado.
O tamanho do mapa depende do produto. No app de saúde que estamos modelando, ele tem 78 notificações, para o paciente, para o médico e para a equipe que opera a plataforma. Num sistema de relatórios técnicos que mapeamos, ele tem duas, as duas por e-mail e as duas de acesso à conta. Os dois estão completos. O mapa é uma das peças que entregamos antes do desenvolvimento em todo sistema sob medida que manda aviso.
O que cada linha do mapa precisa dizer#
Uma linha completa responde a sete perguntas: qual evento dispara o aviso, quem recebe, por qual canal, quando sai, o que o texto diz, o que acontece se a entrega falhar e quem, mesmo envolvido no evento, não deve receber. Quando uma dessas fica em branco, a resposta acaba sendo dada por quem está programando, no meio da tarefa.
- O evento. O fato do sistema que dispara o aviso, escrito como ele acontece: "o pagamento foi aprovado", e não apenas "aviso de pagamento".
- Quem recebe. O perfil e, às vezes, a pessoa exata, como o responsável pelo caso, ou todos os administradores quando o caso ainda não tem responsável.
- O canal. E-mail, push, WhatsApp, SMS ou o aviso dentro do próprio sistema.
- Quando. Na hora, num horário fixo, um tempo antes de um compromisso ou depois de um prazo vencido.
- O texto. O assunto e o corpo, com as variáveis marcadas. As notificações de acesso à conta e as que explicam dinheiro têm o texto escrito no próprio mapa.
- Se falhar. O que o sistema faz quando o aviso não chega: tenta outro canal, guarda o aviso no sistema ou não faz nada, porque o aviso é opcional.
- Quem não recebe. A pessoa que, pela lógica do evento, receberia, e que por uma regra não deve receber.
O trecho abaixo junta linhas de mapas reais, com o texto encurtado.
| Evento | Quem recebe | Canal | Quando | Se falhar | Quem não recebe |
|---|---|---|---|---|---|
| Código de verificação no cadastro e no login | quem está entrando | WhatsApp ou SMS, à escolha da pessoa | na hora, com validade curta | o WhatsApp falhou e o código sai por SMS, sem a pessoa fazer nada | ninguém além do dono do número |
| Lembrete de consulta | paciente | push e e-mail | 24 h e 30 min antes, os dois ajustáveis | o aviso também fica na central de notificações do app | não sai se a consulta foi cancelada ou já começou |
| Lembrete de consulta | médico | push | 1 h e 10 min antes, ajustáveis | quem não permitiu push recebe por e-mail | não sai se a consulta foi cancelada ou já começou |
| E-mail da conta trocado | dono da conta | e-mail, no endereço antigo | na hora | sem segundo canal | o endereço novo, que pode estar com quem tomou a conta |
| Nova denúncia recebida | administradores ativos da empresa | e-mail, sem nada do relato | logo que o relato chega | sem segundo canal | quem denunciou, que não informa contato |
| Caso atribuído | o novo responsável | na hora | sem segundo canal | quem atribuiu o caso a si mesmo | |
| Falha no pagamento ou no repasse | administrador | no painel, no navegador e por e-mail, que não se desliga | na hora | o aviso fica no sino do painel | o operador da plataforma |
A primeira linha é do código por WhatsApp que estamos colocando na Helpe. As outras vêm do app de saúde que estamos modelando e do canal de denúncia anônimo que estamos construindo.
Por que fazer o mapa antes do código#
O mapa vem antes do código porque quase toda notificação depende de uma regra de negócio e de um canal com prazo e custo próprios, e as duas coisas mudam o que se constrói. Descobrir isso no meio do desenvolvimento custa tela e banco de dados refeitos, ou uma entrega parada à espera da aprovação de outra empresa.
A regra aparece primeiro na coluna "quem recebe". Para deixar de avisar quem está de férias, o sistema precisa ter esse dado guardado. No retorno da GT sobre o protótipo, em setembro, o cliente pediu um período de férias no cadastro do operador e que o operador inativo saísse da operação. O afastamento virou uma lista de períodos, com férias, atestado e licença no mesmo mecanismo, e a regra do aviso ficou escrita: operador afastado ou inativo não recebe checklist nem notificação, e o afastado fica sem login no app durante o período. Essa regra só funciona se o banco de dados guarda a situação de cada pessoa, por isso ela precisa estar decidida antes de o cadastro ser construído.
O canal traz prazos que não são da equipe de desenvolvimento. Na Helpe, o código de verificação por WhatsApp depende de a Meta aprovar o modelo de mensagem de autenticação, e o escopo da atualização diz por escrito que, sem essa aprovação, o envio por WhatsApp não funciona em produção. Antes disso, o login por SMS da Helpe precisou passar pela análise da própria AWS para disparar SMS no Brasil. São etapas que entram no cronograma no começo do projeto.
A contagem também muda quando alguém lê o escopo inteiro procurando aviso. Quando o escopo do app de saúde ainda tinha uma tabela própria de avisos, ela listava 39 eventos. Lendo módulo a módulo e passando pelas revisões, o mapa chegou a 78. Na mesma leitura, dois eventos do escopo, "pagamento aprovado" e "consulta confirmada", viraram uma notificação só, porque acontecem no mesmo momento e mandariam duas mensagens sobre o mesmo fato. E um lembrete que o escopo listava como opcional passou a ser essencial, porque o prazo dele é fixado em lei e o paciente não pode desligá-lo.
Os tempos do lembrete ficam ajustáveis nas configurações, porque o negócio muda esses números com o uso. O critério para decidir o que vira configuração está em quando parametrizar uma regra de negócio.
Quem não deve receber a notificação#
Quem não recebe é a coluna que mais protege o sistema, e a que quase ninguém pede. Ela costuma cobrir quatro casos: quem saiu da operação, quem não pode ser identificado, quem já sabe do fato e o endereço que pode estar com quem tomou a conta.
Quem saiu da operação. Na GT, o checklist e a notificação nem chegam ao app do operador afastado ou inativo.
Quem não pode ser identificado. No canal de denúncia anônimo que estamos construindo, quem denuncia recebe zero notificações. A pessoa não informa contato e acompanha o caso pelo protocolo. Os avisos vão só para a equipe da empresa, por e-mail, sem nada do conteúdo do relato. O desenho completo está em como garantir o anonimato num canal de denúncia.
Quem já sabe. No mesmo canal, o aviso de caso atribuído não sai quando a pessoa atribui o caso a si mesma. Enquanto o caso está marcado com mensagem nova, as mensagens seguintes não geram outro aviso.
O endereço que pode ter sido tomado. No app de saúde, o aviso de que o e-mail da conta mudou vai para o e-mail antigo. O aviso de que o segundo fator foi trocado vai para o e-mail da conta e nunca para o meio novo. Se alguém tomou a conta e trocou o contato, o dono de verdade ainda fica sabendo.
O que acontece quando a notificação não chega#
Quando a notificação não chega, o sistema faz o que o mapa mandou: tenta outro canal, guarda o aviso dentro do sistema ou não faz nada, se o aviso é opcional. E nenhuma regra do negócio depende de a pessoa ter visto o aviso.
Na Helpe, se o código por WhatsApp falha, ele sai por SMS automaticamente, sem o usuário precisar pedir de novo. No app de saúde, quando um push essencial não é entregue, o e-mail é acionado, e quem não permitiu push no celular recebe por e-mail todo aviso essencial que seria só push, como o lembrete do médico. O aviso opcional não tem reenvio.
No app de saúde, o que conta é o horário marcado e a presença registrada na sala, e não se o paciente leu o lembrete. A diretriz 4.5.4 da App Store diz o mesmo de outro jeito: o push não pode ser obrigatório para o aplicativo funcionar.
O e-mail também falha de um jeito silencioso, que é cair no spam. Segundo as diretrizes do Google para remetentes, todo domínio que manda e-mail para o Gmail precisa de autenticação SPF ou DKIM e precisa manter a taxa de spam abaixo de 0,3%. Quem manda mais de 5.000 mensagens por dia precisa também de DMARC. Essa configuração do domínio entra na lista de tarefas junto com o mapa.
Como escolher o canal de cada notificação#
O canal se escolhe pelo que o aviso precisa, como alcançar todo mundo, chegar na hora ou ficar guardado, e pela limitação de cada canal.
E-mail. Todo perfil tem, e é o canal de link seguro, de código e de conteúdo longo. É também o canal de reserva quando o push falha.
Push. Chega na hora e aparece na tela bloqueada. No sistema web, o Android recebe pelo navegador, e no iPhone o web push só existe desde o iOS 16.4, para sites adicionados à tela de início, e o pedido de permissão precisa partir de um toque da pessoa, como o WebKit anunciou em fevereiro de 2023. Quando o push no iPhone é essencial para o produto, a decisão volta para a pergunta de aplicativo ou sistema web.
WhatsApp. Tem regras da Meta para a empresa que inicia a conversa. Segundo a documentação da plataforma do WhatsApp Business, quando a janela de atendimento de 24 horas fecha, a empresa só pode mandar modelos de mensagem aprovados. Todo modelo é classificado como autenticação, utilidade ou marketing, e a análise pode levar até 24 horas. Código de verificação precisa usar o modelo de autenticação, com texto fixo. No app de saúde, o WhatsApp ficou fora dos avisos e serve só como contato da operação para dúvida geral.
SMS. Chega em qualquer celular, com pouco espaço. Segundo a documentação do serviço de SMS da AWS, uma mensagem cabe em 160 caracteres quando usa só o alfabeto GSM, e em 70 quando tem qualquer caractere fora dele. O til de "não" e o acento de "você" estão fora. Mensagem maior é dividida em partes, e cada parte é cobrada. No app de saúde, o SMS leva só o código de verificação.
No produto. É o aviso que aparece dentro do sistema, num sino ou numa central de notificações, com lido e não lido. Numa reunião de descoberta em setembro, um cliente colocou "histórico de notificações" na lista do que queria. No mapa, esse pedido vira uma decisão: quem tem central, o que entra nela e por quanto tempo fica guardado.
O que não vira notificação#
Notificação não é "manda um e-mail de tudo". O mapa também decide o que não vira aviso: o que a pessoa já está vendo na tela, a repetição do mesmo assunto, a campanha de marketing e o dado sensível.
As diretrizes de interface da Apple dão o exemplo do próprio Mail: quando chega uma mensagem na caixa que a pessoa está olhando, o aplicativo só acrescenta a mensagem à lista, sem notificação. As mesmas diretrizes pedem para não mandar várias notificações sobre a mesma coisa, mesmo que a pessoa não tenha respondido, porque ela pode acabar desligando todas as notificações do aplicativo.
No app de saúde, isso virou regra escrita: as mensagens de uma conversa em 2 minutos viram um aviso só, os avisos da operação do mesmo tipo são agrupados em 10 minutos, e o aviso que repete por uma pendência sai no máximo uma vez por dia.
Campanha também fica de fora. No app de saúde, nenhum módulo manda comunicação de novidades da empresa. A diretriz 4.5.4 da App Store só permite push de promoção ou marketing quando a pessoa aceitou receber, por um texto de consentimento dentro do app, e tem como sair.
E o conteúdo sensível não vai no aviso. As diretrizes da Apple pedem para não incluir informação sensível, pessoal ou confidencial numa notificação, porque não dá para saber quem está perto da tela. No app de saúde, push e e-mail nunca levam dado clínico, queixa, documento nem nome de paciente. O push mostra data, hora e o atalho, e o conteúdo fica dentro do app, depois do login.
Perguntas frequentes#
Todo sistema precisa de um mapa de notificações?#
Todo sistema que manda algum aviso precisa, mesmo quando o mapa sai pequeno. Num sistema de relatórios técnicos que mapeamos, ele tem duas notificações, as duas por e-mail e as duas de acesso à conta. Escrever isso deixou registrado que o cliente final não recebe nada automático e que o link do relatório é enviado pelo administrador. Sem o mapa, essa decisão ficaria para quem estivesse programando.
Quem faz o mapa de notificações?#
Nós fazemos, a partir do escopo validado e antes do desenvolvimento. O mapa sai em duas passadas: primeiro o documento completo, depois um relatório de cobertura que confere se cada evento do escopo tem uma linha no mapa e se toda linha do mapa vem de algo que o escopo descreve. O cliente revisa quem recebe cada aviso, o tom dos textos e o que pode ser desligado.
Dá para mandar notificação por WhatsApp em qualquer sistema?#
Dá, com três condições. Fora da janela de 24 horas aberta pela última mensagem do usuário, a empresa só pode mandar modelo de mensagem aprovado pela Meta. Código de verificação usa um modelo próprio de autenticação, com texto fixo. E o envio passa por um provedor da API oficial, que cobra pelos envios: na Helpe, o painel ganhou um atalho para a conta do provedor, onde a equipe acompanha o saldo. O prazo da aprovação é da Meta, por isso ele entra no cronograma como dependência.
O usuário pode desligar as notificações?#
Pode desligar as configuráveis, como o pedido de avaliação ou a sugestão de agendar de novo. As transacionais, que cobrem acesso à conta, dinheiro e andamento do serviço, saem sempre. No app de saúde que estamos modelando, das 78 notificações, 75 são transacionais e 3 são configuráveis.
Dá para ver o histórico de notificações dentro do sistema?#
Dá, com uma central de notificações, que guarda dentro do sistema o que a pessoa recebeu, com lido e não lido. No app de saúde que estamos modelando, todo aviso de push e de e-mail também entra na central. O mapa define quem tem central e por quanto tempo ela guarda os avisos.
Fontes#
- Meta, WhatsApp Business Platform, modelos de mensagem (aprovação, categorias e prazo de análise): https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/
- Meta, WhatsApp Business Platform, modelos de autenticação: https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/
- Meta, WhatsApp Cloud API, envio de mensagens (janela de atendimento de 24 horas): https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages/
- WebKit, "Web Push for Web Apps on iOS and iPadOS", 16 de fevereiro de 2023: https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/
- Apple, Human Interface Guidelines, Notifications: https://developer.apple.com/design/human-interface-guidelines/notifications
- Apple, App Store Review Guidelines, revisão de 8 de junho de 2026 (diretriz 4.5.4): https://developer.apple.com/app-store/review/guidelines/
- AWS End User Messaging SMS, limites de caracteres: https://docs.aws.amazon.com/sms-voice/latest/userguide/sms-limitations-character.html
- Google, diretrizes para remetentes de e-mail: https://support.google.com/a/answer/81126
Próximo passo#
Se o seu sistema vai avisar cliente, equipe ou fornecedor, o mapa de notificações entra junto com o escopo nos projetos de sistema sob medida, antes da primeira linha de código. Na Helpe, o canal foi decidido pelo público: muita gente ali nem usa e-mail no dia a dia, e por isso o login é por SMS.