Automatizaciones

Las automatizaciones ejecutan una instrucción según un horario y entregan el resultado como chat normal. Un resumen diario, una revisión semanal o un informe mensual: cada ejecución ocurre sin interfaz en el servidor, aparece en tu lista y puede abrirse y continuarse como cualquier conversación.

Anatomía

Una automatización tiene nombre, instrucciones libres, hasta cinco desencadenadores, un modelo opcional (vacío significa Auto: tu modelo predeterminado en ese momento), un destino y una preferencia de notificación. Sesión de chat es el destino predeterminado; Tarea de Work inicia un sandbox Work aislado, opcionalmente bajo una política elegida. Con notificaciones, los fallos llegan también a la bandeja. Por separado, activar Resultados de automatizaciones en Configuración → Notificaciones → Notificaciones por correo te envía por correo el resultado de cada ejecución en cuanto un administrador haya configurado un servidor de correo saliente (consulta Notificaciones). Nombres e instrucciones se cifran en reposo y pertenecen a su creador.

Los desencadenadores reutilizan once, hourly, daily, weekly, monthly y yearly. La siguiente ejecución es siempre la ocurrencia futura más cercana, calculada en la zona horaria local del servidor.

Disparadores por evento

Un séptimo tipo, event, no tiene reloj alguno: se dispara cuando llega una de tus notificaciones.

{ "kind": "event", "event": "channel-mention", "match": "release" }

event puede ser cualquier tipo de notificación salvo automation-failed: una rutina no puede reiniciarse a sí misma a partir de su propio aviso de fallo. El match opcional es una comprobación de subcadena sin distinguir mayúsculas contra el título de la notificación; sin él, se dispara con cualquier notificación de ese tipo.

Un disparador por evento nunca aporta una hora de próxima ejecución. Una automatización cuyos desencadenadores son todos eventos no muestra próxima ejecución: la lista y el diálogo de edición dicen Se ejecuta cuando… en su lugar. Combinar un disparador por evento con un horario es válido: los desencadenadores programados siguen marcando el reloj.

Dos límites acotan el alcance. Una rutina se dispara como máximo una vez por minuto a partir de eventos, sin importar lo activo que esté el flujo, y la notificación de fallo de una ejecución nunca vuelve a disparar la rutina que la produjo.

La ejecución recibe lo que la disparó, añadido a sus instrucciones:

---
Trigger payload (JSON):
{"event":"channel-mention","title":"...","body":"...","href":"..."}

Ejecución

El planificador actúa cada minuto tras un lease de coordinación, por lo que solo una réplica avanza horarios. Cuando vence una automatización, registra una ejecución, encola automation.run.v1 y avanza next_run_at mediante compare-and-set para que cada ocurrencia se dispare como máximo una vez. El trabajo crea un chat con el nombre de la automatización y encola la instrucción mediante la misma canalización duradera, con enrutamiento, personas y persistencia.

Si el servidor estaba apagado, el siguiente tick ejecuta una vez la ocurrencia y omite las anteriores. Pausar borra el horario; reanudar o editar lo recalcula. Eliminar borra el historial mediante cascada de clave externa.

Las ejecuciones se resuelven desde el registro duradero: éxito al terminar la generación, fallo al llegar a dead-letter, y stalled si no comienzan en 30 minutos.

Los destinos Work usan su ciclo de vida, guardan la tarea creada y terminan correctamente si el agente completa o pide entrada. Un correo de resultado para una ejecución dirigida a Work lleva el resumen que la propia ejecución de Work guardó —el mismo texto que muestra el historial de ejecuciones de la tarea— y recurre al estado de una línea de la tarea cuando una ejecución es anterior a los resúmenes persistidos. El acceso se comprueba al dispararse: si se revoca, falla como work-access-denied. La política seleccionada se valida al guardar y aplica sus límites. Solo funcionan proveedores directos y modelos capaces de usar herramientas.

Rutinas de agentes

Una automatización dirigida a Work también puede vincularse a una tarea de Work existente mediante workTaskId; es la estructura que utiliza la sección Rutinas del panel de detalles de un agente. Una rutina vinculada no crea una tarea nueva en cada activación: cada ocurrencia inicia una ejecución dentro del espacio y la conversación propios de esa tarea, utilizando su modelo, proveedor y política de entorno. Por tanto, los campos de modelo y política de la automatización no se aplican, y cualquier política proporcionada se descarta al guardar. La vinculación se valida al guardar la automatización (la tarea debe existir y pertenecer al llamante). En el momento de la activación, una tarea eliminada hace fallar la ejecución como work-task-missing; una tarea que ya se está ejecutando —o mantiene una vista previa activa— hace fallar honestamente la ocurrencia como work-task-busy, en vez de ponerla en cola.

Disparadores por webhook

Además del horario, un sistema externo puede disparar una automatización: una canalización de CI, un servicio cron, la domótica de casa. En el diálogo de edición de la automatización, Disparador de webhook → Habilitar genera un secreto propio de esa automatización; solo se guarda su SHA-256, así que el texto en claro se muestra exactamente una vez. Rotar el secreto invalida el anterior de inmediato, y desactivar el webhook vuelve a cerrar el endpoint.

El sistema externo dispara la automatización así:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(X-Libre-Webhook-Secret: lwh_... funciona como cabecera alternativa). La respuesta es 202 con el ID de la ejecución encolada: es la misma ruta de ejecución manual que Ejecutar ahora, de modo que las ejecuciones se resuelven, notifican y aparecen en el historial de forma idéntica. La comparación del secreto es de tiempo constante, una automatización inexistente y un secreto incorrecto responden igual (sin oráculo de identificadores de automatización), y una automatización pausada responde 409: a diferencia del propietario con Ejecutar ahora, quien llama desde fuera no puede disparar a través de una pausa.

Un objeto JSON en el cuerpo de la petición viaja hasta la ejecución como su payload de disparo, de modo que la rutina puede ver a qué está reaccionando:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..." \
  -H "Content-Type: application/json" \
  -d '{"commit":"abc123","branch":"main"}'

El payload se añade a las instrucciones que ejecuta la ejecución, bajo un encabezado Trigger payload (JSON):, tanto para ejecuciones de chat como para tareas de Work nuevas y rutinas vinculadas a una tarea. Solo se transportan objetos JSON (los arrays y los valores escalares se ignoran), y un payload cuya forma serializada supere los 4000 caracteres se descarta en vez de truncarse, con un aviso en el registro del servidor. Un disparo sin cuerpo se comporta exactamente como antes.

API

Todos los endpoints salvo el disparo por webhook exigen autenticación y solo operan sobre recursos del llamante; el disparo por webhook se autentica con el secreto de la automatización.

Método	Ruta	Propósito
GET	/api/automations	Listar automatizaciones
POST	/api/automations	Crear una automatización
GET	/api/automations/occurrences?from=&to=	Próximas ocurrencias
GET	/api/automations/runs	Historial filtrable
GET	/api/automations/runs/summary	No vistos y grupos de 30 días
POST	/api/automations/runs/seen	Marcar finalizadas como vistas
GET	/api/automations/:automationId	Leer
PUT	/api/automations/:automationId	Actualizar
DELETE	/api/automations/:automationId	Eliminar
POST	/api/automations/:automationId/pause	Pausar
POST	/api/automations/:automationId/resume	Reanudar
POST	/api/automations/:automationId/run	Ejecutar ahora (202 e ID)
POST	/api/automations/:automationId/webhook	Disparar con el secreto (202)
POST	/api/automations/:automationId/webhook-secret	Generar o rotar el secreto
DELETE	/api/automations/:automationId/webhook-secret	Desactivar el webhook

Cada usuario puede conservar 50 automatizaciones; los nombres admiten 200 caracteres y las instrucciones 20,000.