actual-budget-telegram-bot
Telegram bot for household expense tracking with Actual Budget. No LLMs, no AI costs. Receipt scanning, auto-learning categories, tags, transfers, daily nudge.
A Telegram bot that logs household expenses by parsing chat messages like 'lunch 12.50' directly into Actual Budget, no AI API costs, fully private, with receipt scanning and natural-language spending queries.
This is a Telegram bot that connects to Actual Budget, an open-source personal finance application, so that logging household expenses becomes as simple as sending a text message. The goal is to remove the friction of manual data entry while keeping your financial data completely private and avoiding ongoing AI service costs.
The core interaction is conversational and minimal. You type something like "lunch 12.50" or "uber home 15 credit" in a shared Telegram group, and the bot parses the amount, figures out the category and account based on keywords, and logs a transaction directly into Actual Budget. For receipts, you can send a photo and Google Cloud Vision reads the total from the image. The bot does not use any large language model or AI API for categorization, it uses a keyword parser that starts with built-in mappings and learns new ones by asking you once and remembering permanently.
For queries, the bot understands natural language questions like "how much on food this month" or "what did we spend today" and returns answers from your Actual Budget data. The words "I" and "my" pull only your personal spending, while "we" and "our" pull the combined household total. Commands cover today's expenses, monthly breakdowns, category rankings compared to last month, tag-based trip or project totals, and transfers between accounts.
Automated messages send a daily spending summary at 10pm and a full weekly category breakdown every Sunday. The bot is designed for a household Telegram group with multiple members, routing each person's expenses to the right account and user record based on who sent the message.
The estimated running cost is one to two dollars per month, covering only the Actual Budget hosting. Telegram, the bot runtime on Fly.io, and Google Cloud Vision within the free tier all cost nothing. Deployment options include Fly.io, Docker, or any always-on home server. Setup requires configuring environment variables with tokens and account IDs, then customizing the keyword and account mappings to match your own budget categories. The project is MIT licensed.
Where it fits
- Log a household expense instantly by typing 'coffee 4.50' in a shared Telegram group with no app to open and no form to fill.
- Scan a receipt photo in the group chat and have the bot read the total and log the transaction automatically via Google Cloud Vision.
- Ask 'how much did we spend on food this month' and get an instant breakdown pulled from your own Actual Budget data.
- Run a fully private near-zero-cost household expense tracker that stores all financial data in your own self-hosted Actual Budget instance.