8000 GitHub - phuchuu-gif/gemini-finance-bot: AI-powered personal finance tracker for Telegram using Google Apps Script + Gemini API + Google Sheets. Β· GitHub
[go: up one dir, main page]

Skip to content

About

AI-powered personal finance tracker for Telegram using Google Apps Script + Gemini API + Google Sheets.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ’° Gemini Finance Bot

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 Versions

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.


✨ Features

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

🧠 Architecture

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.


πŸ“ Folder Structure

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

πŸš€ How to Deploy

1️⃣ Create a Telegram Bot

  1. Open @BotFather in Telegram
  2. Send /newbot β†’ follow the steps β†’ copy your BOT_TOKEN
  3. (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

2️⃣ Get Your Chat ID

You’ll need this to send reports or identify users.

  1. Send /start to your bot
  2. Visit:
    https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
    
  3. Look for "chat":{"id":...} β†’ that’s your CHAT_ID

2.1 Set Your ADMIN_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

3️⃣ Create a Google Sheet

  1. Go to Google Sheets
  2. Create a sheet named Transactions
  3. Copy the ID from its URL:
    https://docs.google.com/spreadsheets/d/<SHEET_ID>/edit
    

4️⃣ Get a Gemini API Key

  1. Visit Google AI Studio
  2. Click Create API key
  3. Copy your GEMINI_KEY

⚠️ Note: Gemini API has a free quota β€” no billing needed for personal use.


5️⃣ Create a Google Apps Script Project

  1. Go to https://script.google.com
  2. Create a new project β†’ name it Gemini Finance Bot
  3. Copy all code from:
  4. 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";

6️⃣ Deploy as a Web App

  1. In Apps Script, click Deploy β†’ New deployment
  2. Choose Web App
  3. Configure:
    • Execute as β†’ Me
    • Who has access β†’ Anyone
  4. Click Deploy β†’ Copy your Web App URL

7️⃣ Connect Telegram Webhook

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"}

πŸ”§ Telegram API Cheat Sheet

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

8️⃣ Add Daily Triggers (Reminders & Reports)

In Apps Script β†’ Triggers (⏰ icon), add these:

Function Time Purpose
dailyReminderJob 20:00 Daily β€œlog your expenses” reminder
dailyReportJob 21:00 Daily financial summary

πŸ’¬ Example Conversation

πŸ‘€ User:
bought coffee 35k at Highland

πŸ€– Bot:
βœ… Recorded: expense 35,000β‚« β€” coffee at Highland
β˜• β€œThat’s a nice treat! Enjoy your drink πŸ˜‹β€


πŸ“Š Example Report

πŸ“… Daily Report
πŸ’° Income: 10,000,000β‚«
πŸ’Έ Expense: 2,750,000β‚«
🟒 Balance: +7,250,000β‚«

Nice budgeting today! 🎯

🧰 Tech Stack

Tool Purpose
Google Apps Script Serverless backend
Gemini API AI natural language understanding
Telegram Bot API Chat interface
Google Sheets Data storage & reporting

πŸ“Έ Demo & Screenshots

See how Gemini Finance Bot works in action!

Telegram demo conversation Telegram demo conversation
Interact naturally with the bot β€” record your expenses or income instantly.

Google Sheet Transactions sample
All transactions are stored in your Google Sheet β€” organized, filterable, and exportable.


πŸ’Έ Free & Open Source

βœ… 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.


🧾 License

MIT License Β© 2025 Nghia Nguyen


🀝 Contributing

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 🌏

About

AI-powered personal finance tracker for Telegram using Google Apps Script + Gemini API + Google Sheets.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0