LendMoneyBot

A Telegram bot for tracking personal debts and loans between users. The bot leverages Telegram's contact sharing feature to easily add lenders and manage debt records.

Problem / Purpose

Keeping track of informal loans between friends, family, or colleagues can be challenging. LendMoneyBot solves this by providing:

• A simple interface within Telegram to record who you owe money to
• Real-time debt tracking with the ability to increase or decrease amounts
• Quick access to your debt summary via inline queries
• Persistent storage so your data is always available

Project Structure

lendmoneybot/
├── pom.xml                                    # Maven build configuration
├── src/
│   └── main/
│       └── java/
│           └── com/
│               └── telegram/
│                   ├── Main.java              # Application entry point
│                   ├── LendMoneyBot.java      # Core bot logic and command handling
│                   ├── LendUser.java          # User data model
│                   ├── PersistenceService.java # Database operations
│                   └── BuildVars.java         # Configuration constants
├── .gitignore
├── LICENSE
└── README.md

Requirements

Software

• Java 8 JDK or higher
• Maven 3.0+
• MariaDB server
• Redis server

Telegram Bot Setup

1. Create a new bot via @BotFather on Telegram
2. Obtain your bot token and username
3. Configure inline mode via BotFather if you want to use inline queries

Installation

1. Clone the Repository

git clone https://github.com/your-username/lendmoneybot.git
cd lendmoneybot

2. Database Setup

Create the required MariaDB tables:

CREATE TABLE user (
    telegram_id INT PRIMARY KEY,
    username VARCHAR(255),
    first_name VARCHAR(255),
    last_name VARCHAR(255)
);

CREATE TABLE lending (
    lender_id INT,
    borrower_id INT,
    sum DOUBLE,
    PRIMARY KEY (lender_id, borrower_id),
    FOREIGN KEY (lender_id) REFERENCES user(telegram_id),
    FOREIGN KEY (borrower_id) REFERENCES user(telegram_id)
);

3. Configuration

Edit src/main/java/com/telegram/BuildVars.java with your credentials:

class BuildVars {
    static final String BOT_NAME = "your_bot_username";
    static final String BOT_API_KEY = "your_bot_token";

    private static final String DATABASE_USER = "your_db_user";
    private static final String DATABASE_PASSWORD = "your_db_password";
    private static final String DATABASE_NAME = "your_db_name";
    private static final Integer DATABASE_PORT = 3306;
    // ...
}

4. Build and Run

# Build and run
mvn package exec:java

# Or build a standalone JAR
mvn package
java -jar target/telegram.bots-1.0-SNAPSHOT-jar-with-dependencies.jar

Usage

Bot Commands

Command	Description
/start	Initialize the bot and display the keyboard
/add	Add a new lender by sharing their Telegram contact
/show	Display all your current debts
/edit	Modify an existing debt (increase or decrease)
/help	Show available commands
/about	Display bot information

Adding a Lender

1. Send /add or tap "Add lender" on the keyboard
2. Share a contact from your Telegram contacts
3. Enter the amount you owe

Example interaction:

User: /add
Bot: Send lender contact to this bot to proceed.
User: [shares contact "John Doe"]
Bot: Got it. How much do you own to this person? :)
User: 150
Bot: Successfully added lender. You can now track info by using /show command

Viewing Debts

User: /show
Bot: John Doe -> ₴150 pending.
     Jane Smith -> ₴75 pending.

Editing a Debt

1. Send /edit or tap "Edit lender info"
2. Select the lender by number
3. Choose to increase or decrease the amount
4. Enter the amount to add or subtract

Example interaction:

User: /edit
Bot: Select user:
     /1 John Doe -> ₴150 pending.
User: /1
Bot: /1 Increase debt or /2 decrease?
User: Decrease
Bot: Enter sum to decrease
User: 50
Bot: Successfully edited user! :)

Inline Mode

Type @your_bot_username me in any chat to quickly share your debt information.

Implementation Details

Architecture

The bot uses a long polling mechanism via the TelegramBots library to receive updates. User interactions are processed through a state machine pattern with the following states:

• Idle: Default state, waiting for commands
• Add Lender: Waiting for contact share
• Add Sum: Waiting for debt amount input
• Edit User Start: Waiting for lender selection
• Edit User Action: Waiting for increase/decrease choice
• Edit User Sum: Waiting for edit amount input

Data Flow

1. User sends a message to the bot
2. LendMoneyBot.onUpdateReceived() processes the update
3. State flags determine the expected input type
4. PersistenceService handles database operations
5. Redis temporarily stores intermediate data (contact info during add process)
6. Response is sent back to the user

Database Schema

• user: Stores Telegram user information (id, username, first/last name)
• lending: Maps borrower-lender relationships with the debt amount

Class/Function Documentation

Classes

Class	Description
Main	Application entry point; initializes the Telegram API and registers the bot
LendMoneyBot	Core bot class extending TelegramLongPollingBot; handles all user interactions and commands
LendUser	Data model representing a lender with userId, name, and debt sum
PersistenceService	Database access layer; manages all MariaDB operations
BuildVars	Configuration class containing bot credentials and database connection settings

Key Methods

Class	Method	Description
LendMoneyBot	onUpdateReceived(Update)	Main handler for all incoming Telegram updates
LendMoneyBot	getBotUsername()	Returns the bot username from configuration
LendMoneyBot	getBotToken()	Returns the bot API token from configuration
PersistenceService	addLenderTo(Contact, double, Integer)	Adds a new lender and creates debt record
PersistenceService	getAllUsersInformation(User)	Retrieves all lenders associated with a user
PersistenceService	editUser(int, int, boolean, double)	Modifies debt amount; deletes record if balance reaches zero
PersistenceService	findInlineInfoWithUser(User)	Returns debt info formatted for inline query results
PersistenceService	getAmountOfUsers(User)	Returns count of lenders for a user

Dependencies

Dependency	Version	Purpose
TelegramBots	2.4.4.5	Telegram Bot API wrapper
Log4j	1.2.17	Logging framework
Lombok	1.16.16	Boilerplate code reduction
MariaDB Java Client	2.0.3	Database connectivity
Commons DbUtils	1.7	JDBC utility library
Jedis	2.9.0	Redis client for Java
Gson	2.8.1	JSON serialization/deserialization

License

This project is licensed under the MIT License - see the LICENSE file for details.