Budget Buddy Bot

Telegram Bot helping to keep your finances under control

Stack

Node.js >14.x.x
NPM >8.x.x
Typescript
Google Sheets API
Telegraf.js
Chart.js

Capabilities

This Telegram bot is intended to keep track of your personal finances distributed among various bank accounts and currencies, and provides an easy to read and understand summary of your overall budget.

It uses Google Sheets API to store and access your financial data to/from Google Spreadsheets document on your Google Drive. So, only you are in charge to manage access to this Spreadsheet document. Budget Buddy Bot does not send your financial data anywhere except for your own Google Spreadsheet document!

This bot supports having several people attached to the same budget. It means that you can configure it in a way that your wife, children or anyone will be asked for their financial data, which will be considered as part of the same budget.

Available commands

/start

Initiates pool of your bank accounts and other payment sources state.

When this command triggered, it takes from the Spreadsheet a list of payment sources belonging to you, based on your Telegram chat ID and asks you to provide exact amount of money remaining on each of your payment sources.

If you have several accounts under the same payment source in the same currency, and you want to summarise their amounts before storing them, or you want to apply any other mathematical operations to it, you can do it right in the message reply. Bot accepts any mathematical expression as a reply to his requests, so you can send him something like:

(11244.14 + 12441.12) / 2 * 10%

and bot will store the resulting value 1184.26 as an amount on the requested payment source.

/summary

On this command bot will reply with an overall summary of your budget, aggregated by currencies. It also will build a line chart based on your historical data for each currency, if you will ask him to do it, by pressing a button.

Getting Started

Create your Telegram Bot using @BotFather and note bot token
Create GCP account and obtain credentials to access Google Sheets API
Create Google Spreadsheet document, note document ID and sheet name
Fill created Spreadsheet with information about your payment sources in format of table with following columns:
- ID - unique identifier number of the payment source (ex: 1, 2, ...)
- Source - name of the payment source (ex: Wise, Citibank)
- Currency - currency identifier in ISO format (ex: EUR, USD)
- Telegram ID - Telegram chat identifier of payment source owner (ex: 122559221)
- Active - flag indicating if the account is still active (options: 1 or 0)

Clone this repo and define following environment variables on your machine (preferably using .env file):

TELEGRAM_BOT_TOKEN=<your telegram bot Token from step 1>
GOOGLE_API_CREDENTIALS=<google api credentials json from step 2>
SPREADSHEET_ID=<spreadsheet id from step 3>
SHEET_NAME=<sheet name in your spreadsheet document from step 3>
EQUIVALENCE_CURRENCY=<preferable currency to calculate total amount equivalence>

Install project dependencies with npm install
Run application in development mode using command npm run dev
Open conversation with your bot in Telegram
Hit /start command to launch your first amounts pool

Deploying on Heroku

This project is 100% compatible with Heroku. Follow these steps to deploy the application there:

If you don't have account on Heroku yet, sign up here
Login to your Heroku account and create new project

Go to Settings, click Reveal Config Vars and add following vars:

NODE_ENV=production
NODE_OPTIONS=--max_old_space_size=2560
TELEGRAM_BOT_TOKEN=<your telegram bot Token>
GOOGLE_API_CREDENTIALS=<google api credentials json>
SPREADSHEET_ID=<spreadsheet id>
SHEET_NAME=<sheet name in your spreadsheet document>
EQUIVALENCE_CURRENCY=<preferable currency to calculate total amount equivalence>

Deploy this project using Heroku CLI

aldomozhirov/budget-buddy-bot