Telegram Accounter Bot

A production-ready Python bot that tracks income and expenses per Telegram user via text or voice messages. Voice notes are transcribed with OpenAI Whisper, and OpenAI GPT categorizes statements into structured ledger entries.

Features

• User-specific ledgers stored in SQLite with automatic migrations
• Voice and text input, both understood via OpenAI
• Natural-language parsing that supports multiple statements per message
• Simple keyword-based categories plus free-form notes
• Credit-based payment system to cover OpenAI API costs
• Automatic credit deduction per message
• Payment history tracking and balance management
• Detailed comments across the codebase for learning purposes

Prerequisites

• Python 3.11+
• ffmpeg installed on your system (Telegram voice notes are OGG/OPUS)
• A Telegram bot token from @BotFather
• An OpenAI API key with access to GPT-4o-mini and Whisper

Setup

1. Create a virtual environment:

   cd /Users/danilkarpov/telegram_accounter
   python3 -m venv .venv
   source .venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Copy the environment template and fill in secrets:

   cp .env .env

4. Run the bot:

   python src/bot.py

Environment variables

• BOT_TOKEN: Telegram bot token
• OPENAI_API_KEY: OpenAI key for text + audio
• OPENAI_MODEL_CHAT: Chat completion model (default gpt-4o-mini)
• OPENAI_MODEL_AUDIO: Audio transcription model (default whisper-1)
• DATABASE_PATH: Optional custom path to SQLite file
• ADMIN_USER_IDS: Comma-separated list of Telegram user IDs for admin commands (optional)

Workflow

1. User sends text or voice message
2. Bot checks user's credit balance (insufficient balance blocks processing)
3. Bot downloads (and if needed, transcodes) the message
4. OpenAI converts voice to text and extracts structured transactions
5. Credits are deducted based on API usage (text: ~$0.0002, voice: ~$0.0062)
6. Entries (income/expense) are persisted with timestamps per user
7. /summary command shows totals for today, this week, and all time

Commands

• /start - Welcome message and instructions
• /summary - View expense/income totals (today, week, lifetime)
• /balance - Check your credit balance and costs
• /buy - Purchase credits (payment integration needed)
• /add_credits <user_id> <amount> - Admin command to manually add credits

Testing ideas

• Send combined statements like "food 15, uber 40"
• Try malformed inputs to see fallback responses
• Use /summary after adding entries to verify balances

Payment System

This bot uses a credit-based payment system to cover OpenAI API costs. See README_PAYMENTS.md for:

• How the credit system works
• Setting up Telegram Payments
• Manual credit addition for testing
• Cost configuration

Quick start for testing:

1. Add your Telegram user ID to ADMIN_USER_IDS in .env
2. Use /add_credits <your_user_id> 10.0 to add test credits
3. Send messages and watch credits deduct automatically

Concepts used

• Async I/O with asyncio
• Webhook-style polling using python-telegram-bot
• Data validation with Pydantic models
• SQLite persistence
• Working with external APIs (Telegram, OpenAI)
• Natural language processing prompts
• Credit management and payment processing
• Database transactions for atomic operations