Automazioni

Le automazioni eseguono un'istruzione secondo una pianificazione e consegnano il risultato come una normale sessione di chat. Un riepilogo quotidiano delle notizie, una revisione settimanale, un rapporto mensile: ogni esecuzione avviene senza interfaccia sul server, compare nell'elenco delle chat e può essere aperta e proseguita come qualsiasi altra conversazione.

Anatomia

Un'automazione comprende un nome, istruzioni in testo libero, uno o più trigger, un modello facoltativo (vuoto significa Auto: il tuo modello di chat predefinito al momento dell'esecuzione), una destinazione di esecuzione e una preferenza per le notifiche (nell'app oppure disattivate). La destinazione decide che cosa produce un'esecuzione: Sessione di chat (valore predefinito) accoda le istruzioni come conversazione, mentre Attività Work avvia un ambiente isolato Work con le istruzioni come messaggio iniziale, eventualmente soggetto a un criterio Work denominato scelto nel modulo. Con le notifiche attive, un'esecuzione non riuscita compare anche nella casella delle notifiche, così gli errori ti raggiungono anche quando la pagina Automazioni è chiusa. Separatamente, attivare Risultati delle automazioni in Impostazioni → Notifiche → Notifiche email ti invia via email l'esito di ogni esecuzione, una volta che un amministratore ha configurato un server di posta in uscita (vedi Notifiche). Nomi e istruzioni sono cifrati a riposo. Ogni automazione appartiene all'utente che l'ha creata.

I trigger riutilizzano il modello condiviso del calendario: once, hourly, daily, weekly, monthly, yearly; un'automazione può contenerne fino a cinque. La prossima esecuzione è sempre la ricorrenza futura più vicina tra tutti i trigger, calcolata nel fuso orario locale del server.

Trigger a evento

Un settimo tipo, event, non ha alcun orologio: si attiva quando arriva una delle tue notifiche.

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

event corrisponde a qualsiasi tipo di notifica tranne automation-failed — una routine non deve poter riavviarsi da sola a partire dal proprio avviso di fallimento. Il campo facoltativo match è un confronto per sottostringa, senza distinzione tra maiuscole e minuscole, sul titolo della notifica; se omesso, ogni notifica di quel tipo attiva la routine.

Un trigger a evento non contribuisce mai a un orario di prossima esecuzione. Un'automazione i cui trigger sono tutti a evento quindi non mostra alcuna prossima esecuzione: l'elenco e la finestra di modifica indicano Viene eseguita quando… al suo posto. Combinare un trigger a evento con una pianificazione è possibile: i trigger pianificati continuano comunque a far scattare l'orologio.

Due limiti contengono il raggio d'azione. Una routine si attiva al massimo una volta al minuto a partire dagli eventi, per quanto intenso sia il flusso, e la notifica del fallimento di un'esecuzione non riattiva mai la routine che l'ha prodotta.

L'esecuzione riceve ciò che l'ha attivata, aggiunto alle sue istruzioni:

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

Esecuzione

Un tick del pianificatore viene eseguito ogni minuto dietro un lease di coordinamento, così una sola replica fa avanzare le pianificazioni. Quando un'automazione è pronta, il tick registra un'esecuzione, accoda un job duraturo automation.run.v1 e fa avanzare next_run_at con un confronto e impostazione, affinché ogni ricorrenza si attivi al massimo una volta. Il job crea una sessione di chat intitolata come l'automazione, quindi accoda l'istruzione attraverso la stessa pipeline duratura di generazione delle chat usata da ogni conversazione, inclusi instradamento dei provider, valori predefiniti dei personaggi e persistenza.

Se il server non era in esecuzione quando è trascorsa una ricorrenza, il tick successivo la avvia una volta e salta tutte quelle precedenti mancate. La sospensione di un'automazione ne cancella la pianificazione; la ripresa o la modifica la ricalcola dal momento attuale. L'eliminazione di un'automazione rimuove la relativa cronologia delle esecuzioni tramite una cascata di chiavi esterne.

Gli esiti delle esecuzioni derivano dal registro dei job duraturi: riuscita quando è terminata la generazione della chat, non riuscita quando il job viene spostato tra quelli irrecuperabili e non riuscita come stalled quando un'esecuzione in coda non inizia entro 30 minuti.

Le esecuzioni destinate a Work si comportano allo stesso modo, sostituendo al job di chat il ciclo di vita di Work: l'esecuzione registra l'attività creata (la scheda Esecuzioni vi rimanda direttamente), riesce quando l'agente termina oppure si arresta per chiedere un input e non riesce quando l'attività fallisce o viene annullata. L'email con l'esito di un'esecuzione destinata a Work riporta il riepilogo che l'esecuzione Work stessa ha salvato — lo stesso testo su cui l'agente si è fermato, il testo mostrato dalla cronologia delle esecuzioni dell'attività — e ripiega sullo stato in una riga dell'attività quando un'esecuzione precede l'introduzione dei riepiloghi salvati. L'accesso a Work viene verificato quando parte la pianificazione, quindi la revoca dell'accesso Work a un utente disattiva anche le relative automazioni destinate a Work; l'esecuzione non riesce come work-access-denied, anziché essere saltata senza avviso. Il criterio selezionato viene convalidato quando si salva l'automazione e la relativa impostazione di rete predefinita e i limiti di risorse si applicano a ogni attività avviata dall'automazione. In Work vengono eseguiti soltanto provider di modelli diretti e il modello deve supportare gli strumenti: sono le stesse regole del compositore Work.

Routine degli agenti

Un'automazione destinata a Work può invece essere associata a un'attività Work esistente tramite workTaskId: è la struttura su cui si basa la sezione Routine del pannello dei dettagli di un agente. Una routine associata non crea una nuova attività a ogni attivazione: ogni ricorrenza avvia un'esecuzione all'interno dell'area di lavoro e della conversazione dell'attività, usando modello, provider e criterio del runtime di quest'ultima; pertanto i campi modello e criterio a livello di automazione non si applicano e qualsiasi criterio specificato viene rimosso al momento del salvataggio. L'associazione viene convalidata quando si salva l'automazione (l'attività deve esistere e appartenere al chiamante). Al momento dell'attivazione, un'attività eliminata fa fallire l'esecuzione come work-task-missing, mentre un'attività già in esecuzione o con un'anteprima attiva fa fallire correttamente la ricorrenza come work-task-busy, senza accodarla.

Trigger webhook

Oltre alla pianificazione, un'automazione può essere avviata da un sistema esterno: una pipeline CI, un servizio cron, la domotica. Nella finestra di modifica dell'automazione, Trigger webhook → Abilita genera un segreto specifico per quell'automazione; ne viene memorizzato solo l'hash SHA-256, quindi il testo in chiaro è mostrato esattamente una volta. La rotazione del segreto invalida immediatamente quello precedente e la disattivazione del webhook richiude l'endpoint.

Il sistema esterno avvia l'automazione con:

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

(X-Libre-Webhook-Secret: lwh_... funziona come intestazione alternativa.) La risposta è 202 con l'ID dell'esecuzione accodata: è lo stesso percorso di esecuzione manuale di Esegui ora, quindi le esecuzioni si concludono, notificano e compaiono nella cronologia in modo identico. Il confronto del segreto avviene a tempo costante, un'automazione inesistente e un segreto errato rispondono in modo identico (nessun oracolo sugli ID delle automazioni) e un'automazione sospesa risponde 409: a differenza di Esegui ora del proprietario, un chiamante esterno non può attivarla superando una sospensione.

Un oggetto JSON nel corpo della richiesta entra nell'esecuzione come payload del trigger, così la routine può vedere a cosa sta reagendo:

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

Il payload viene aggiunto alle istruzioni eseguite dall'esecuzione, sotto un'intestazione Trigger payload (JSON): — per le esecuzioni di chat, le nuove attività Work e le routine associate a un'attività, allo stesso modo. Vengono trasportati solo oggetti JSON (array e valori scalari vengono ignorati), e un payload la cui forma serializzata supera i 4000 caratteri viene scartato anziché troncato, con un avviso nel log del server. Un'attivazione senza corpo si comporta esattamente come prima.

API

Tutti gli endpoint tranne l'attivazione via webhook richiedono autenticazione e operano solo sulle automazioni del chiamante; l'attivazione via webhook si autentica invece con il segreto specifico dell'automazione.

Metodo	Percorso	Scopo
GET	/api/automations	Elenca le automazioni
POST	/api/automations	Crea un'automazione
GET	/api/automations/occurrences?from=&to=	Ricorrenze future calcolate
GET	/api/automations/runs	Cronologia esecuzioni (filtrabile)
GET	/api/automations/runs/summary	Conteggio non visti + intervalli di 30 giorni
POST	/api/automations/runs/seen	Contrassegna come viste le esecuzioni concluse
GET	/api/automations/:automationId	Legge un'automazione
PUT	/api/automations/:automationId	Aggiorna un'automazione
DELETE	/api/automations/:automationId	Elimina un'automazione
POST	/api/automations/:automationId/pause	Sospende la pianificazione
POST	/api/automations/:automationId/resume	Riprende la pianificazione
POST	/api/automations/:automationId/run	Esegue ora (202 con un ID esecuzione)
POST	/api/automations/:automationId/webhook	Attiva tramite segreto (202)
POST	/api/automations/:automationId/webhook-secret	Genera o ruota il segreto
DELETE	/api/automations/:automationId/webhook-secret	Disattiva il webhook

Un utente può conservare fino a 50 automazioni; i nomi sono limitati a 200 caratteri e le istruzioni a 20.000.