A Telegram bot for tracking study sessions in groups with Persian language support. Track your study time, compete with friends, and view detailed statistics!
- 📊 Study Time Tracking: Start, pause, resume, and end study sessions
- 🏆 Leaderboards: Daily, weekly, and monthly rankings
- 📈 Live Updates: Real-time study statistics that update automatically
- 👤 Personal Stats: View your individual study progress
- 📅 Persian Calendar: Full Jalali (Shamsi) calendar support
- 🔒 User-Specific Controls: Each user can only interact with their own commands
- 🌐 Group Support: Perfect for study groups and classes
- 💾 Persistent Data: All data stored in JSON format
- Python 3.8 or higher
- A Telegram Bot Token from @BotFather
- A Telegram group to use the bot in
cd /path/to/study-botpython3 -m venv .venv
source .venv/bin/activate # On Linux/Mac
# OR
.venv\Scripts\activate # On Windowspip install -r requirements.txtCreate a .env file in the project root:
cp .env.example .env # If example exists
# OR create manually:
nano .envAdd the following configuration:
BOT_TOKEN=your_bot_token_here
ALLOWED_GROUP_ID=your_group_id_here
UPDATE_INTERVAL=30Configuration Details:
BOT_TOKEN: Get this from @BotFatherALLOWED_GROUP_ID: Your Telegram group ID (use 0 to allow all groups)UPDATE_INTERVAL: Seconds between live statistics updates (default: 30)
Finding Your Group ID:
- Add the bot to your group
- Send any message in the group
- Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Look for
"chat":{"id":-1001234567890- that's your group ID
python3 bot.pyThe bot includes an auto-restart script that will automatically restart the bot if it stops:
./start.shThis script:
- ✅ Runs in an infinite loop
- ✅ Automatically restarts the bot if it crashes
- ✅ Shows restart count and timestamps
- ✅ Waits 5 seconds between restarts
- ✅ Can only be stopped with Ctrl+C
| Command | Description |
|---|---|
/start |
Show main menu with all options |
/details |
Display live study statistics (auto-updates) |
/stats |
Show complete daily statistics report |
When you use /start, you'll get an interactive menu:
▶️ شروع مطالعه - Start a new study session- ⏸ توقف موقت - Pause your current session
▶️ ادامه دادن - Resume after a pause- ⏹ پایان و ذخیره - End and save your session
- 📊 آمار من - View your personal statistics
- 📈 آمار گروه - View group statistics
- 🏆 رتبهبندیها - Access leaderboard menu
- ❓ راهنما - Show help and instructions
- 🏆 امروز - Today's top students
- 📅 هفتگی - Weekly leaderboard
- 📆 ماهانه - Monthly leaderboard
- Each user can only interact with their own
/startmenu buttons - If someone tries to use another person's buttons, they'll see an access denied message
- Group-specific access control (optional)
- No authentication required - just add users to your group!
study-bot/
├── bot.py # Main bot code (SQLite version)
├── database.py # Database layer
├── start.sh # Auto-restart script
├── requirements.txt # Python dependencies
├── .env # Configuration file
├── .env.example # Configuration template
│
├── data/ # Data directory
│ └── study_bot.db # SQLite database
│
├── backups/ # Backup files
├── scripts/ # Utility scripts
├── docs/ # Documentation
└── README.md # This file
📖 See PROJECT_STRUCTURE.md for detailed structure.
To run the bot permanently on a server, you can create a systemd service:
- Create service file:
sudo nano /etc/systemd/system/study-bot.service- Add this configuration:
[Unit]
Description=Study Bot Telegram Bot
After=network.target
[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/study-bot
ExecStart=/path/to/study-bot/start.sh
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target- Enable and start:
sudo systemctl enable study-bot
sudo systemctl start study-bot
sudo systemctl status study-bot- ✅ Fixed! The bot now includes:
- Error handlers to catch and log errors
- Automatic connection retry on network issues
- Robust timeout configurations
- Use
./start.shfor automatic restarts
- Check if bot is running:
ps aux | grep bot.py - Verify bot token in
.envfile - Ensure bot is admin in the group
- Check console for error messages
- Make sure
start.shis executable:chmod +x start.sh - Check file permissions:
ls -l
- The
data.jsonfile is created automatically - Backup regularly:
cp data.json data.json.backup - If corrupted, delete it (bot will create new one)
All data is stored in SQLite database (study_bot.db) with the following structure:
- users: User information and active sessions
- daily_stats: Daily study time per user
- weekly_stats: Weekly statistics
- monthly_stats: Monthly statistics
- details_messages: Live message tracking
Benefits of SQLite:
- ✅ No data corruption
- ✅ ACID transactions (atomic, consistent, isolated, durable)
- ✅ Better performance
- ✅ Concurrent access support
- ✅ Easy backup (just copy study_bot.db)
Backup your data regularly!
cp data/study_bot.db backups/study_bot_$(date +%Y%m%d).db- Minimum session time: 1 minute
- Automatic session expiration at midnight
- Pause and resume functionality
- Real-time elapsed time calculation
- Live updating group dashboard
- Personal progress tracking
- Comprehensive ranking systems
- Persian calendar integration
- Average study time calculations
- Details message updates every 30 seconds (configurable)
- Daily reports at midnight (Iran timezone)
- Automatic username synchronization
Feel free to fork, modify, and improve this bot!
This project is open source and available for personal and educational use.
If you encounter issues:
- Check the troubleshooting section
- Review console error messages
- Ensure all dependencies are installed
- Verify your
.envconfiguration
Made with ❤️ for students who want to track their study time and compete with friends!
🎯 Good luck with your studies! 📚✨