Telegram-Budget

Small profit-loss calculator via telegram bot. Made far away from home in order to control family expenses and shared budgets.

Preview

Scenario
First Usage
Adding transaction
Editing transaction
Main menu

Try it out

Telegram Demo Bot

Usage

After launching the bot, you can interact with it through Telegram. Use the following commands to manage your budget:

📌 /start - Main page

📌 /help - Show help

📌 /list - Get a list of available budgets

📌 /me - Get your user ID

📌 /history <budget name> - Get the transaction history for a budget. The budget name is optional. If no budget name is specified, the active budget will be selected. Example: /history or /history Vacation

📌 /create <budget name> - Create a new budget. The new budget will automatically become active. Example: /create Vacation or /create Weekly Budget

📌 /switch <budget name> - Switch the active budget. You can get a list of available budgets using the /list command. Example: /switch Vacation or /switch Weekly Budget

📌 /timezone <UTC offset in format 00:00> - Set your time zone. You need to specify the UTC offset. Example: /timezone 03:00 or /timezone -08:00

📌 /grant <user ID> <budget name> - Grant access to a budget to another user. The budget name is optional. If no budget name is specified, the active budget will be selected. Example: /grant 1234567890 or /grant 1234567890 Weekly Budget

📌 /revoke <user ID> <budget name> - Revoke access to a budget from another user. The budget name is optional. If no budget name is specified, the active budget will be selected. Example: /revoke 1234567890 or /revoke 1234567890 Weekly Budget

📌 /delete <budget name> - Delete a budget. All transactions will be permanently deleted. The budget name is required. Example: /delete Vacation or /delete Weekly Budget

Interaction with the Bot through the Button Interface

You can interact with the bot through the button interface on the main page. Examples of the interfaces:

• Main Page:

  

  (The "Share" and "Delete" buttons are still in development – use commands /grant and /delete for these functions)

  • The main page displays the latest transactions for the current day in the user`s timezone. The timezone can be set using the /timezone command.

• History:

  
  • Transactions in the history section are ordered from the most recent to the oldest. There is pagination.

• Switch Budget:

  
  • In the switch budget menu, you can create a new budget. Follow the bot`s instructions after clicking the "create new" button.

Adding Transactions

Any message in the format: <amount> <comment> (e.g., -10 for coffee) will be recorded as a transaction for the specified amount with the given comment in your active budget. The comment is optional.

Editing Transactions

Any transaction can be edited by modifying the sent message. In this case, all participants of the budget will receive a notification about the change. Editing the amount and comment is allowed. Only the user who created the transaction can edit it.

Installation Requirements

Before you start the installation, ensure the following requirements are met:

1. Clean Machine:

• Docker version 26.1.1 or newer
• Docker Compose version 2.27.0 or newer

2. Domain Name:

• A domain name that you own, already pointed to the target machine IP (this is necessary because the installation script will obtain certificates during the setup process).

3. API Token:

• A Telegram Bot API Token which you can get from @BotFather

Installation

1. Follow the script instructions

# Download and run the installation script
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/vorobalek/telegram-budget/main/deployment/install.sh)"

2. Run services from the directory you have chosen during the installation process

# Navigate to your installation directory and start the services
cd <path to your installation directory> && docker compose up

or

# Navigate to your installation directory and start the services with the following logs
docker compose -f <path to your installation directory>/docker-compose.yml up -d && \
docker compose -f <path to your installation directory>/docker-compose.yml logs backend -f

3. (Optional) Certificate Renewal

After three months, you'll need to renew the SSL certificate generated by the installation script. To avoid disrupting your system, the script does not override your cron job schedule. You can renew the certificate manually or add it to your cron jobs.

# Manually renew Let's Encrypt certificate
docker compose -f <path to your installation directory>/docker-compose.yml run --rm certbot certonly -d <your domain> --webroot --webroot-path /var/www/certbot/

Alternatively, you can modify your cron jobs to automate the renewal process:

# Renew Let's Encrypt certificate every month
0 0 1 * * docker compose -f <path to your installation directory>/docker-compose.yml run --rm certbot certonly -d <your domain> --webroot --webroot-path /var/www/certbot/

Build & Run manually

1. docker build -t <image nametag> .

2. docker run \
     -d \
     -e 'TELEGRAM_BOT_TOKEN=<...>' \
     -e 'TELEGRAM_WEBHOOK_SECRET=<...>' \
     -e 'DB_CONNECTION_STRING=<...>' \
     -e 'PORT=<...>' \
     -e 'DOMAIN=<...>' \ 
     -e 'AUTHORIZED_USER_IDS=<...>' \
     -e 'LOCALE=<...>' \
     -e 'DATE_FORMAT=<...>' 
     -e 'DATETIME_FORMAT=<...>' \
     -e 'SENTRY_DSN=<...>' \
     -p <machine port>:<container port> \
   --restart always \
   --name <container name> \
   <image nametag>

Environment variables (ex. is located here)

Key	Description	Required	Secret	Default
TELEGRAM_BOT_TOKEN	Telegram Bot API token.	YES	YES
TELEGRAM_WEBHOOK_SECRET	A secret token to be sent in a header X-Telegram-Bot-Api-Secret-Token in every webhook request, 1-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed. The header is useful to ensure that the request comes from a webhook set by you.	YES	YES
DB_CONNECTION_STRING	The connection string of the PostgreSQL database to connect to.	YES	YES
PORT	The number of the port for receiving requests after SSL proxy if you have.	YES	NO	–
DOMAIN	The domain to send Telegram updates to. SSL is required. The https:// prefix will be added.	YES	NO	–
AUTHORIZED_USER_IDS	A list of Telegram user IDs allowed to interact with the bot. List of numbers splitted by commas, spaces, or semicolons. Or * to authorize everyone.	YES	NO	–
LOCALE	The locale for the text responses from the bot. Only ru and en are currently available.	NO	NO	en
DATETIME_FORMAT	The format for the date and time text representation. Ex.: hh:mm tt MM/dd/yyyy or dd.MM.yyyy HH:mm.	NO	NO	hh:mm tt MM/dd/yyyy
SENTRY_DSN	The Data Source Name of a project in Sentry. Not configured by default.	NO	YES	–