Saltar a contenido

Notificaciones

Hardhat Flow envía notificaciones SMS para eventos críticos usando Twilio. Toda entrega SMS es asíncrona — las notificaciones se despachan mediante workers Celery y nunca bloquean la solicitud de la aplicación.

Eventos que disparan SMS

Seis eventos disparan notificaciones SMS automáticas:

Event Who is Notified
Job bloqueado PM + Owner
Job desbloqueado PM
Bid rechazado PM + Owner
Bid cancelado PM + Supervisor
Job cancelado PM + Supervisor
Bander Priority activada (Bid o Job) PM + Supervisor

Detalle de eventos

Job Blocked Cuando blocked pasa a true en un Job, el PM asignado y el Owner reciben SMS. El mensaje incluye el ID del Job y blocked_reason.

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 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:

  1. El SMS se omite en silencio para ese usuario.
  2. Se registra una advertencia vía structlog con ID de usuario, tipo de evento e ID de entidad.
  3. 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 se entregan de forma asíncrona:

  1. Ocurre el evento en la aplicación (ej. Job bloqueado).
  2. Se encola una tarea Celery de inmediato.
  3. Un worker Celery ejecuta la tarea y llama a la API de Twilio.
  4. La respuesta de la API (éxito o fallo) queda registrada.

La solicitud HTTP que disparó el evento no espera la entrega del SMS. Si Celery está caído o Twilio devuelve error, la acción en la aplicación igual se completa. Los fallos de SMS solo aparecen en registros.

La entrega SMS es el mejor esfuerzo posible. Si los workers Celery no están en ejecución, las notificaciones quedan en cola hasta que los workers vuelvan.

Formato del mensaje

Todos los SMS siguen este formato:

[Hardhat Flow] <Entity>: <identifier> — <what happened>.

Event Example Message
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.