Notificaciones y Comunicaciones

Tabla de Contenidos

1. Arquitectura General
2. Arquitectura de Modulos
3. Email (SMTP)
4. WhatsApp (Twilio)
5. Push Notifications (Expo)
6. Colas con Bull
7. Campanas Masivas
   • 7.1 Templates de Comunicacion
   • 7.2 Preview y Estimacion
   • 7.3 Prevencion de Spam
   • 7.4 Chatbot WhatsApp (RSVP)
   • 7.5 Smart Routing
8. Webhooks de Estado
9. Flujo de Campana
10. Workflows y Automatizacion
11. Proveedores por Ambiente

Arquitectura General

El sistema de notificaciones y comunicaciones de Nvito sigue una arquitectura basada en colas para garantizar entrega confiable, reintentos automaticos y procesamiento asincrono de mensajes masivos.

Componentes Principales

Arquitectura de Modulos

El sistema de notificaciones esta organizado en 3 modulos con dependencias bien definidas para evitar dependencias circulares:

Patron clave: NotificationChannelsModule es el modulo base que ambos (QueueModule y NotificationsModule) importan. Esto elimina la dependencia circular que existiria si NotificationsModule y QueueModule se importaran mutuamente. No hay forwardRef en el proyecto.

Email (SMTP)

Configuracion

El servicio de email usa nodemailer para enviar correos via SMTP. La configuracion es flexible para soportar multiples proveedores:

// Configuracion del transporter
const transportOptions = {
  host: config.email.smtp.host,     // Servidor SMTP
  port: config.email.smtp.port,     // Puerto (1025 dev, 587 prod)
  secure: false,                     // TLS se negocia via STARTTLS
  auth: user ? { user, pass } : undefined,  // Auth condicional
};

Auth Condicional

• MailDev (local): No requiere autenticacion (user no configurado)
• Mailtrap (dev/test): Requiere usuario y contrasena
• Produccion: Requiere credenciales SMTP del proveedor final

Opciones de Envio

interface SendEmailOptions {
  to: string | string[];     // Destinatario(s)
  subject: string;           // Asunto
  text?: string;             // Cuerpo en texto plano
  html?: string;             // Cuerpo en HTML
  from?: string;             // Remitente (default: Nvito <noreply@nvito.mx>)
  replyTo?: string;          // Reply-to (default: hola@nvito.mx)
  tags?: { name: string; value: string }[];  // Tags para tracking
}

Envio por Lotes

El EmailService soporta envio en lotes con sendBatchEmails(), que procesa multiples emails en paralelo usando Promise.allSettled() para que un fallo individual no afecte al resto.

Verificacion de Configuracion

El metodo verifyConfiguration() prueba la conexion SMTP sin enviar correos, util para health checks del sistema.

WhatsApp (Twilio)

Configuracion

El servicio de WhatsApp usa el SDK de Twilio para enviar mensajes a traves de WhatsApp Business API:

// Variables de entorno
TWILIO_ACCOUNT_SID=ACxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxx
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886  // Numero sandbox o produccion

Tipos de Mensaje

Mensajes con Template

Los mensajes con template pre-aprobado por WhatsApp/Meta se envian usando contentSid (ID del template en Twilio) y variables dinamicas:

interface SendWhatsAppTemplateOptions {
  to: string;                                    // Numero destino
  contentSid: string;                            // ID del template Twilio
  contentVariables?: Record<string, string>;     // Variables del template
}

Formato de Numeros

El servicio formatea automaticamente los numeros de telefono:

• Si ya tiene formato whatsapp:+XX...: lo usa directamente
• Si tiene prefijo +: agrega whatsapp: al inicio
• Si empieza con 52: agrega whatsapp:+
• Otro caso: asume codigo de Mexico (whatsapp:+52...)

Degradacion Elegante

Si las credenciales de Twilio no estan configuradas, el servicio no lanza error sino que retorna { sid: 'mock-sid', success: false } y registra un warning en logs. Esto permite que el sistema funcione en ambientes de desarrollo sin Twilio.

Push Notifications (Expo)

Arquitectura

Las push notifications se envian a dispositivos moviles (iOS/Android) a traves de la Expo Push API. El flujo es:

1. La app movil registra su Expo Push Token via POST /mobile/auth/register-push
2. El token se almacena en la tabla MobileSession
3. Cuando ocurre un evento relevante (nuevo RSVP, check-in, etc.), el PushNotificationService encola un job de push
4. El PushProcessor procesa el job y envia la notificacion via PushSenderService

PushSenderService

El servicio de envio puro que usa la Expo Push API:

interface PushPayload {
  to: string;          // Expo Push Token
  title: string;       // Titulo de la notificacion
  body: string;        // Cuerpo del mensaje
  data?: Record<string, unknown>;  // Datos extras para la app
}

PushNotificationService

Servicio de dominio que orquesta el envio de push notifications a los hosts de un evento:

• notifyEventHosts(eventId, title, body, data) — Busca todas las sesiones activas con role=HOST del evento y encola un push para cada una
• registerToken(sessionId, pushToken) — Registra o actualiza el push token de una sesion movil

Degradacion Elegante

Si no hay sesiones activas con push token para el evento, el servicio simplemente no envia nada (sin error). Esto permite que el sistema funcione sin la app movil instalada.

Colas con Bull

Arquitectura de Colas

El sistema usa Bull (basado en Redis) para procesar mensajes de forma asincrona:

Configuracion de Redis

// queue.config.ts
redis: {
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD || undefined,
  db: parseInt(process.env.REDIS_DB || '0'),
}

Opciones por Defecto de Jobs

defaultJobOptions: {
  attempts: 3,              // 3 intentos antes de marcar como fallido
  backoff: {
    type: 'exponential',    // Backoff exponencial entre reintentos
    delay: 5000,            // Delay base de 5 segundos
  },
  removeOnComplete: true,   // Limpiar jobs completados
  removeOnFail: false,      // Mantener jobs fallidos para analisis
}

Reintentos con Backoff Exponencial

Tipos de Jobs

Email:

• send-email: Envio de un email individual
• send-batch-email: Envio de un lote de emails

WhatsApp:

• send-whatsapp: Envio de un mensaje WhatsApp (freeform o template)

Push:

• send-push: Envio de una push notification a dispositivo movil via Expo

Operaciones de Gestion

El QueueService expone operaciones administrativas:

Campanas Masivas

Modelo de Datos

El sistema de comunicaciones masivas usa tres entidades principales:

• CommunicationCampaign: Representa una campana de envio (ej: "Envio de invitacion - Boda Ana"). Incluye tipo, canal, metricas acumuladas, filtros de destinatarios y referencia opcional a workflow.
• CommunicationMessage: Cada mensaje individual dentro de la campana, con tracking de estado, timestamps y error.
• CommunicationTemplate: Plantillas reutilizables de mensajes por tipo de campana y categoria de evento.

Arquitectura SRP (Sub-servicios)

El modulo de comunicaciones sigue el patron de sub-servicios con responsabilidad unica:

Tipos de Campana

El sistema soporta 5 tipos de envio masivo:

Canales de Comunicacion

Filtrado de Destinatarios

El RecipientFilterService soporta multiples criterios combinables:

Estados de Mensaje

Metricas de Campana

Cada campana mantiene metricas acumuladas que se recalculan en cada webhook de estado:

Estados de Campana

Templates de Comunicacion

El sistema de templates permite crear plantillas reutilizables para cada tipo de campana:

Modelo CommunicationTemplate:

Variables disponibles (12):

Endpoints:

Preview y Estimacion

Antes de enviar una campana, el sistema permite previsualizar el mensaje y estimar el numero de destinatarios:

Preview de mensajes (POST /communications/preview-message):

• Genera el HTML o texto final del mensaje con todas las variables interpoladas
• Soporta preview por canal (EMAIL muestra HTML renderizado, WHATSAPP muestra texto plano)
• Permite seleccionar un invitado especifico para ver su preview personalizado
• Util para verificar que el template se ve correctamente antes del envio masivo

Estimacion de destinatarios (POST /communications/estimate-recipients):

• Cuenta invitados que coinciden con los filtros seleccionados
• Retorna desglose por canal: { total, byChannel: { email, whatsapp, both } }
• Usa queries de conteo (sin desencriptar datos) para rendimiento optimo
• El frontend muestra el conteo en tiempo real conforme el usuario ajusta filtros

Prevencion de Spam

El SpamPreventionService protege contra envios duplicados accidentales:

Deteccion de duplicados (POST /communications/check-duplicate):

• Busca campanas del mismo tipo y canal enviadas en las ultimas 24 horas
• Retorna: isDuplicate (boolean), lastCampaign (id, nombre, fecha, destinatarios), hoursSince (horas desde la ultima)
• El frontend muestra un warning al usuario antes de confirmar el envio si detecta duplicado

Historial por invitado (GET /communications/guests/:guestId/communications):

• Muestra todos los mensajes recibidos por un invitado especifico
• Incluye informacion de la campana asociada (nombre, tipo, canal)
• Permite al organizador ver el historial completo de comunicaciones de cada invitado

Chatbot WhatsApp (RSVP)

El chatbot de WhatsApp permite a los invitados confirmar o declinar su asistencia de forma conversacional:

Componentes:

• ChatbotService: Maquina de estados de conversacion almacenada en Redis con TTL. Gestiona el flujo: saludo inicial → espera respuesta → procesa intent → confirma/declina → cierra conversacion.
• NluService: Procesamiento de lenguaje natural basico para detectar intents en las respuestas del invitado. Clasifica en: CONFIRM (si, confirmo, asisto, etc.), DECLINE (no, no puedo, declino, etc.), UNKNOWN (respuesta no entendida → re-pregunta).
• Mensajes predefinidos: Templates en chatbot-messages.ts para cada etapa del flujo (saludo, confirmacion, rechazo, no entendido).

Webhook entrante: POST /communications/webhooks/twilio/incoming recibe las respuestas de los invitados y las procesa a traves del ChatbotService.

Smart Routing

El SmartRoutingService resuelve automaticamente el canal optimo para cada invitado basandose en sus datos de contacto disponibles:

Cuando el canal solicitado es BOTH, el servicio envia por ambos canales (Email + WhatsApp) al mismo invitado, creando dos CommunicationMessage separados.

Webhooks de Estado

Twilio Status Webhooks

Twilio envia actualizaciones de estado a POST /communications/webhooks/twilio cada vez que un mensaje de WhatsApp cambia de estado.

Estados de Twilio

Procesamiento del Webhook

1. Twilio envia POST con MessageSid, MessageStatus, ErrorCode, ErrorMessage
2. El controller busca el CommunicationMessage por providerId (MessageSid)
3. Actualiza el estado del mensaje y timestamps correspondientes
4. Recalcula las metricas de la campana asociada con updateCampaignMetrics()
5. Siempre retorna { received: true } (incluso en error) para que Twilio no reintente

Seguridad del Webhook

• El endpoint esta decorado con @Public() (no requiere autenticacion JWT)
• Esta marcado con @ApiExcludeEndpoint() (no aparece en Swagger)
• En produccion se debe validar la firma de Twilio para verificar autenticidad

Flujo de Campana

El siguiente diagrama muestra el flujo completo de una campana de comunicacion desde el admin hasta la entrega:

Workflows y Automatizacion

Los workflows permiten automatizar el envio de comunicaciones basado en eventos del sistema. Cada workflow define un trigger, un tipo de campana y los parametros del mensaje.

Modelo CommunicationWorkflow

Triggers Disponibles

Endpoints

Comportamiento

• Cada vez que un workflow se ejecuta, crea una nueva CommunicationCampaign con el workflowId vinculado
• El contador executionCount se incrementa automaticamente
• Los workflows pausados no se ejecutan aunque ocurra el trigger
• Los workflows se evaluan en el contexto del evento al que pertenecen

Proveedores por Ambiente

Tabla de Proveedores

MailDev (Desarrollo Local)

MailDev es un servidor SMTP local que captura todos los emails enviados y los muestra en una interfaz web:

• SMTP: localhost:1025 (sin autenticacion)
• Web UI: localhost:1080 (visualizacion de emails)
• Ventaja: No se envian emails reales durante desarrollo

Mailtrap (DEV/TEST)

Mailtrap es un servicio de testing de email que captura correos en un inbox virtual:

• SMTP: Host y puerto proporcionados por Mailtrap
• Auth: Requiere usuario y contrasena
• Ventaja: Permite probar templates HTML sin enviar a destinatarios reales

Twilio Sandbox (DEV/TEST)

El sandbox de Twilio permite probar WhatsApp sin un numero de produccion:

• Numero sandbox: whatsapp:+14155238886 (default)
• Limitacion: Solo funciona con numeros registrados en el sandbox
• Templates: Se usan los templates de prueba de Twilio

Variables de Entorno

Email

WhatsApp

Redis / Colas

Referencias

Modulo de Notificaciones (canales puros)

• EmailService: src/modules/notifications/email.service.ts
• WhatsAppService: src/modules/notifications/whatsapp.service.ts
• TemplateService: src/modules/notifications/template.service.ts
• PushSenderService: src/modules/notifications/push-sender.service.ts
• PushNotificationService: src/modules/notifications/push-notification.service.ts
• NotificationHelperService: src/modules/notifications/notification-helper.service.ts
• NotificationChannelsModule: src/modules/notifications/notification-channels.module.ts
• NotificationsModule: src/modules/notifications/notifications.module.ts

Modulo de Colas

• QueueService: src/modules/queue/queue.service.ts
• EmailProcessor: src/modules/queue/processors/email.processor.ts
• WhatsAppProcessor: src/modules/queue/processors/whatsapp.processor.ts
• PushProcessor: src/modules/queue/processors/push.processor.ts
• QueueModule: src/modules/queue/queue.module.ts

Modulo de Comunicaciones (campanas masivas)

• CommunicationsService: src/modules/communications/communications.service.ts
• CommunicationsController: src/modules/communications/communications.controller.ts
• WebhookController: src/modules/communications/communications-webhook.controller.ts
• TemplatesController: src/modules/communications/controllers/communication-templates.controller.ts
• MessageDispatcherService: src/modules/communications/services/message-dispatcher.service.ts
• InvitationDispatcherService: src/modules/communications/services/invitation-dispatcher.service.ts
• ReminderMessageDispatcherService: src/modules/communications/services/reminder-message-dispatcher.service.ts
• CampaignQueryService: src/modules/communications/services/campaign-query.service.ts
• RecipientFilterService: src/modules/communications/services/recipient-filter.service.ts
• RecipientEstimatorService: src/modules/communications/services/recipient-estimator.service.ts
• SpamPreventionService: src/modules/communications/services/spam-prevention.service.ts
• SmartRoutingService: src/modules/communications/services/smart-routing.service.ts
• MessagePreviewService: src/modules/communications/services/message-preview.service.ts
• CommunicationTemplateService: src/modules/communications/services/communication-template.service.ts
• ChatbotService: src/modules/communications/chatbot/chatbot.service.ts
• NluService: src/modules/communications/chatbot/nlu.service.ts

Configuracion

• Queue Config: src/config/queue.config.ts
• WhatsApp Config: src/config/whatsapp.config.ts