Lembretes de evento

Eventos de calendário só continuam úteis quando as pessoas aparecem neles. Lembretes transformam o calendário em um empurrão — uma mensagem no WhatsApp um dia antes do retiro dos jovens, um e-mail na manhã da reunião dos líderes, um SMS uma hora antes do início da chamada de oração.

Lembretes não são configurados por evento. São configurados uma vez por organização, e cada evento com uma data futura e um canal correspondente passa pelo mesmo pipeline.

Como a configuração funciona

Existe exatamente uma linha event_reminder_config por org. Abra Configurações → Lembretes para editá-la.

event_reminder_config(
  id, organization_id, is_enabled,
  reminder_offsets_hours integer[],
  channel_slugs text[],
  title_template text,
  body_template text,
  created_at, updated_at
)

Dois arrays fazem o trabalho:

• reminder_offsets_hours — quando enviar. {24} é um único lembrete 24 horas antes do evento. {24, 1} são dois lembretes: um dia antes e uma hora antes. {168, 24, 1} são três lembretes: uma semana antes, um dia antes e uma hora antes.
• channel_slugs — como enviar. Escolha entre email, sms, whatsapp, push, in_app. O padrão é {push, in_app} que nunca custa créditos de mensagem.

Os dois arrays se multiplicam. Se reminder_offsets_hours = {24, 1} e channel_slugs = {email, whatsapp}, cada evento dispara quatro notificações: um e-mail e uma mensagem do WhatsApp 24 horas antes, depois de novo uma hora antes.

Semântica de enviar-X-horas-antes

Os offsets são horas absolutas, não "a manhã do" ou "o dia anterior". Um offset de 24 horas para um evento às 19h de domingo envia às 19h de sábado — não às 9h da manhã de domingo. Se você quer lembretes da manhã do dia, configure o offset aproximadamente para a diferença entre a manhã e a hora do evento (10–12 horas para um evento de domingo à noite).

Alguns padrões comuns:

Caso de uso	Offsets
Apenas nudge no dia anterior	{24}
Dia anterior + hora antes	{24, 1}
Semana antes + dia anterior para eventos grandes	{168, 24}
Chamada de oração na hora	{0.25} (15 min — mas apenas inteiros, então use 1)

WARNING

A coluna é integer[]. Offsets de menos de uma hora não são suportados. Arredonde para cima — um offset de 0 horas competiria com o próprio evento.

Canais

Cada slug de canal mapeia para o canal configurado nas suas configurações de Messaging. Para enviar lembretes pelo WhatsApp, você precisa de um canal WhatsApp ativo configurado em Messaging → Canais; para enviar SMS, um canal SMS; para enviar e-mail, um canal de e-mail.

Se um slug de canal está na configuração mas nenhum canal funcional existe para ele, o lembrete para esse slug falha silenciosamente. Os outros canais ainda saem. Fique de olho na tela Notificações → Logs se os lembretes ficarem quietos — canais com falha aparecem lá com o motivo da falha.

Os dois canais gratuitos valem destacar:

• push — notificações push de navegador e PWA. Membros que instalaram o app ou se inscreveram no navegador as recebem sem gastar créditos de mensagem.
• in_app — notificações do ícone de sino. Visíveis para quem fizer login.

A maioria das orgs roda {push, in_app, whatsapp} — push para alcance barato, WhatsApp para as pessoas que não instalaram o app.

Modelos de título e corpo

Dois campos de texto carregam o texto do lembrete:

• title_template — padrão é Upcoming: .
• body_template — padrão é on at .

Variáveis disponíveis em ambos os modelos:

• — o título do evento (ou o título de substituição de uma exceção).
• — formatada no fuso horário da org.
• — a hora de início, ou em branco se o evento não tiver.
• — prefixado com " at " quando presente, caso contrário em branco.

Mantenha os títulos curtos — SMS e push limitam os caracteres visíveis. O corpo pode ser mais longo para e-mail e WhatsApp.

Deduplicação

Eventos recorrentes se repetem. Sem deduplicação você enviaria o mesmo lembrete uma vez por ocorrência por offset por canal — rapidamente milhares de mensagens. A tabela event_reminders_sent evita isso:

event_reminders_sent(
  id, event_id, occurrence_date,
  organization_id, channel_slug, offset_hours,
  sent_at
)

O cron que despacha os lembretes verifica (event_id, occurrence_date, channel_slug, offset_hours) contra essa tabela antes de enviar. Se a linha existe, o lembrete é pulado. Se não existe, o lembrete sai e a linha é inserida na mesma transação.

A implicação: editar um evento recorrente não reenvia lembretes já enviados, e re-rodar o cron após uma falha não vai enviar em dobro os que já tinham sucesso.

Desligar lembretes

Configure is_enabled = false na linha de configuração e o cron pula sua org inteira. Útil quando você está semeando uma org de teste, migrando de outra plataforma ou testando a criação de eventos sem fazer spam para seus membros.

Você também pode desligar lembretes por canal removendo o slug de channel_slugs. Remover whatsapp no meio da semana significa que a próxima passada de lembretes pula o WhatsApp para todo mundo, mesmo para eventos já agendados.

O que recebe lembrete

Cada evento não-excluído com uma ocorrência futura dentro do próximo offset agendado recebe um lembrete. Isso inclui:

• Eventos únicos cuja event_date está no futuro.
• Cada ocorrência futura de um evento recorrente, expandida da RRULE.
• Eventos que caem em uma data com substituição — o lembrete usa o título, a hora e o local da substituição.
• Eventos que a exceção não cancelou. Ocorrências canceladas são puladas.

Aniversários atualmente não passam por event_reminder_config — eles têm um gatilho de workflow separado no módulo messaging.