Notificaciones¶
Hardhat Flow envía notificaciones SMS para eventos críticos de campo (vía Twilio) y notificaciones por correo para hitos del flujo de trabajo (vía Mailgun). Toda entrega es asíncrona — las notificaciones se despachan mediante workers Celery y nunca bloquean la solicitud de la aplicación.
Desarrolladores que agreguen un nuevo aviso por correo o SMS: ver Adding Email and SMS Notifications (guía en inglés).
Notificaciones por correo (eventos de flujo)¶
Los Owners configuran el correo en Settings bajo Email Notifications. Por cada evento se puede activar o desactivar y elegir qué roles reciben el correo. Todos los roles del inquilino están disponibles, incluidos Owners.
| Evento | Cuándo se dispara |
|---|---|
| Bid enviado para aprobación | Un bid pasa de New Bid a Awaiting PO |
| Bid aprobado — job creado | Se aprueba un bid y se crea automáticamente un job |
| Factura creada | Un job completado se convierte en factura |
| Pago registrado | Se registra cualquier pago en una factura |
| Factura pagada en su totalidad | El saldo de la factura llega a cero |
| Flujo completado | Una factura pagada se cierra a Workflow Complete |
Valores por defecto¶
Al provisionar un inquilino, los seis eventos quedan habilitados con listas de roles razonables (Owners, Accounting, Project Managers y Supervisors según el evento). Los Owners pueden restringir o ampliar destinatarios en cualquier momento.
Requisitos¶
- Los destinatarios deben tener correo en su perfil de usuario.
- Quien dispara el evento no recibe el correo (evita ruido duplicado).
- El correo es de mejor esfuerzo — si Mailgun no está configurado o se alcanza el tope diario, la acción en la app igual se completa.
Invitaciones de usuario¶
Cuando un Owner agrega un miembro del equipo (o se provisiona un Owner de un inquilino nuevo), Hardhat Flow envía un correo de bienvenida con:
- Quién lo invitó y a qué empresa se une
- Un enlace seguro para definir la contraseña (ticket de Auth0 de un solo uso)
- Dónde iniciar sesión después de configurarla
Esto reemplaza el correo genérico de restablecimiento de Auth0 para que el primer contacto sea de marca e informativo.
El correo complementa el SMS.
Las alertas SMS (abajo) cubren eventos urgentes de campo, como jobs bloqueados. El correo cubre el flujo de bid a pago para que el personal de oficina se mantenga informado sin revisar la app constantemente.
Platform Admin: alertas de solicitud de acceso¶
Cuando alguien envía el formulario público Request Access, los platform admins reciben una alerta por correo además del correo de confirmación al solicitante. Las alertas van a todas las cuentas activas de Platform Admin. La variable de entorno opcional PLATFORM_ADMIN_NOTIFY_EMAILS puede agregar direcciones extra.
Preferencias de texto (próximamente)¶
La página Settings incluye una sección Text Notifications con casillas deshabilitadas para futuros controles de preferencia SMS. Las alertas SMS siguen disparándose hoy con las reglas de destinatarios de la tabla siguiente. Cuando las preferencias de texto estén habilitadas, los owners podrán elegir qué eventos envían SMS y qué roles los reciben.
Eventos que disparan SMS¶
Seis eventos disparan notificaciones SMS automáticas:
| Evento | Quién es notificado |
|---|---|
| Job bloqueado | PM + Owner |
| Job desbloqueado | PM |
| Bid rechazado | PM + Owner |
| Bid cancelado | PM + Supervisor |
| Job cancelado | PM + Supervisor |
| Bandera Priority activada (bid o job) | PM + Supervisor |
Detalle de eventos¶
Job Blocked
Cuando blocked pasa a true en un job, el PM asignado y todos los usuarios con rol Owner reciben SMS. El mensaje incluye la ubicación del job y pide iniciar sesión para ver detalles.
Job Unblocked
Cuando se quita blocked en un job, el PM recibe SMS confirmando que el bloqueo se resolvió.
Bid Rejected
Cuando un Owner pone un bid en Bid Rejected, se notifica al PM asignado y a todos los usuarios con rol Owner del inquilino.
Bid Cancelled Cuando un Owner cancela un bid, se notifica al PM y al Supervisor asignados.
Job Cancelled Cuando un Owner cancela un job, se notifica al PM y al Supervisor asignados.
Priority Flag Set
Cuando priority pasa a true en un bid o un job, el PM y el Supervisor asignados reciben SMS de urgencia.
Las notificaciones de prioridad se envían cuando la bandera se activa (de false a true). Al quitar la bandera no se envía notificación.
Requisito de número telefónico¶
Las notificaciones SMS requieren un número en el registro del usuario (User.phone).
- El teléfono es obligatorio para quien deba recibir SMS.
- Se recomienda encarecidamente registrar teléfonos para todas las cuentas de Owner, PM y Supervisor.
- Badge Workers y usuarios de Accounting no son destinatarios de SMS.
Si no hay teléfono registrado¶
Si se dispara una notificación para un usuario sin número:
- El SMS se omite en silencio para ese usuario.
- Se registra una advertencia vía structlog con ID de usuario, tipo de evento e ID de entidad.
- Los demás destinatarios (si los hay) reciben sus notificaciones con normalidad.
No hay notificación en la aplicación ni error visible al usuario que disparó el evento si un SMS no puede enviarse por falta de teléfono. Revise los registros si sospecha que faltan SMS.
Número saliente por inquilino¶
Cada inquilino tiene su propio número Twilio saliente. El número se guarda en CompanySettings.twilio_phone_number.
- Todo SMS enviado desde un inquilino sale del número configurado de esa empresa.
- Los destinatarios ven un número reconocible y consistente por compañía.
- El número lo configura el Owner o Platform Admin en CompanySettings.
Un número por inquilino ayuda a que clientes y personal reconozcan y distingan los SMS por empresa.
Entrega asíncrona vía Celery¶
Todas las notificaciones SMS y por correo se entregan de forma asíncrona:
- Ocurre el evento en la aplicación (ej. job bloqueado, bid enviado).
- Se encola una tarea Celery de inmediato.
- Un worker Celery ejecuta la tarea y llama a Twilio (SMS) o Mailgun (correo).
- La respuesta de la API (éxito o fallo) queda registrada.
La solicitud HTTP que disparó el evento no espera la entrega. Si Celery está caído o el proveedor devuelve error, la acción en la aplicación igual se completa. Los fallos de entrega solo aparecen en registros.
La entrega es de mejor esfuerzo. Si los workers Celery no están en ejecución, las notificaciones quedan en cola hasta que los workers vuelvan.
Formato del mensaje SMS¶
Todos los SMS siguen este formato:
[Hardhat Flow] <Entity>: <identifier> — <what happened>.
| Evento | Ejemplo de mensaje |
|---|---|
| Job bloqueado | [Hardhat Flow] Job: 123 Main St — marked BLOCKED. Log in to view details. |
| Job desbloqueado | [Hardhat Flow] Job: 123 Main St — unblocked. |
| Bid rechazado | [Hardhat Flow] Bid: Acme Corp / 123 Main St — rejected. |
| Bid cancelado | [Hardhat Flow] Bid: Acme Corp / 123 Main St — cancelled. |
| Job cancelado | [Hardhat Flow] Job: 123 Main St — cancelled. |
| Prioridad (bid) | [Hardhat Flow] Bid: Acme Corp / 123 Main St — marked HIGH PRIORITY. |
| Prioridad (job) | [Hardhat Flow] Job: 123 Main St — marked HIGH PRIORITY. |
El identificador de entidad para jobs es la ubicación del bid asociado. Para bids, es el nombre del cliente seguido de la ubicación del bid.