Crea un bot Telegram per registrare le spese in Google Sheets

Un caffè, un biglietto dell’autobus, un quaderno. È facile dimenticare i piccoli acquisti prima di aprire un foglio di calcolo. E se bastasse un messaggio Telegram per registrarli e un altro per controllare il mese?

In questo tutorial crei Pocket Ledger, un tracker delle spese su Telegram con Google Sheets. Invia un acquisto, conferma i dettagli proposti e chiedi il totale mensile. Il foglio conserva le righe e fa i calcoli; il bot gestisce la conversazione. Ecco il risultato finale.

Il primo traguardo è un caffè salvato. Il secondo è un totale verificabile nel foglio. Scoprirai anche perché la parola «salvato» in una risposta è solo metà della prova.

Scarica il kit di configurazione Pocket Ledger con la cartella di lavoro iniziale già formattata, avatar, prompt, impostazioni delle Actions e scheda di test. Importa la cartella nel foglio creato da Quickchat AI, poi segui i passaggi sotto. Gli esempi copiabili usano sempre l’inglese e novembre 2026 per confrontare i tuoi risultati con le schermate.

Cosa serve per creare un registro spese Telegram?

Servono Telegram, un account Google e un account Quickchat AI. La configurazione usa le impostazioni della dashboard e una formula nel foglio; non occorre ospitare un programma.

1. Crea un account Quickchat AI, completa la verifica e crea un Agent chiamato Pocket Ledger.
2. Prepara un account Google per il nuovo foglio. Inizia con i dati fittizi riportati sotto.
3. Usa un nuovo bot Telegram per questo esercizio. Tieni disponibile un secondo account Telegram fidato per il test di accesso finale.

Il piano Free di Quickchat AI è destinato all’apprendimento personale e non commerciale e include una quota limitata. Le conversazioni AI e Simulation Testing consumano crediti. Consulta piani e quote attuali prima di scegliere un piano per l’uso continuativo.

Due direzioni, due Actions. Salvare una riga non dà all’Agent un modo per leggere i totali precedenti.

Passaggio 1: come colleghi il tuo bot Telegram privato?

BotFather crea l’identità del bot. Quickchat AI fornisce l’Agent che risponde ai suoi messaggi.

Apri @BotFather ufficiale, invia /newbot, chiama il bot Pocket Ledger e scegli un nome utente disponibile che termini con bot. Usa /setuserpic per caricare l’avatar del kit. Mantieni privato il token: lo incollerai direttamente in Quickchat AI.

In Quickchat AI apri External Apps → Telegram → Your own bot. Nella finestra Connect to Telegram, incolla la credenziale in Bot Token e conferma la finestra. Attiva Enable your own bot e fai clic su Save. La guida a BotFather descrive le schermate in dettaglio.

Apri il link del nuovo bot in Telegram, invia /start, poi invia Hello nella chat privata. /start invia il messaggio di benvenuto; il messaggio normale crea la conversazione in Inbox e i metadati del mittente necessari nei passaggi successivi. Lascia inattive le Actions che gestiscono dati personali durante la configurazione.

Apri questa conversazione in Quickchat AI, in Inbox → Details → Visitor. Trova Telegram User Id e Telegram Chat Type (le chiavi dei metadati sono telegram_user_id e telegram_chat_type). Copia l’ID utente numerico con il controllo che appare al passaggio del mouse e verifica che il tipo di chat sia private.

L’ID proviene dai metadati del mittente Telegram. Il nome utente, un numero scritto in un messaggio e l’ID del bot sono cose diverse. Nei prossimi passaggi userai l’ID del mittente per limitare entrambe le Actions.

Passaggio 2: come prepari il foglio Google?

L’integrazione Google Sheets crea un foglio e un’Action iniziale. Riutilizza quel file affinché l’Action e l’autorizzazione Google facciano riferimento alla stessa risorsa.

1. Apri Actions & MCPs → Add Action → Google Sheets e autorizza il tuo account Google. La guida alla connessione Google Sheets spiega il consenso e la configurazione iniziale.
2. Disattiva subito l’Action iniziale. Viene creata attiva. Mantieni il nome log_lead_to_google_sheet, perché la riconnessione lo usa per trovarla. Ne cambieremo lo scopo per salvare spese.
3. Apri il foglio creato e chiamalo Pocket Ledger demo. In questo nuovo file demo, scegli File → Import → Upload, seleziona pocket-ledger-starter.xlsx dal kit e scegli Replace spreadsheet. Poi fai clic su Import data. Questo prepara Expenses e Summary nel file a cui Quickchat AI può accedere. Usa questa opzione solo nel nuovo foglio demo.
4. Controlla le tre righe iniziali sotto. In Summary, i totali iniziali devono essere EUR 7.70 e USD 6.00. Il passaggio 6 spiega la formula e collega l’Action di lettura.

Inizia dalla connessione Google Sheets. L’autorizzazione crea il foglio usato da entrambe le Actions.

Preferisci creare le schede da te? Rinomina quella iniziale Expenses. Per questi esempi in inglese imposta File → Settings → Locale → United States. Formatta A:D e F:H come Plain text ed E come Number con due decimali, poi incolla il blocco sotto in A1. Blocca l’intestazione e allarga le colonne. Aggiungi Summary seguendo il passaggio 6. Google documenta anche come importare una cartella Excel in un foglio esistente.

date	month	item	category	amount	currency	note	conversation_url
2026-11-01	2026-11	coffee	food	4.50	EUR	synthetic example
2026-11-02	2026-11	bus ticket	transport	3.20	EUR	synthetic example
2026-11-03	2026-11	notebook	stationery	6.00	USD	synthetic example

La colonna conversation_url collegherà ogni nuova spesa alla conversazione. Lasciala vuota per i tre esempi inseriti manualmente. L’autorizzazione Google drive.file copre i file creati dall’app o concessi esplicitamente; questa configurazione usa il foglio creato dall’integrazione e non dà accesso all’intero Drive.

Passaggio 3: come limiti le spese alla tua chat?

Imposta Run only when su ogni Action che legge o scrive il registro. Entrambe le condizioni devono coincidere, quindi il solo ID non basta in una chat di gruppo.

1. Apri l’Action inattiva log_lead_to_google_sheet e trova Run only when.
2. Aggiungi entrambe le condizioni sopra. Usa le chiavi esatte dei metadati e le cifre del tuo ID, senza nome utente né prefisso @.
3. Salva l’Action lasciandola inattiva. Applica le stesse condizioni all’Action di lettura quando la creerai nel passaggio 6.

Le condizioni dell’Action di salvataggio nella demo locale. Sostituisci l’ID fittizio con quello del vero mittente e ripeti entrambe le condizioni sull’Action di lettura.

Entrambe le condizioni devono essere presenti su entrambe le Actions. Un mittente diverso o una chat di gruppo devono essere bloccati prima che la richiesta HTTP raggiunga Google Sheets.

Sono condizioni delle Actions applicate dal server. Scrivere «rispondi solo a me» nel prompt non è un controllo degli accessi. Limita anche la condivisione del foglio e l’accesso al tuo account Quickchat AI.

Passaggio 4: come fai salvare al bot una spesa confermata?

Modifica l’Action iniziale affinché aggiunga una riga nell’ordine delle colonne del foglio. Imposta When to run → AI decides, così potrà attendere la conferma. Poi assegna all’Agent una regola di conferma prima di attivarlo.

Configura i campi della spesa

In What to ask the user first, sostituisci i campi dei lead con questi parametri. Mantieni esattamente i nomi mostrati.

Mantieni l’ID reale del foglio nell’API Endpoint esistente. Cambia l’intervallo in Expenses!A:H, conserva il metodo POST e imposta Query Params su valueInputOption=RAW e insertDataOption=INSERT_ROWS. Rimuovi le impostazioni di query duplicate se sono già nell’URL.

POST https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Expenses!A:H:append
Query Params:
valueInputOption = RAW
insertDataOption = INSERT_ROWS
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Content-Type = application/json

YOUR_CREATED_SHEET_ID è un segnaposto esplicativo. Mantieni l’ID reale già presente nell’URL iniziale, senza sostituirlo con questo segnaposto. Seleziona il System Token Google Sheets esistente nel valore Authorization e la variabile integrata dell’URL della conversazione nel corpo.

Nella scheda Body, inserisci:

{"values":[["{{date}}","{{month}}","{{item}}","{{category}}","{{amount}}","{{currency}}","{{note}}","{{conversation_url}}"]]}

Configurazione locale dell’Action per le spese. Il corpo definisce l’ordine delle celle; il formato del parametro amount ne definisce il tipo numerico.

Mantieni le virgolette intorno a {{amount}} nell’editor. Poiché il segnaposto esatto rimanda a un parametro Decimal Number, la sostituzione produce un numero JSON come 4.5. Togliere le virgolette rende il JSON dell’editor non valido. Nel foglio risultante verifica che E sia numerico e venga incluso nella formula.

L’API append di Google aggiunge la riga. RAW mantiene letterale il testo, per esempio una nota che inizia con =, invece di valutarlo come formula. Il parametro numerico fornisce il tipo dell’importo.

Save one personal expense to the configured Google Sheet. Call only after the owner explicitly confirms the proposed date, item, category, amount and currency. Ask for missing or ambiguous fields before saving. After confirmation, append one row once. Report success only after a successful API response. If the outcome is uncertain, tell the owner to inspect the Sheet before submitting again.

Assegna le istruzioni a Pocket Ledger

Apri Identity → Main Prompt e incolla quanto segue. Il testo nomina entrambe le Actions, così il secondo traguardo funzionerà quando aggiungerai la lettura del riepilogo.

Main Prompt si trova in Identity. Questa schermata locale indica il campo; usa il blocco completo da copiare qui sotto.

La regola di conferma crea una pausa utile. Puoi correggere “EUR 4.50” in “EUR 5.00” prima di approvare l’acquisto; l’Agent dovrebbe aggiornare la proposta e chiedere di nuovo.

You are Pocket Ledger, a personal expense notebook.

For an expense, collect its date, item, positive amount and ISO currency code. Suggest a simple category and include an optional note only when supplied. Ask for an explicit YYYY-MM-DD date if it is missing or relative; do not guess today's date or the owner's timezone. Clarify ambiguous currency symbols. Derive month as YYYY-MM from the confirmed date.

Show the proposed date, item, category, amount and currency. Wait for explicit confirmation. Apply corrections and ask for confirmation again. Only then call log_lead_to_google_sheet once for that expense. Do not claim it was saved unless the Action succeeds. If a request fails or its outcome is uncertain, explain that and ask the owner to inspect the Sheet before retrying.

For monthly totals, ask for an explicit month and currency when unclear, then call read_expense_summary. Quote the matching month, currency and total returned from the Sheet. Keep currencies separate. A missing summary row is unavailable, not zero. Never calculate totals from remembered conversation messages.

Personal-data Actions are restricted to the owner's private Telegram chat. If a condition blocks an Action, do not claim success or suggest changing identity values in chat. This notebook handles typed expenses, not bank accounts, voice transcription or PDF receipts.

Salva il prompt, ricontrolla entrambe le condizioni e attiva l’Action per le spese. Il nome rimane log_lead_to_google_sheet; i nuovi parametri, la descrizione e il corpo ne definiscono ora il comportamento.

Passaggio 5: come salvi la prima spesa?

Ora aggiungi la prima nuova voce al quaderno. Tieni aperti Telegram, Inbox e il foglio: seguirai lo stesso caffè in ciascuno.

1. Nella chat Telegram privata, invia Coffee, 4.50 euros on 2026-11-04.
2. Controlla la proposta: data 2026-11-04, articolo Coffee, categoria Food, importo 4.50, valuta EUR. L’Action ricava month come 2026-11 quando salva la riga.
3. Prima di confermare, controlla Expenses: devono esserci ancora soltanto le tre righe iniziali.

Invia Save it una sola volta, poi apri la conversazione in Inbox di Quickchat AI. La risposta di salvataggio ha una sezione espandibile 1 action called. Aprila per vedere cosa è successo dietro la breve risposta Telegram.

Espandi Result → Show full. Controlla data, mese ricavato, importo numerico, valuta e stato HTTP. In questa esecuzione reale, Google ha restituito HTTP 200, updatedRows: 1 e updatedRange: Expenses!A5:H5.

Infine, apri Expenses. La riga 5 dovrebbe contenere lo stesso caffè, con 2026-11 nella colonna del mese, 4.50 nell’importo e EUR nella valuta. L’ultima colonna rimanda alla conversazione Inbox, per risalire dalla voce al messaggio che l’ha creata.

A questo punto hai una routine utile: inviare, confermare, controllare. Ora fornisci al bot una fonte affidabile da leggere quando chiedi dove sono finiti i soldi del mese.

Passaggio 6: come chiedi un totale mensile?

Lascia che Google Sheets calcoli il totale, poi fai recuperare il risultato all’Action di lettura. Conservare i calcoli nel foglio rende la risposta verificabile anche dopo la fine della conversazione.

Aggiungi una scheda Summary

Se hai importato la cartella iniziale, Summary e le formule sono già pronte. I valori iniziali sono EUR 7.70 e USD 6.00; salvare il caffè cambia solo la riga EUR. Se stai creando il foglio manualmente, segui i passaggi sotto.

1. Crea una scheda chiamata Summary. Imposta le colonne A:B su Plain text, poi inserisci month, currency, total in A1:C1.
2. Inserisci 2026-11 ed EUR in A2:B2, poi 2026-11 e USD in A3:B3.
3. Inserisci questa formula in C2 ed estendila fino a C3. Formatta C come numero con due decimali.

=SUMIFS(Expenses!$E$2:$E$501,Expenses!$B$2:$B$501,A2,Expenses!$F$2:$F$501,B2)

La funzione SUMIFS somma gli importi il cui mese e la cui valuta corrispondono alla riga del riepilogo. Se le impostazioni locali richiedono punti e virgola fra gli argomenti, sostituisci le virgole della formula. I numeri nelle richieste JSON continuano a usare il punto decimale.

Gli EUR 7.70 iniziali più il nuovo caffè da EUR 4.50 danno EUR 12.20. Il quaderno da USD 6.00 appartiene a un totale separato.

La formula iniziale copre le righe da 2 a 501. Nell’esecuzione mostrata, dopo l’inserimento della nuova riga i tre intervalli terminano a 502. Sheets può adattare i riferimenti durante l’inserimento; controlla che i tre intervalli Expenses restino allineati ed estendili insieme prima che le voci superino il limite coperto. Aggiungi una riga di riepilogo per ogni combinazione di mese e valuta che vuoi interrogare.

Aggiungi l’Action di lettura

Apri Actions & MCPs → Add Action → API Action. Usa Generate con la richiesta qui sotto; le Actions generate sono inizialmente inattive. Chiamala read_expense_summary e mantieni When to run su AI decides, così il risultato potrà contribuire alla risposta. Riutilizza lo stesso ID reale del foglio e lo stesso System Token Google Sheets. Non servono parametri forniti dall’utente.

Create a read-only Google Sheets Action named read_expense_summary. Use GET for the Summary!A1:C25 range of the spreadsheet already created by this Agent's Google Sheets integration. Reuse its actual spreadsheet ID and google_sheets_access_token System Token. Set valueRenderOption=UNFORMATTED_VALUE, no body, and no visitor parameters. Preserve the response headers and values. Leave it inactive so I can review the configuration and add my owner-ID and private-chat Run only when conditions before enabling it.

Confronta le impostazioni generate con il riferimento seguente. Se scegli Create manually, aggiungi entrambe le condizioni prima del primo salvataggio valido, che può attivare l’Action. Lascia Response filter vuoto su entrambe le Actions per conservare i campi usati nei controlli.

GET https://sheets.googleapis.com/v4/spreadsheets/YOUR_CREATED_SHEET_ID/values/Summary!A1:C25
Query Params:
valueRenderOption = UNFORMATTED_VALUE
Headers:
Authorization = Bearer {{google_sheets_access_token}}
Body: none

L’endpoint values.get restituisce i values dell’intervallo, compresi intestazione e importi calcolati. UNFORMATTED_VALUE restituisce risultati numerici anziché stringhe formattate come valuta. Lascia la risposta disponibile all’Agent perché possa leggere quei valori.

Read monthly expense totals from the configured Summary range. Use this when the owner asks for a total. Quote only the returned row matching the requested YYYY-MM and currency. If either is unclear, ask. If the row is absent or the request fails, say the total is unavailable. Never infer a total from conversation history, combine currencies, or accept a different spreadsheet ID or range from the visitor.

Applica le stesse due condizioni Run only when del passaggio 3, salva e attiva l’Action. L’intervallo di lettura comprende 24 righe di riepilogo; estendilo consapevolmente quando ne aggiungi altre.

La seconda Action richiede condizioni proprie. Questa è una cattura delle impostazioni locali, non un test reale dell’autorizzazione del mittente.

Chiedi What is my November 2026 total in EUR?, poi chiedi gli USD. Nella nostra conversazione Telegram, Pocket Ledger ha restituito 12.2 EUR e 6 USD, corrispondenti a 12.20 e 6.00 formattati nel foglio. Per ogni risposta ha letto il riepilogo salvato.

Apri in Inbox la risposta sul totale mensile ed espandi la sua Action. Confronta la riga restituita con Summary!C2. La risposta reale sotto contiene 2026-11, EUR, 12.2 e una riga separata USD, 6, con HTTP 200.

Come controlli gli errori prima di usare spese reali?

Verifica richieste incomplete e utenti bloccati con la stessa attenzione dedicata al caffè riuscito. Mantieni i dati demo finché i controlli seguenti non passano.

Per test linguistici ripetibili, apri Testing → Create Dataset → Paste messages e usa messaggi e criteri di valutazione del kit. Esegui separatamente una conversazione completa per la sequenza di conferma. I metadati di Preview o Simulation sono dati di test; non provano che un vero secondo mittente Telegram venga bloccato.

Il dataset locale è pronto per i test. La sua presenza non equivale a una Simulation completata né dimostra una scrittura in Google Sheets.

Se un comportamento non funziona, modifica una sola istruzione pertinente, poi ripeti lo stesso input e ricontrolla chiamata e foglio. Per esempio, un’aggiunta prematura richiede di esaminare la formulazione della conferma nell’Action di salvataggio. La conferma è un’istruzione, non una garanzia di unicità del database. Dopo un timeout, controllare il foglio conta più che inviare di nuovo.

Quando il percorso funziona, rimuovi le righe fittizie, mantieni intestazioni e formule e aggiungi righe di riepilogo per mesi e valute che usi davvero. La prima spesa reale può seguire la stessa routine del caffè.

Un assistente AI può aiutare a configurare Pocket Ledger?

Un assistente collegato alla gestione dell’account può preparare l’Agent e controllare le impostazioni delle Actions. Segui Manage with AI usando la scheda ChatGPT o la scheda Claude di Quickchat AI. Forniscigli il kit e questa richiesta:

Help me configure Pocket Ledger from this setup kit. Inspect the available Quickchat AI tools first. Prepare the Main Prompt and the two HTTP Actions using the exact field names, numeric amount type and fixed ranges. Keep log_lead_to_google_sheet as the starter name. Ask me to complete Google OAuth and Telegram Bot Token setup in the dashboard. Apply both owner/private run conditions before enabling either Action. Do not run credit-consuming tests or append expenses until I ask. Report any setting your tools cannot configure so I can complete it in the dashboard.

Il proprietario completa il consenso Google e la connessione Telegram. Controlla le impostazioni ed esegui le stesse verifiche sopra, indipendentemente da chi le ha inserite.

Domande frequenti

Come posso registrare le spese su Telegram con Google Sheets?

Collega un bot Telegram a un Quickchat AI Agent e autorizza Google Sheets. Configura un’Action per aggiungere una spesa dopo la conferma e un’altra per leggere un riepilogo mensile calcolato con formule. Limita entrambe le Actions al tuo ID utente Telegram e a una chat privata.

Il bot può dirmi quanto ho speso questo mese?

Sì, se il mese e la valuta richiesti hanno una riga nell’intervallo Summary configurato. Google Sheets calcola il totale con SUMIFS e l’Action di lettura lo recupera. Un’Action che aggiunge soltanto righe non può recuperare totali, e una riga di riepilogo assente non equivale a zero.

Un’altra persona può leggere le mie spese attraverso il bot Telegram?

Entrambe le Actions sui dati personali devono richiedere il tuo telegram_user_id verificato e telegram_chat_type uguale a private. Queste condizioni bloccano le chiamate da altri mittenti e dai gruppi. Verifica entrambi i casi prima di aggiungere dati personali e limita anche l’accesso al foglio e all’account Quickchat AI.

Questo registro spese Telegram è gratuito?

Creare un bot Telegram è gratuito. Il piano Free di Quickchat AI supporta l’apprendimento personale e non commerciale con una quota limitata di crediti AI. Le risposte AI e Simulation Testing consumano crediti; l’uso continuativo dipende dalla quota disponibile e dal piano.

Servono Apps Script, Python o un server di automazione?

Questa configurazione usa Quickchat AI Actions e una formula Google Sheets. Incolli impostazioni delle richieste, corpo JSON e prompt forniti nella dashboard; non devi distribuire Apps Script, un bot Python o un server di automazione.

Posso usare il mio foglio spese esistente?

Questa configurazione usa il foglio creato dall’integrazione Google Sheets di Quickchat AI. L’autorizzazione drive.file non dà accesso illimitato al Drive. Non sostituire l’ID del foglio con quello di un file esistente qualsiasi presumendo che sia accessibile.

Il bot può leggere foto di scontrini o messaggi vocali?

Questo tutorial tratta spese digitate. L’estrazione dagli scontrini richiede un test dedicato di consegna delle immagini su Telegram e conferma prima di poterci fare affidamento. Trascrizione vocale e lettura di scontrini PDF non fanno parte della configurazione.

Come vengono gestite valute diverse e voci duplicate?

Ogni valuta ha un totale mensile separato; la configurazione non converte valute. La conferma riduce gli inserimenti accidentali ma non garantisce la prevenzione atomica dei duplicati. Se un salvataggio scade, controlla il foglio prima di inviarlo di nuovo.