# Combot Automation Compact v3: istruzioni per LLM e riferimento del formato

Fornisci questo file intero a un modello insieme alla richiesta della regola. Descrive il formato importato dall'editor di Automation. Il linguaggio delle regole è JSON Compact v3, non Python, YAML, JavaScript, il vecchio Triggers v2 o pseudocodice arbitrario «se → allora».
Le etichette dell’interfaccia sono tradotte, i valori JSON no. Per esempio, `Known Combot links` corrisponde a «Link di invito Combot» e `Combot custom admins` a «Amministratori Combot» nell’editor. Non sostituire questi valori JSON con le etichette dell’interfaccia.

Revisione del documento: 9 settembre 2026. Il riferimento è stato confrontato con l'editor e il gestore di Automation. I controlli completati di importazione e in Telegram sono elencati separatamente alla fine: esaminare il codice sorgente non stabilisce la versione di un servizio in esecuzione.

## 1. Istruzioni per il modello

Traduci la richiesta della persona in una regola Automation senza cambiarne il significato.

1. Stabilisci evento, condizioni, esclusioni, azione, destinatario dell'azione e destinazione della risposta. Per una programmazione, stabilisci il fuso orario; per un comando, se viene inviato da solo o in risposta. Non aggiungere moderazione, premi, casualità o eliminazione se non richiesti.
2. Non indovinare ID utenti, argomenti, indirizzi delle chat, inviti, livelli o funzioni attive. Il nome di un argomento non è il suo ID. Fai domande quando mancano informazioni essenziali. Puoi proporre separatamente ipotesi sul testo della risposta, ma non presentare una regola incompleta come soluzione esatta.
3. Genera sempre nuove regole con `en: false`. È una convenzione per prepararle in sicurezza, non un limite di Automation. Omettere `en` significa attivo.
4. Usa solo campi documentati. Per i filtri annidati contrassegnati con «usa un'esportazione», chiedi un'esportazione reale di una configurazione simile; non inventare la struttura. Se uno scenario non è supportato, spiega il limite anziché nasconderlo rimuovendo condizioni.
5. Rispondi con una breve spiegazione → un blocco JSON importabile → impostazioni e controlli manuali. Il JSON non deve contenere commenti, puntini di sospensione, ID segnaposto, righe esplicative fuori dai campi, virgole finali o chiavi inventate come `when`, `if`, `then`, `conditions`, `actions` o `event`.
6. Prima di restituire il risultato, ragiona su un caso corrispondente e uno non corrispondente. Per un comando in risposta, controlla separatamente chi invia il comando e l'autore del messaggio originale. Non dichiarare di aver provato una regola in Combot se non è realmente accaduto.

Il JSON Schema allegato aiuta a generare nuove regole disattivate. I suoi campi obbligatori sono volutamente più rigorosi dell'importazione e non accetta tutte le vecchie esportazioni. I filtri annidati complessi vengono controllati solo come oggetti. Superare lo schema non prova compatibilità delle condizioni, disponibilità delle risorse, rispetto del piano o successo delle azioni Telegram.

## 2. Cosa incollare in Import

La radice è un oggetto con `v: 3` numerico e un array di regole `t`. Di solito restituisci una regola. Non restituire un array senza contenitore o `{"triggers": [...]}`: non sono il formato della finestra di importazione.

Un esempio minimo completo:

```json
{
  "v": 3,
  "t": [
    {
      "n": "Comando con informazioni sul corso",
      "en": false,
      "k": "c",
      "ctm": "p",
      "cm": ["/course_info"],
      "a": {
        "m": "a",
        "r": [
          {
            "i": "course_reply",
            "t": "s",
            "v": {
              "tx": "Le registrazioni delle lezioni sono nel messaggio fissato della chat.",
              "rp": "r"
            }
          }
        ]
      }
    }
  ]
}
```

`dv: "t3.compact.3"` è un indicatore di schema facoltativo. Ai nuovi risultati bastano `v` e `t`. L'importazione esistente riconosce un contenitore `bundle`, ma non serve per la generazione.

Non aggiungere `id` del server, `revision`, `chat_id`, `ck` calcolato o `$schema` nel pacchetto di importazione. Il server assegna un nuovo ID alla regola. `i` dell'azione è diverso: è un identificativo locale della riga, come `course_reply`. Deve essere univoco tra le azioni della regola e contenere 1–80 lettere latine, cifre, `_` o `-`.

La stessa chiave breve ha significati diversi a livelli diversi: `t` alla radice è l'elenco delle regole, `a.r[].t` è il tipo di azione e `a.r[].v` contiene i parametri dell'azione. Non confondere i livelli.

## 3. Campi principali della regola

| Campo | Significato |
| --- | --- |
| `n` | Nome non vuoto, fino a 80 caratteri nell'editor |
| `d` | Descrizione facoltativa, fino a 280 caratteri nell'editor |
| `en` | `false` per una nuova regola disattivata |
| `e` | Array dei codici evento, salvo che si tratti di un comando |
| `k`, `cm`, `ctm` | Modalità comando; vedi sotto |
| `a` | Piano delle azioni: `{"m":"a","r":[...]}` o `{"m":"r","r":[...]}` |
| `s`, `ti` | Dove controllare l'evento: chat di origine, Generale o argomenti selezionati |
| `at` | Quando è consentita la corrispondenza; filtro temporale, non timer |
| `wh`, `wx`, `wm` | Autore dell'evento: gruppi inclusi, esclusioni e combinazione dei gruppi |
| `cgr` | Condizioni numeriche: tempo in chat, messaggi, avvertimenti, XP, reputazione |
| `ua`, `ux`, `uar`, `ul`, `ulx` | Attributi del membro, valori dei campi e lingua |
| `twh`, `twx`, `tcg`, `tua`, `tux`, `tur`, `tlg`, `tlx` | Controlli sull'altro utente dell'evento, come l'autore a cui si risponde o il membro che entra |
| `tv`, `tr`, `ty`, `cs`, `lmin`, `lmax` | Condizioni sul testo |
| `mti`, `mtx`, `me`, `mex` | Tipi di messaggio ed entità del testo |
| `il`, `ilc`, `ilx` | Link d'invito per le richieste di iscrizione |
| `rct`, `rnt`, `rnx`, `rcy`, `rcx`, `rcn`, `rcm` | Condizioni sulle reazioni |
| `chl` | Link diretto a un elenco preciso per gli eventi di modifica delle sue attività |
| `cl` | Pulizia predefinita della risposta precedente: `n` o `ps` |
| `ov` | Insiemi alternativi di condizioni OR; usa un'esportazione per i casi complessi |

Non compilare ogni campo. Aggiungi solo le condizioni richieste pertinenti all'evento scelto. Un ingresso, per esempio, non richiede parole chiave nei messaggi e un contatore aggregato di reazioni non ha un utente preciso da premiare automaticamente.

## 4. Eventi

| `e` | Quando si attiva |
| --- | --- |
| `["m"]` | Nuovo messaggio nella chat |
| `["em"]` | Modifica di un messaggio |
| `["m","em"]` | Nuovo messaggio o modifica |
| `["lc"]`, `["el"]`, `["lc","el"]` | Commento del canale collegato, modifica o entrambi |
| `["cp"]`, `["ec"]`, `["cp","ec"]` | Post nel contesto del canale collegato, modifica o entrambi |
| `["jr"]` | Richiesta di iscrizione |
| `["nm"]` | Ingresso di un membro |
| `["ml"]` | Uscita o rimozione di un membro |
| `["cb"]`, `["rb"]` | Potenziamento aggiunto o rimosso |
| `["mr"]` | Cambiamento delle reazioni di un utente preciso |
| `["rc"]` | Aggiornamento dei conteggi aggregati anonimi delle reazioni nel contesto del canale collegato |
| `["ck"]` | Nuovo elenco di attività |
| `["cd"]` | Attività dell'elenco segnate come completate |
| `["ca"]` | Attività aggiunte all'elenco |

Non combinare tipi di evento non correlati, come `["m","nm"]`; usa regole separate. Sono consentite le coppie nuovo-più-modificato elencate. Non generare la modalità nascosta del bot ospite `gm`.

Una modifica è un'attivazione separata. Non aggiungerla automaticamente a XP, reputazione, avvertimenti o azioni che la persona si aspetta una volta sola.

## 5. Comandi semplici e comandi in risposta

Un comando semplice (Plain command), per esempio una risposta informativa:

```json
{"k":"c","ctm":"p","cm":["/course_info"]}
```

Un comando che il moderatore invia in risposta al messaggio di un membro (Reply target):

```json
{"k":"c","cm":["/team_pause"]}
```

Sono frammenti dei campi di una regola, non pacchetti di importazione autonomi.

Non aggiungere `e` a un comando. Fornisci in `cm` un elenco non vuoto di comandi personalizzati minuscoli con barra, usando lettere latine, cifre e `_`. Non presentare un comando inventato come integrato in Combot. Per i comandi in risposta ometti `ctm`; non inserirvi `reply_target`, `r` o il nome di una persona.

Un comando semplice non ha destinatario per azioni sugli utenti. Usa l'invio di un messaggio e, solo se richiesto esplicitamente, l'eliminazione del messaggio del comando. Silenziamenti, avvertimenti, XP e altre azioni su una persona richiedono un comando in risposta.

In un comando in risposta, `wh` controlla chi invia il comando, mentre `twh` e gli altri campi `t...` controllano l'autore del messaggio a cui si risponde. Usa `v.tg: "t"` per agire su quest'ultimo. Se Anna risponde `/team_pause` a Ilya, limita Ilya, non Anna.

Controllare solo `twh` non limita chi può chiamare il comando. Un comando dei moderatori deve includere `wh` secondo la richiesta. L'azione `d` elimina il comando stesso, non il messaggio di Ilya.

Non sostituire la modalità comando con una ricerca della stringa `/team_pause` in `tv`. Non aggiungere condizioni del comando nascoste dall'editor, come programmazioni, senza un'esportazione verificata.

## 6. Membri ed esclusioni

`wh` e `wx` usano queste stringhe esatte, non etichette tradotte:

`New members`, `Regular members`, `Ex-members`, `Whitelisted users`, `Admins`, `Telegram admins`, `Combot custom admins`, `Owner`.

Un elenco di inclusione vuoto non impone restrizioni di gruppo. Di solito puoi omettere `Anyone`. `wm: "o"` richiede un gruppo corrispondente; `wm: "a"` richiede tutti i gruppi selezionati. Le esclusioni in `wx` impediscono la corrispondenza indipendentemente dai gruppi positivi.

Esempio: chiunque tranne gli amministratori può inviare il messaggio corrispondente:

```json
{"wx":["Telegram admins","Combot custom admins","Owner"]}
```

Esempio: solo un amministratore Telegram o il proprietario può chiamare il comando:

```json
{"wh":["Telegram admins","Owner"],"wm":"o"}
```

Non confondere i ruoli. `Combot custom admins` descrive permessi Combot, non amministratori Telegram. Nel gestore, `Admins`, come `Telegram admins`, controlla gli amministratori Telegram incluso il proprietario; non aggiunge gli amministratori Combot. Per consentire entrambi i gruppi, elenca `Telegram admins` e `Combot custom admins` con `wm: "o"`. `Regular members` significa membri attuali conosciuti, non persone presenti da molto tempo o con molti messaggi. `New members` usa le impostazioni e le esenzioni già esistenti per i nuovi membri della chat; non indica «i primi sette giorni» fissi. Usa `cgr` per una durata esatta.

Non generare `Core members` o `Non-members`: non sono fornite definizioni affidabili per nuove regole. Informazioni mancanti sul membro non provano che non abbia mai fatto parte della chat.

Per il destinatario usa `twh`, `twx` e `twm`. Prendi altri valori contestuali, come `Target self`, `Target bots`, `Target Combot` e `Target linked channel post`, da un'esportazione adatta; non indovinarli nei filtri del mittente.

Per `nm` e `ml`, `wh`/`wx` descrivono chi ha avviato l'ingresso o la rimozione; `twh`/`twx` descrivono il membro il cui stato è cambiato. Se Anna aggiunge Ilya, le condizioni del nuovo membro riguardano Ilya tramite `t...`, non Anna. Scegliere `v.tg` in un'azione non scambia queste condizioni.

`am: "o"` controlla che sia un amministratore Telegram; `am: "n"` lo esclude. Non sostituisce la combinazione di ruoli in `wh`/`wx`. Per le nuove regole preferisci gruppi espliciti.

## 7. Tempo in chat, attività, XP e reputazione

Le condizioni numeriche vanno in `cgr`, oppure `tcg` per il destinatario. Questo frammento significa che il membro è in chat da al massimo un'ora e ha al massimo cinque messaggi registrati:

```json
{
  "cgr": {
    "logic": "All",
    "statistics": {
      "rules": [
        {"metric":"joinedDays","unit":"h","op":"lte","value":"1"},
        {"metric":"messageCount","unit":"c","join":"and","op":"lte","value":"5"}
      ]
    }
  }
}
```

Operatori: `eq` significa uguale a, `gte` almeno e `lte` al massimo. Indica sempre l'operatore esplicitamente. Non tradurre «meno di cinque» con `lte: 5`: per un contatore intero è `lte: 4`. Non usare un controllo `eq` su una durata esatta quando la persona intende «almeno»: il tempo continua a passare.

Metriche delle statistiche:

- `joinedDays`: tempo dall'ingresso in questa chat, non età dell'account o della persona. Unità: `s`, `m`, `h`, `d`, `w`, `mo`. Un giorno è di 24 ore, una settimana di 7 giorni e qui un mese di 30 giorni. Le nuove regole devono sempre includere un'unità.
- `messageCount`: messaggi registrati in questa chat; unità `c`.
- `warns`: avvertimenti attivi; unità `c`.

«Un messaggio registrato» è `{"metric":"messageCount","unit":"c","op":"eq","value":"1"}`. Non garantisce l'esecuzione una volta sola: aggiornamenti del contatore ed elaborazione dell'evento possono avvenire separatamente.

Altre sezioni:

```json
{
  "cgr": {
    "logic": "All",
    "xp": {
      "xp": {"rules":[{"op":"gte","value":"100"}]}
    },
    "reputation": {
      "reputation": {"rules":[{"op":"gte","value":"5"}]}
    }
  }
}
```

Le soglie dei livelli usano `cgr.xp.rank.rules`, ma i valori devono provenire dai veri livelli della chat, non da nomi inventati. Le righe supportano `join: "and" | "or"` e `mode: "include" | "exclude"`. Usa AND esplicito per condizioni semplici e un'esportazione reale per catene AND/OR complesse. `cgr.logic: "All" | "Any"` combina le sezioni. Una riga numerica di esclusione è un divieto: una corrispondenza positiva in un'altra sezione della stessa variante di condizioni non può aggirarla.

Non creare controlli sul tempo dal primo messaggio o dalla prima altra attività: `firstMessageAge` e `firstOtherActivityAge` non sono disponibili. Non promettere «l'attività della settimana scorsa» usando il `messageCount` totale. I dati non disponibili non devono diventare automaticamente zero.

## 8. Attributi e campi dell'utente

`ua` richiede attributi; `ux` li esclude. Valori esatti: `Any username`, `Telegram Premium`, `Bot account`, `Any last name`. Per esempio, `{"ux":["Bot account"]}` esclude i bot.

`ul` e `ulx` includono ed escludono codici lingua degli utenti, se forniti da Telegram. Non è la lingua di un messaggio né la nazionalità. Non dedurre la lingua dal nome del membro.

Le condizioni su valori specifici vanno in `uar`, o `tur` per il destinatario. Campi supportati: `user_id`, `name`, `username`, `last_name`, `bio`. La bio appartiene al contesto della richiesta di iscrizione; non è un campo del profilo continuamente disponibile per ogni membro.

Una condizione sullo username ha questa forma:

```json
{
  "uar": {
    "username": {
      "rules": [
        {"mode":"include","matchType":"Exact match","values":["example_member"]}
      ]
    }
  }
}
```

Mostra la struttura, non un membro reale. Per una richiesta effettiva usa solo lo username fornito dalla persona, senza `@`; chiedilo se manca. Fornisci gli ID come stringhe in `values`. Per il controllo degli accessi preferisci un ID fornito esplicitamente: nomi e username possono cambiare.

Qui `matchType` usa le stringhe complete `Exact match`, `Partial match` e `Regular expression`, non i codici del testo dei messaggi `f`, `p` e `r`. I valori di una riga sono alternative; le righe hanno `join`. Non inventare `Starts with` o `Ends with` per questi campi.

`ual` e `tul`: `a` significa tutte le regole; `o` qualsiasi gruppo. In questo profilo di generazione usa un'esportazione per le strutture di gruppo `uag` e `tug`.

## 9. Testo e tipo di messaggio

Usa `tv`, un array di stringhe, per cercare frasi. Basta una stringa corrispondente. Per esempio:

```json
{"tv":["dov'è la registrazione","registrazione della lezione"],"tr":"p","ty":"p","cs":false}
```

`tr`: `p` significa frasi, `w` parole e `r` espressioni regolari. La modalità parole non richiede ogni parola elencata. Neanche la normale corrispondenza parziale garantisce i confini di parola: «gatto» può corrispondere dentro «gattone».

`ty`: `f` significa tutto il testo, `p` parte del testo, `s` l'inizio, `e` la fine e `r` un'espressione regolare. `cs: true` distingue maiuscole e minuscole; `false` o l'omissione disattivano la distinzione. Per una FAQ semplice basta `tv`: la ricerca di frasi senza distinzione di maiuscole è predefinita.

`lmin` e `lmax` limitano la lunghezza del testo. Un limite vuoto o zero non impone un limite da quel lato. Non confondere la lunghezza del testo con il numero di parole.

Usa espressioni regolari solo quando la corrispondenza semplice non basta. Fornisci il modello come stringa JSON, eseguendo l'escape delle barre inverse; non aggiungere automaticamente delimitatori JavaScript `/.../i`. Per requisiti di parole esatte o negazioni complesse, spiega esempi corrispondenti e non corrispondenti.

`mti` include tipi di messaggio; `mtx` li esclude. Valori principali: `photo`, `video`, `animation`, `audio`, `document`, `sticker`, `voice`, `video_note`, `contact`, `location`, `poll`, `dice`, `game`, `paid_media`. Per esempio, `{"mti":["voice"]}` indica vocali; `{"mti":["photo","video"]}` significa foto O video, non entrambi gli allegati insieme.

L'editor ha anche `text` e `caption`. Partecipano alle impostazioni del contenuto testuale; non trattare `caption` come un tipo indipendente di allegato Telegram. Per «solo didascalie delle foto» o una distinzione rigorosa tra testo e didascalie, ottieni un'esportazione di quella configurazione. Il codec può omettere valori predefiniti, incluso un `text` da solo; quel valore nel JSON in ingresso non prova da solo che la restrizione sopravviva all'importazione.

`me` e `mex` richiedono o escludono entità del testo. Valori: `bot_command`, `url`, `text_link`, `mention`, `hashtag`, `cashtag`, `email`, `phone_number`, `emoji`, `custom_emoji`, `bold`, `italic`, `underline`, `strikethrough`, `code`, `pre`, `spoiler`, `blockquote`, `expandable_blockquote`. `mel: "a"` richiede tutte le entità incluse; `"o"` almeno una. Per qualsiasi link visibile o nascosto: `{"me":["url","text_link"],"mel":"o"}`.

`mef` restringe link, comandi e altre entità specifiche; `mmo` descrive proprietà dei media; `mtg` e `mog` sono gruppi di condizioni; `csx`/`cse` sono insiemi di caratteri. Genera questi campi complessi da un'esportazione reale. Non inventare sostituti come `max_file_size`, `allowed_domains`, `mime`, `language` o `contains_all`.

## 10. Orari e argomenti della chat

`s`: `sc` significa chat di origine, `gn` Generale e `st` argomenti selezionati. Per questi ultimi `ti` contiene ID positivi degli argomenti.

L'importazione reimposta gli argomenti di origine selezionati sull'intera chat e quelli di invio sull'argomento corrente. Succede anche con ID corretti e vale anche per le alternative OR. Se lo scenario dipende da un argomento, nominalo nella spiegazione e nelle impostazioni manuali obbligatorie. Non dichiarare il risultato pronto da attivare finché gli argomenti non sono stati selezionati di nuovo.

`at` imposta l'orario consentito per l'evento; non programma un invio autonomo. «Rispondere a una domanda la sera» è possibile. «Pubblicare ogni giorno alle 19:00 senza eventi in arrivo» richiede un programmatore, non questo attivatore.

Il bot controlla l'ora attuale mentre elabora l'evento, non il timestamp del messaggio originale. Una modifica al mattino controlla gli orari del mattino anche se il messaggio originale è stato scritto di notte.

Una fascia settimanale, lunedì–venerdì, 09:00–18:00 UTC:

```json
{"at":{"m":"w","wd":[0,1,2,3,4],"tw":[{"startMinute":540,"endMinute":1080}]}}
```

`wd`: 0 è lunedì e 6 domenica. Gli orari sono minuti interi dalla mezzanotte UTC, da 0 a 1439. Le fasce settimanali includono il minuto finale. Una fascia notturna può avere l'inizio maggiore della fine; il giorno della settimana usa la data UTC attuale, non il giorno di inizio del «turno». Controlla entrambi i lati della mezzanotte anziché indovinare i giorni necessari.

Le 09:00 e le 18:00 di Mosca corrispondono alle 06:00 e alle 15:00 UTC: minuti 360 e 900. Per smettere di corrispondere esattamente alle 18:00, l'ultimo minuto consentito è 14:59 UTC, ovvero `endMinute: 899`. Per altri fusi considera lo scarto e gli eventuali cambi dell'ora legale. Non inserire l'ora locale come UTC senza conversione.

Un intervallo di date:

```json
{"at":{"m":"d","s":"2026-10-01T00:00:00Z","e":"2026-10-07T23:59:59Z"}}
```

Illustra la forma, non le date della campagna della persona. L'inizio deve precedere la fine. In questa modalità entrambi gli estremi sono inclusi. `Z` significa UTC.

Gli orari di chiusura (Closing hours) usano le impostazioni esistenti della chat: `{"at":{"m":"c"}}`; al di fuori di quegli orari: `{"at":{"m":"c","i":true}}`. La modalità orari di chiusura include l'inizio ed esclude la fine. L'attivatore non configura gli orari di chiusura della chat. Senza una programmazione valida, non promettere che funzionino la condizione diretta o quella invertita.

## 11. Link d'invito, reazioni ed elenchi di attività

### Inviti

Per le richieste di iscrizione `["jr"]`, `il` accetta `Known Combot links`, `External invite link` o `Any source`. Omettilo quando non serve una restrizione.

`Known Combot links` significa link nel catalogo Combot di questa chat. `ilc` e `ilx` elencano codici di link inclusi ed esclusi in quel catalogo; prendi i codici esatti da un'esportazione o dai dati forniti. Elenchi vuoti mantengono il controllo sulla categoria generale.

`External invite link` significa un link identificato fuori dall'intero catalogo Combot, non «tutto tranne i miei due link selezionati». Un'origine sconosciuta o un catalogo non disponibile non possono essere trattati come link esterno. Non promettere che la condizione intercetti ogni richiesta senza un invito conosciuto.

### Reazioni degli utenti

Evento `["mr"]`. `rct` contiene `added` e/o `removed`. `rnt` e `rnx` includono ed escludono reazioni nel nuovo stato dell'utente. Se uno dei due è compilato, `rct` deve includere `added`.

Il gestore esegue `mr` solo quando Telegram fornisce `user`. Una reazione inviata come canale o amministratore anonimo con `actor_chat` non attiva questo evento. È diverso dai conteggi aggregati `rc`.

```json
{"e":["mr"],"rct":["added"],"rnt":["👍"]}
```

I valori delle reazioni sono emoji normali, ID di emoji personalizzate come stringhe oppure `paid`. `rnt` controlla tutto il nuovo stato, non solo la differenza. Se 👍 era già presente e l'utente aggiunge un'altra reazione, la condizione può corrispondere di nuovo. Il destinatario `u` qui è la persona che ha cambiato la reazione; non premia automaticamente l'autore del messaggio.

### Conteggi aggregati delle reazioni

Evento `["rc"]`. `rcy`/`rcx` scelgono i tipi di reazione conteggiati. `rcn`/`rcm` impostano soglie inferiori e superiori come interi non negativi. Zero o l'omissione significano nessun limite da quel lato.

```json
{"e":["rc"],"rcy":["👍"],"rcn":10}
```

Controlla il valore attuale a un aggiornamento, non «ha raggiunto dieci per la prima volta». Un altro aggiornamento corrispondente può eseguire di nuovo l'azione. Il contatore aggregato anonimo non ha un utente preciso che ha reagito.

### Elenchi di attività

Per `["cd"]` e `["ca"]`, `chl` limita la regola a un elenco. Se la persona vuole un elenco preciso, chiedi il link diretto al suo messaggio. Se vuole tutti gli elenchi corrispondenti in una chat o argomento, non aggiungere `chl`.

Sono supportati i link Telegram diretti, compresi quelli con numero dell'argomento; non quelli con `?comment=`. Non inventare un indirizzo. Per un link pubblico il gestore dell'evento deve conoscere lo username della chat; un URL apparentemente valido non stabilisce da solo la corrispondenza.

## 12. Azioni

`a.m: "a"` esegue ogni riga in ordine. `a.m: "r"` esegue tutte le righe contrassegnate con `fr: 1` e una sola riga casuale non contrassegnata, se ne esistono. Le righe selezionate mantengono l'ordine originale. Usa la modalità `a` salvo richiesta di casualità; non aggiungere `fr` fuori dalla modalità casuale.

| Codice `a.r[].t` | Azione | Parametri `v` |
| --- | --- | --- |
| `s` | Inviare un messaggio | `tx` e formattazione; vedi sotto |
| `d` | Eliminare il messaggio che ha attivato la regola | Nessun parametro |
| `w` | Aggiungere avvertimenti | `tg`, `c` positivo, di solito 1 |
| `rw` | Rimuovere avvertimenti | `tg`, `c` positivo, di solito 1 |
| `m` | Limitare l'invio di messaggi | `tg`, durata `du` in secondi |
| `b` | Bannare | `tg`, durata `du` in secondi |
| `k` | Rimuovere dalla chat consentendo il ritorno | `tg` |
| `um` | Togliere le limitazioni all'invio di messaggi | `tg` |
| `ub` | Revocare un ban | `tg` |
| `du` | Eliminare i messaggi utente memorizzati disponibili al bot | `tg` |
| `x` | Modificare gli XP | `tg`, intero `v` diverso da zero da −99999 a 99999 |
| `r` | Modificare la reputazione | `tg`, intero `v` diverso da zero da −999 a 999 |
| `ja` | Approvare una richiesta di iscrizione | Solo evento `jr`, nessun parametro |
| `jd` | Rifiutare una richiesta di iscrizione | Solo evento `jr`, nessun parametro |

Non confondere il codice azione `du` con il campo durata `v.du`. La durata è in secondi, non minuti: un'ora è 3600. Zero per silenziamento o ban significa nessuna fine specificata; non sostituirlo mai a una durata sconosciuta. Se richiesto, puoi scrivere il motivo in un messaggio separato; non promettere un motivo personalizzabile della sanzione tramite un campo non documentato.

Destinatario dell'azione utente `v.tg`:

- `u`: il partecipante che ha causato l'evento.
- `t`: il destinatario definito dal contesto, come l'autore del messaggio a cui si risponde. Non un ID letterale.
- `l`: il creatore del link d'invito nel catalogo Combot, nel contesto di una richiesta di iscrizione.
- `b`: entrambi i partecipanti disponibili nel contesto pertinente. Non «tutti nella chat».

Specifica sempre il destinatario. I comandi semplici non supportano azioni sugli utenti. I comandi in risposta supportano mittente, destinatario ed entrambi. Per una richiesta di iscrizione usa azioni separate per richiedente (`u`) e creatore conosciuto del link (`l`) se servono entrambi: `b` non significa richiedente più creatore del link. L'editor propone il creatore del link per le richieste di iscrizione; non proporre la stessa scelta nelle istruzioni passo passo per l'ingresso di un membro. Per altri eventi usa solo destinatari disponibili in quell'evento.

Un destinatario sconosciuto non deve trasformare un'azione in una punizione per chi invia il comando. Non promettere un ripiego su un'altra persona. L'azione `du` non garantisce l'eliminazione dell'intera cronologia di un membro: il bot è limitato dai messaggi disponibili e dalle capacità di Telegram.

Avvertimenti, livelli e reputazione devono essere attivi quando lo scenario dipende da loro, e la moderazione richiede i permessi adatti del bot. Togliere un silenziamento, revocare un ban e approvare una richiesta di iscrizione sono azioni separate.

Gli eventi di richiesta di iscrizione consentono invii di messaggi, azioni sugli utenti disponibili e `ja`/`jd`; l'eliminazione `d` non è adatta. Per gli eventi senza messaggio non aggiungere eliminazione o risposta a un messaggio inesistente.

## 13. Testo e destinazione della risposta

Parametri dell'azione `s`:

| Campo | Significato |
| --- | --- |
| `tx` | Testo non vuoto fino a 4096 caratteri; è consentito l'HTML supportato da Telegram |
| `d` | `sc`: chat di origine; `lg`: canale di log configurato; predefinito `sc` |
| `tp` | `ct`: argomento corrente; `gn`: Generale; `st`: argomenti selezionati; predefinito `ct` |
| `to` | ID positivi degli argomenti selezionati; reimpostati dall'importazione |
| `rp` | `r`: risposta al messaggio attivatore; omissione: messaggio autonomo |
| `cl` | `n`: conserva la risposta precedente; `ps`: elimina la risposta precedente di questa riga |
| `bt` | Righe di pulsanti URL: array di array di oggetti con `text` e `url` |
| `ph` | Array di URL immagini per le anteprime dei link |
| `pa` | `true`: posiziona l'anteprima sopra il testo |

`rp: "r"` viene mantenuto per la chat di origine e l'argomento corrente. Non promettere lo stesso collegamento di risposta nei log o in un altro argomento. Non inserire chat, canali o messaggi privati esterni arbitrari in `d`.

Se manca `cl` a livello della riga, eredita l'impostazione della regola. `cl: "ps"` a livello della regola attiva la pulizia delle risposte precedenti; `cl: "n"` esplicito nella riga prevale. La pulizia appartiene a una regola, riga di azione e destinazione precise. Righe casuali diverse non diventano un unico «ultimo benvenuto» condiviso.

Per una risposta normale puoi usare `<b>Informazioni sul corso</b>\nLe registrazioni sono nel messaggio fissato.` Non fornire Markdown come HTML. Esegui correttamente l'escape di link e testo. Aggiungi pulsanti e immagini solo con URL reali forniti dalla persona; `ph` non invia un album fotografico.

Variabili confermate del contesto messaggio: `{name}`, `{uid}`, `{name_link}`, `{from.id}`, `{from.title}`, `{from.username}`, `{chat.id}`, `{chat.title}`, `{chat.username}`, `{message.id}`, `{message.timestamp}`, `{timestamp}`, `{group_name}`, `{reply_to_uid}`, `{reply_to_name}`, `{reply_to_name_link}`. La disponibilità dipende dall'evento. Non inventare `{target.name}`, `{user.first_name}`, `{reaction_count}` o variabili simili.

In un comando in risposta, `{from.title}` descrive chi invia il comando, non il membro punito o premiato. Scegliere `tg: "t"` non cambia il significato delle variabili. Se non sei certo che l'evento fornisca il nome richiesto, usa una formulazione neutra.

Anche durante un ingresso, `{from.title}` non garantisce il nome del nuovo membro: se Anna aggiunge Ilya, è Anna ad agire. Usa un benvenuto generico come «Benvenuto in {chat.title}!» senza nome.

Le azioni non sono una transazione. Un messaggio dopo un silenziamento non prova che Telegram lo abbia applicato. Non formulare una conferma incondizionata di una sanzione come risultato verificato: qui non è documentata una condizione separata di controllo del successo.

## 14. Alternative, limiti e promesse non supportate

`ov` contiene condizioni alternative della stessa regola. Condividono evento e azioni del genitore, anziché definire scenari indipendenti. Un'esclusione in un'alternativa non è globale. Se un divieto deve valere sempre, mantienilo in ogni alternativa. Un'alternativa con `en: false` non partecipa alla corrispondenza.

Usa esportazioni reali dell'editor per nuovi `ov`, `mtg`, `mog`, `uag`, `tug`, `mef` e `mmo` complessi. Non creare alberi OR ricorsivi e non inserire catene di azioni separate nelle alternative aspettandoti esecuzioni indipendenti.

Nelle esportazioni possono comparire i campi di compatibilità `mt`, `mtl`, `t`, `rmi` e `rme`. Non aggiungerli al posto delle impostazioni principali documentate senza un motivo. Per restrizioni semplici sulle risposte usa `rm`: `a` qualsiasi messaggio, `r` solo risposte, `rb` risposte a un bot, `rc` risposte a Combot, `nr` messaggi non in risposta. Non usare `rm: "cr"` al posto dei nuovi campi comando.

Non generare campi vecchi o interni `lf`, `fc`, `lo`, né campi UI `actions`, `destination`, `topic`, `applyTarget` e `alwaysRun`. Il formato Compact li rappresenta diversamente e alcune impostazioni non sono affatto funzioni attive.

Limiti per la pianificazione:

- Free: fino a 2 regole salvate; Pro: fino a 50; Business: fino a 100. Contano anche quelle disattivate. Considera le regole già presenti per valutare i posti rimasti.
- Alternative OR aggiuntive per regola: Free 0, Pro 2, Business 5.
- Fino a 100 righe di azioni per regola, con un limite separato di 20 azioni calcolate per esecuzione del piano.
- Un invio costa 1 per destinazione univoca, oppure 2 con pulizia della risposta precedente. Le azioni Telegram sugli utenti vengono contate per destinatario, quindi `b` può riservare il doppio. XP e reputazione costano 0 in questo calcolo. La modalità casuale conta le righe obbligatorie più la scelta casuale più costosa.
- È un calcolo interno, non la promessa di esattamente venti richieste di rete comprese tutte le operazioni ausiliarie. Se la prossima riga supera il limite rimanente, l'esecuzione si ferma; le azioni completate non vengono annullate.

Non promettere esecuzioni solo a timer senza evento, «al massimo una volta all'ora», premi unici per reazioni, protezione dagli abusi dei premi su eventi ripetuti, solo il primo superamento di una soglia, esecuzione esattamente una volta, elaborazione di chat esterne arbitrarie, età dell'account o statistiche di attività su un periodo passato arbitrario. Se uno di questi requisiti è essenziale, spiega che la sola regola descritta non basta.

L'importazione aggiunge nuove copie delle regole; non migra il vecchio Triggers v2. Puoi riscrivere il significato di una vecchia regola in Compact v3, ma non presentare il suo vecchio JSON come importazione pronta.

## 15. Scenari di accettazione degli esempi

La cartella allegata `examples` contiene sei pacchetti indipendenti, ciascuno con una regola disattivata:

| File | Caso corrispondente | Controlli aggiuntivi |
| --- | --- | --- |
| `01-course-command.json` | Un membro inserisce `/course_info` | Testo normale senza comando non deve attivare una risposta |
| `02-recording-faq.json` | Il testo contiene «dov'è la registrazione» | Una domanda non pertinente non deve attivare una risposta; la ricerca parziale può corrispondere a una frase più lunga |
| `03-random-welcome.json` | Entra un nuovo membro | Deve essere scelto un benvenuto, non tutti e tre |
| `04-moderator-reply-mute.json` | Un amministratore Telegram o il proprietario risponde `/team_pause` a un membro | I membri normali non possono chiamarlo; i destinatari amministratori sono esclusi; un comando senza risposta non deve limitare chi lo invia |
| `05-known-link-join-request.json` | Una richiesta usa un link del catalogo Combot | Origini esterne o sconosciute non devono corrispondere; tutti i link conosciuti corrispondono salvo selezione di link precisi |
| `06-thumbs-up-reaction.json` | Un utente aggiunge una reazione e il nuovo stato contiene 👍 | Rimuovere 👍 non corrisponde; modifiche corrispondenti ripetute possono inviare un altro messaggio |

Sono scenari di accettazione per la tua chat, non una dichiarazione che siano stati tutti eseguiti. Seguono i controlli completati. Ogni esempio richiede un controllo delle impostazioni e delle capacità nella tua chat prima dell'attivazione.

## 16. Fonti del formato e verifiche completate

Il formato è stato confrontato con Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` e bot `ddc1a8a6b6ab99bd2517d783870495990c7058e5`. Queste revisioni del ramo principale includono le correzioni coordinate dell'editor e di Automation. Le integrazioni di Rails PR #78 e bot PR #56 sono state confermate su Codeberg; le revisioni esatte dei processi distribuiti non sono state stabilite indipendentemente.

Fonti principali: `trigger_compact_codec_helpers.js`, `trigger_import_export_helpers.js`, `trigger_validation_helpers.js`, registri di eventi e azioni, `user_attribute_model_helpers.js`, `AutomationController`, contratto dettagliato di Automation in `docs/MONGODB.md` e gestione delle condizioni e azioni in `automation.py`.

I sei esempi originali sono stati controllati in memoria usando il codec sorgente dell'editor: decodifica, ricostruzione, nuova decodifica e stabilità del risultato normalizzato. Azioni e stato disattivato sono stati mantenuti. Il codec omette alcuni valori predefiniti, quindi il confronto ha usato risultati normalizzati anziché uguaglianza byte per byte con il JSON in ingresso.

L'8 settembre è stato controllato lo stato disattivato dei sei esempi originali dopo importazione tramite l'editor di produzione su combot.org, salvataggio sul server e ricaricamento della pagina. Questo non sostituisce la verifica di ogni condizione e azione in Telegram.

I casi comando e FAQ sono stati controllati in Telegram: le richieste corrispondenti hanno ricevuto le risposte previste e i controlli negativi no. Solo `/course_info` è stato cambiato in un nome di test univoco consentito dalle misure di protezione dello strumento di prova; le altre impostazioni degli esempi sono state mantenute. Questi risultati non provano automaticamente altri eventi e azioni.

Per `06-thumbs-up-reaction.json`, aggiungere 👍 da un profilo personale ha prodotto una risposta prevista; rimuoverla non ne ha prodotte. Identità e insiemi vecchi/nuovi delle reazioni sono stati confermati tramite un osservatore Bot API separato. Il benvenuto casuale all'ingresso, l'applicazione del silenziamento e l'approvazione di una richiesta di iscrizione reale non sono stati provati in quella sessione; l'importazione non prova l'esecuzione delle azioni.

Le regole di test create sono state rimosse ed è stato controllato il ripristino dell'elenco originale; i messaggi dei risultati rimangono nel gruppo di test. Il JSON Schema è documentazione allegata, non è collegato al prodotto né presentato come un validatore integrato esistente.

Il 9 settembre il riferimento editoriale è stato confrontato con Rails `0d80ce4788ef5adc5c7c1b79e85c6b8be27cc00e` e bot `0a491a6ee50c57e98c1d9de04819253d15214506`. I chiarimenti riguardano il limite del nome nell'editor, i gruppi di amministratori, i partecipanti degli eventi, i destinatari delle azioni e i link facoltativi agli elenchi. È una revisione della documentazione basata sul sorgente, non una nuova prova in Telegram. Il testo localizzato degli esempi non è stato verificato indipendentemente dal vivo.