Raccolte e dati

Le raccolte sono le tabelle dati personali del tuo bot. Sono ideali per conservare richieste, ordini, risposte dai dialoghi, punteggi in gioco, prenotazioni — tutto ciò che il bot raccoglie dagli utenti o riceve dalle integrazioni. La sezione si trova nel menu a sinistra: Dati → Raccolte.

Che cos'è una raccolta

Una raccolta è composta da campi (lo schema che descrive le colonne) e record (le righe con i dati). Ogni record è un insieme di valori corrispondenti ai campi della raccolta; internamente viene salvato come documento JSON flessibile, quindi la raccolta gestisce senza problemi l'aggiunta di nuovi campi.

Il nome della raccolta è unico all'interno di un singolo bot e viene usato come identificatore nelle azioni delle reazioni (ad esempio leads, orders, scores).

Tipi di campo

Quando crei una raccolta, definisci l'elenco dei campi e il tipo di ciascuno:

text — stringa (nome, email, commento).
number — numero (importo, quantità, punteggio).
bool — sì/no (true / false).
datetime — data e ora.
json — oggetto o array annidato per valori complessi.

Il tipo influisce su come il campo viene modificato nell'interfaccia e su come il valore viene convertito al momento del salvataggio. Lo schema non è rigido: se un record contiene un campo fuori schema, verrà comunque salvato e visualizzato come colonna separata.

Creare una raccolta

Apri Dati → Raccolte e fai clic su Aggiungi.
Inserisci un nome (in caratteri latini, senza spazi — così è più facile referenziarlo nelle reazioni).
Con il pulsante Campo aggiungi le colonne necessarie e scegli il tipo di ciascuna.
Se necessario, configura le regole di conservazione (vedi sotto) e salva.

Record: visualizzazione e modifica

Nella scheda della raccolta c'è un pulsante con l'icona della tabella — apre la finestra Dati con i record di quella raccolta:

Visualizzazione — tutte le righe vengono mostrate in elenco, un campo per cella, a partire dalle più recenti.
Aggiungi record — apre un form basato sullo schema della raccolta; ogni campo è modificabile in base al suo tipo (interruttore per bool, campo di input JSON per json, ecc.).
Modifica (matita) — modifica una riga esistente.
Elimina (cestino) — elimina una riga.

I record vengono popolati anche automaticamente dalle azioni delle reazioni del bot (vedi sotto). La modifica manuale e la scrittura automatica operano sulla stessa raccolta.

Conservazione (retention)

Per evitare che la raccolta cresca indefinitamente, configura le regole di pulizia automatica:

Conserva al massimo N record — quando il limite viene superato, i record più vecchi vengono eliminati.
Conserva per non più di N giorni — i record più vecchi del periodo indicato vengono eliminati.

La pulizia viene eseguita periodicamente da un processo in background; le regole possono essere combinate.

Utilizzo dei dati dalle reazioni

Le raccolte sono direttamente collegate al costruttore di reazioni. Nelle azioni di una reazione sono disponibili:

Crea record — aggiunge una riga; i valori provengono dai template (ad esempio {{user.id}}, {{message.text}}). Puoi impostare una chiave di deduplicazione in modo che una chiamata ripetuta aggiorni la stessa riga invece di crearne un duplicato.
Aggiorna record — modifica le righe che soddisfano una condizione.
Leggi record — carica le righe nel contesto di esecuzione come array per elaborarle successivamente.
Elimina record — elimina le righe in base a una condizione.
Ciclo (for-each) — scorre l'array dal contesto ed esegue le azioni annidate per ciascun elemento (ad esempio, inviare un messaggio a ogni elemento di una lista dalla raccolta).

In questo modo il bot può gestire un CRM, accumulare richieste, assegnare punti e generare report senza un database esterno.

Accesso da Mini App

I record di una raccolta possono essere letti dalla Telegram Mini App del tuo bot: il frontend richiede i dati della raccolta per nome con filtri e un limite. Questo ti permette di mostrare all'utente i suoi ordini, la cronologia o la classifica direttamente all'interno di Telegram.

Suggerimenti

Dai ai campi nomi brevi e in formato macchina (email, total, paid) — sono più comodi da inserire nei template delle reazioni.
Per la scrittura idempotente (ad esempio «una sola richiesta per utente») usa la chiave di deduplicazione.
Abilita la retention per log e dati temporanei, in modo che la raccolta non cresca a dismisura.
Il tipo json è adatto quando la struttura del valore non è definita in anticipo.