Skip to main content

Documentation Index

Fetch the complete documentation index at: https://woku.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

Disponible en el plan Corporate. Esta funcionalidad forma parte de las capacidades empresariales de woku. Conversa con nuestro equipo comercial.
Una regla de alerta es una pieza de configuración que escucha un evento (una respuesta recién creada) o se ejecuta periódicamente, y cuando sus condiciones se cumplen dispara una lista ordenada de acciones. Cada regla puede definir además escalamientos: una o más sub-listas de acciones que se ejecutan después de un retraso si el ciclo no se cerró antes. Usos típicos:
  • NPS bajo asigna a supervisor: cuando una respuesta de NPS marca menor a 7, asigna al supervisor de la sucursal y le manda un WhatsApp.
  • Texto con queja crítica: si la respuesta menciona la palabra “denuncia” o “abogado”, manda un email al equipo legal y abre un webhook a Salesforce.
  • SLA vulnerado: si una respuesta lleva más de 60 minutos sin ser atendida, escala a la jefatura y cambia el estado a urgent.

​
Anatomía de una regla

CampoTipoDescripción
namestringNombre visible.
descriptionstring opcionalPara qué sirve.
trigger{ type: 'event' | 'cron', events?, cronExpression? }Cómo se activa.
conditions{ all: [...] } o { any: [...] }Grupo top-level de condiciones (compatible con json-rules-engine).
actionsarrayAcciones inmediatas al matchear (orden importa).
escalationsarraySub-listas con afterMin para acciones diferidas.
enabledbooleanoSi está activa.
prioritynúmeroPrioridad de evaluación (menor = primero).
metrics{ totalFired, totalEscalated, lastFiredAt }Contadores en vivo.

​
Triggers

  • event, la regla se evalúa en cada form-response.created. La evaluación corre en un listener, no en el path del HTTP, así que no agrega latencia al endpoint que crea la respuesta.
  • cron, la regla se evalúa cada 5 minutos (V1) sobre las respuestas no cerradas en las últimas 72 horas. Aquí caen las reglas tipo SLA o detección de volumen bajo.

​
Condiciones

conditions es exactamente lo que consume json-rules-engine. La forma mínima es: 
{
  "all": [
    { "fact": "score", "operator": "lessThan", "value": 7 }
  ]
}
Operadores soportados out-of-the-box: equal, notEqual, lessThan, lessThanInclusive, greaterThan, greaterThanInclusive, in, notIn, contains, doesNotContain. Operadores custom Woku:
  • stringContains, factValue.toLowerCase().includes(jsonValue.toLowerCase()).
all representa AND, any representa OR. Para V1 el builder visual soporta árboles de un solo nivel; la API acepta árboles anidados a cualquier profundidad, un JSON guardado a mano funciona.

​
Facts disponibles

El evaluador construye un fact bag por respuesta:
FactOrigen
scorePrimer valor numérico en answers. Apunta al NPS por convención.
textConcatConcatenación lowercased de todos los strings en answers. Útil para stringContains.
formResponseId, formId, companyIdIds del contexto.
createdAtISO timestamp.
sla_elapsedSolo en cron: minutos transcurridos desde createdAt.
cualquier key de answersCada campo del formulario es un fact independiente.

​
Acciones

TipoParámetrosEfecto
assign_useruserIdFormResponse.assignedTo = userId.
change_statusstatusFormResponse.status = status. Si el status nuevo cae en {closed, resolved, dismissed}, dispara cancelación de escalamientos pendientes.
send_webhookurl, headers?POST con { alertRuleId, alertRuleExecutionId, companyId, formResponseId, formId, facts, firedAt, isEscalation }. Timeout 10 s, retry 3x exponencial.
send_emailto, subject?V1 logged-only; el módulo de mail engancha esta rama en un follow-up.
send_whatsappto, template?, params?V1 logged-only; mismo plan que send_email.
Las acciones se encolan en BullMQ (alertActionsQueue, concurrencia 10) y se ejecutan independientemente. El orden de la lista se preserva en la cola.

​
Escalamientos

Cada entrada de escalations define un retraso y una sub-lista de acciones: 
{
  "afterMin": 60,
  "actions": [
    { "type": "send_email", "to": "ops@example.com" },
    { "type": "send_whatsapp", "to": "+56912345678", "template": "alert_nps" }
  ],
  "cancelIfClosed": true
}
Cuando la regla matchea, cada acción de cada escalamiento se encola con delay = afterMin * 60_000. Si después la respuesta entra en un status terminal (closed/resolved/dismissed), los jobs pendientes se cancelan y la ejecución se marca como cerrada. Además, los jobs de escalamiento chequean execution.closedAt antes de ejecutarse: si el cierre fue muy reciente, el job se vuelve no-op incluso si el removeJob no llegó a tiempo. Esto cubre la ventana de carrera entre el cambio de estado y la cancelación.

​
Builder

El menú Reglas de alerta lleva al listado por empresa. Desde ahí se puede crear, editar, eliminar o probar una regla. El builder tiene cinco pestañas:
  1. General: nombre, descripción, tipo de trigger, prioridad, habilitada.
  2. Condiciones: lista de condiciones leaf con operador raíz AND/OR. Cada fila pide fact, operator, value. La serialización convierte "7" a 7, "true" a true, valores con coma a arrays para in/notIn.
  3. Acciones: lista drag-to-reorder con @dnd-kit. El tipo de acción determina los campos que pide.
  4. Escalamientos: lista de { afterMin, actions, cancelIfClosed }, con la misma UI de acciones anidada.
  5. Vista previa: render del JSON exacto que se envía al servidor.

​
Simulador

El botón Probar en cada fila del listado abre un modal que ejecuta una simulación (dry-run). Pide un JSON con answers y opcionalmente extraFacts, y devuelve:
  • matched: si la regla habría coincidido.
  • actionsWouldFire: la lista de acciones que se dispararían.
  • facts: el fact bag exacto que vio el motor.
No dispara nada: no encola jobs, no muta FormResponse, no envía emails ni webhooks. Es la herramienta para validar una regla antes de exponerla a producción.

​
Garantías

  • Aislamiento entre reglas: cada regla se evalúa en su propio try/catch. Una regla con un operador inexistente o condiciones malformadas no impide que las demás se evalúen.
  • Backpressure: las acciones corren en una cola dedicada con concurrencia 10. Una racha de respuestas no bloquea el path síncrono.
  • Idempotencia: cada fire crea un AlertRuleExecution con actionJobIds + escalationJobIds. Los jobs de escalamiento vuelven a chequear closedAt antes de ejecutarse.
  • Dedup en cron: el evaluador cron-based no dispara dos veces la misma regla contra la misma respuesta dentro de una ventana de 24 horas (la ejecución previa es el token).
  • Auditable: cada CRUD de regla queda registrado en el audit log como alert-rule.create/update/delete.

​
Limitaciones conocidas (V1)

  • send_email y send_whatsapp son stubs que loguean la intención. El módulo de mail y el de WhatsApp engancharán esas ramas en una iteración siguiente sin cambiar el contrato del dispatcher.
  • Sin builder de árboles anidados: el editor visual cubre un nivel all o any. Para reglas con anidamiento de all dentro de any (o viceversa) hay que editar el JSON directamente vía API.
  • Sin agente IA como acción: el plan original menciona acciones de LangChain, quedan para una iteración futura.
  • Statuses terminales hard-coded: V1 considera {closed, resolved, dismissed} como terminales. Una iteración siguiente permitirá overrides por empresa.
  • El cron corre cada 5 minutos. Para reglas de SLA con SLAs muy cortos (< 5 min) la latencia perceptible es esa frecuencia.