explaingit

bbharathbala/actual-budget-telegram-bot

★ 13JavaScriptAudience · generalComplexity · 3/5LicenseSetup · moderate

TLDR

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.

Mindmap

mindmap
  root((actual-budget-telegram-bot))
    What it does
      Logs expenses from chat
      Queries spending history
      Daily and weekly summaries
    Features
      Keyword categorization
      Receipt photo scanning
      Multi-member household
    Tech Stack
      JavaScript
      Telegram API
      Google Cloud Vision
    Hosting
      Fly.io
      Docker
      Home server
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

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.

USE CASE 2

Scan a receipt photo in the group chat and have the bot read the total and log the transaction automatically via Google Cloud Vision.

USE CASE 3

Ask 'how much did we spend on food this month' and get an instant breakdown pulled from your own Actual Budget data.

USE CASE 4

Run a fully private near-zero-cost household expense tracker that stores all financial data in your own self-hosted Actual Budget instance.

Tech stack

JavaScriptTelegram APIGoogle Cloud VisionDockerFly.ioActual Budget

Getting it running

Difficulty · moderate Time to first run · 30min

Requires a running Actual Budget server instance, a Telegram bot token, and a Google Cloud Vision API key for receipt scanning.

Use freely for any purpose including commercial use as long as you keep the copyright notice.

In plain English

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.

Copy-paste prompts

Prompt 1
I set up actual-budget-telegram-bot in my household Telegram group. Help me configure the keyword-to-category mappings so 'uber', 'lyft', and 'taxi' all map to Transport and debit from the Checking account.
Prompt 2
I sent a receipt photo to the bot but it didn't log the transaction. Walk me through debugging the Google Cloud Vision setup and verifying the environment variables are set correctly.
Prompt 3
Write a Telegram message I can send to actual-budget-telegram-bot to see a ranked list of our household's top spending categories this month compared to last month.
Prompt 4
Deploy actual-budget-telegram-bot to Fly.io using Docker. List the environment variables I need, explain where to find the Actual Budget server token, and show the fly.toml config I need.
Open on GitHub → Explain another repo

← bbharathbala on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.