An AI-powered Telegram bot for personal finance tracking β built with
Google Apps Script + Gemini API + Google Sheets.
π¬ Record your daily expenses naturally β get smart reports & friendly AI feedback.
πΈ 100% free, serverless, and open source.
π Runs entirely on Google infrastructure β no hosting or backend required.
| Language | File | Description |
|---|---|---|
| π»π³ Vietnamese | src/gemini-bot.vi.gs | Full Vietnamese version |
| π English | src/gemini-bot.en.gs | Full English version |
Each version is a stand-alone file β just copy it into Google Apps Script, set your keys, and deploy.
No external servers, no database setup β everything runs on your Google account.
| Feature | Description |
|---|---|
| π€ Natural text input | Type βbought coffee 35kβ or βgot salary 10mβ β the bot understands it |
| π§ AI parsing | Gemini detects type (income/expense), amount, note, and category |
| ποΈ Auto categorization | Food, Transport, Shopping, Bills, etc. |
| π Instant reports | /report, /reportday, /reportmonth, /reportcategory, /topcategory |
| β° Daily automation | Reminders at 20:00, daily report at 21:00 |
| πΎ Google Sheets | Secure, exportable, and fully owned by you |
| π¬ AI replies | Friendly, emotional, and human-like feedback |
| πΈ Completely free | Uses only free Google services β no hidden costs |
User β Telegram Bot β Google Apps Script β Gemini API β Google Sheets
β
Fully serverless architecture β everything executes under your Google account.
No VM, VPS, or paid hosting required.
gemini-finance-bot/
βββ README.md
βββ LICENSE
βββ src/
β βββ gemini-bot.en.gs
β βββ gemini-bot.vi.gs
βββ assets/
β βββ demo-telegram.png
β βββ sheet-sample.png
β βββ setup-guide.png
βββ .gitignore- Open @BotFather in Telegram
- Send
/newbotβ follow the steps β copy your BOT_TOKEN - (Optional) Configure your bot:
| Command | Purpose |
|---|---|
/mybots |
List your bots |
/deletebot |
Delete a bot |
/setdescription |
Set bot description |
/setabouttext |
Short βAboutβ info |
/setuserpic |
Upload bot profile picture |
Youβll need this to send reports or identify users.
- Send
/startto your bot - Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Look for
"chat":{"id":...}β thatβs your CHAT_ID
This variable defines where the bot will send automatic reminders and daily reports.
You can use:
- Your personal Chat ID (for solo tracking)
- Or a group Chat ID (for family/team usage)
In your Apps Script code, find this line:
const ADMIN_CHAT_ID = "YOUR_CHAT_ID";Replace "YOUR_CHAT_ID" with your actual Chat ID (the value you found earlier).
If itβs a group chat, the ID usually starts with a minus sign (e.g. -5037557217).
π The bot will automatically send:
- Daily reminder at 20:00 β βItβs time to log your expenses!β
- Daily summary at 21:00 β your total income & expenses of the day
- Go to Google Sheets
- Create a sheet named Transactions
- Copy the ID from its URL:
https://docs.google.com/spreadsheets/d/<SHEET_ID>/edit
- Visit Google AI Studio
- Click Create API key
- Copy your GEMINI_KEY
β οΈ Note: Gemini API has a free quota β no billing needed for personal use.
- Go to https://script.google.com
- Create a new project β name it
Gemini Finance Bot - Copy all code from:
- English β src/gemini-bot.en.gs
- Vietnamese β src/gemini-bot.vi.gs
- Replace your credentials:
const BOT_TOKEN = "YOUR_TELEGRAM_TOKEN"; const GEMINI_KEY = "YOUR_GEMINI_API_KEY"; const SHEET_ID = "YOUR_SHEET_ID"; const ADMIN_CHAT_ID = "YOUR_CHAT_ID";
- In Apps Script, click Deploy β New deployment
- Choose Web App
- Configure:
- Execute as β Me
- Who has access β Anyone
- Click Deploy β Copy your Web App URL
In your browser:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=<YOUR_SCRIPT_URL>
β You should see:
{"ok":true,"result":true,"description":"Webhook was set"}| Action | URL / Command |
|---|---|
| Check Webhook Info | https://api.telegram.org/bot<TOKEN>/getWebhookInfo |
| Delete Webhook | https://api.telegram.org/bot<TOKEN>/deleteWebhook |
| Get Updates | https://api.telegram.org/bot<TOKEN>/getUpdates |
| Send Test Message | https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<ID>&text=Hello |
In Apps Script β Triggers (β° icon), add these:
| Function | Time | Purpose |
|---|---|---|
dailyReminderJob |
20:00 | Daily βlog your expensesβ reminder |
dailyReportJob |
21:00 | Daily financial summary |
π€ User:
bought coffee 35k at Highland
π€ Bot:
β Recorded: expense 35,000β« β coffee at Highland
β βThatβs a nice treat! Enjoy your drink πβ
π
Daily Report
π° Income: 10,000,000β«
πΈ Expense: 2,750,000β«
π’ Balance: +7,250,000β«
Nice budgeting today! π―
| Tool | Purpose |
|---|---|
| Google Apps Script | Serverless backend |
| Gemini API | AI natural language understanding |
| Telegram Bot API | Chat interface |
| Google Sheets | Data storage & reporting |
See how Gemini Finance Bot works in action!
Interact naturally with the bot β record your expenses or income instantly.
All transactions are stored in your Google Sheet β organized, filterable, and exportable.
β
100% free to use
β
Runs on free-tier Google Apps Script and Gemini API
β
No external server or database required
β
Open-source under MIT License
Anyone can fork, customize, or expand this bot with zero hosting costs.
MIT License Β© 2025 Nghia Nguyen
Pull requests are welcome!
If you find bugs or have ideas β open an Issue π
If you like this project, please give it a β β it helps others find it!
π Gemini Finance Bot is 100% free, open-source, and runs entirely on Google Apps Script β no hosting, no fees, no setup hassle.
Made by Nghia Nguyen for the community π