🏆 Telegram Accountability Challenge Bot

The Ultimate Accountability Bot - Track habits, build streaks, and achieve your goals!

🚀 Features

📊 Core Accountability System

• Weekday-only tracking (Monday-Friday focus)
• Empty day logging support (/log without activities still counts!)
• Double letter activities (KK40, MM15, etc.)
• Real-time message editing with automatic stats updates
• Smart private messaging with group chat fallback

🎮 Advanced Gamification

• 6-tier level system (Beginner → Legend)
• Achievement badges for streaks, milestones, and consistency
• Monthly challenges with special recognition
• Streak tracking with consecutive day counting
• Personal goals with weekly targets and progress tracking

💡 Power User Features

• Bulk editing (/edit yesterday M20 S30)
• Activity templates for common combinations
• Multi-week history with detailed analytics
• Data export functionality
• Custom activity definitions
• Calendar view with visual activity indicators

🤖 Smart Automation

• Sunday 18:00: Weekly celebration with leader boards
• Sunday evening: Private weekly breakdowns
• Weekdays 21:00: Optional daily reminders
• Intelligent help system for unrecognized messages

📚 Quick Start

Prerequisites

• Python 3.8+
• A Telegram Bot Token (Get one from @BotFather)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/telegram-accountability-bot.git
   cd telegram-accountability-bot

2. Install dependencies

   pip install python-telegram-bot pytz

3. Set up your bot token

   # Create token file
   mkdir -p ~/bin/telegram_bot_robert
   echo "YOUR_BOT_TOKEN_HERE" > ~/bin/telegram_bot_robert/token

4. Run the bot

   python3 telegram_bot_robert.py

🎯 Usage Guide

Core Commands

/log M20 S30        # Log 20 min meditation, 30 min sport
/log KK40           # Log 40 units of kickboxing (double letters supported)
/log                # Log empty day (counts for attendance!)
/status             # View current week progress
/help               # Complete command guide

Analytics & Progress

/history            # Last 4 weeks of activity
/history 8          # Last 8 weeks
/analytics          # Personal insights and trends
/level              # Check level and achievements
/calendar           # Visual monthly calendar

Goals & Customization

/goals              # View current weekly goals
/goals set M 100    # Set 100 units of M per week
/define M Meditation # Define what activity codes mean
/reminder on/off    # Toggle 21:00 daily reminders

Power Features

/edit yesterday M30 S20     # Edit past activities
/template save morning M20 S30  # Save activity templates
/template use morning       # Use saved template
/export                     # Export your data

🏗️ Architecture

• Database: JSON-based local storage with automatic backups
• Timezone: Configurable (default: Europe/Helsinki)
• Scheduling: Built-in job queue for automated messages
• Error Handling: Comprehensive logging and graceful recovery

🎮 Gamification System

Level Progression

• Beginner 🌱 (0-49 points)
• Explorer 🚀 (50-149 points)
• Achiever ⭐ (150-299 points)
• Champion 🏆 (300-499 points)
• Master 👑 (500-749 points)
• Legend 🌟 (750+ points)

Achievements

• Streak Badges: 7, 14, 30+ day streaks
• Unit Milestones: 100, 500, 1000+ total units
• Monthly Awards: Consistency, Variety, Powerhouse
• Special Recognition: Early Bird, First Month Warrior

📅 Automation Schedule

• Sunday 18:00: Weekly celebration with stats and leader board
• Sunday evening: Individual weekly breakdown (private message)
• Monday 08:00: New week motivation message
• Weekdays 21:00: Daily reminders (if enabled and not logged)

🛠️ Configuration

Token Setup

Update the TOKEN_FILE_PATH in the script:

TOKEN_FILE_PATH = "/path/to/your/token/file"

Timezone

TIMEZONE = pytz.timezone('Your/Timezone')  # e.g., 'America/New_York'

Admin Features

Update admin username for backup commands:

if user.username != "your_admin_username":

📁 File Structure

telegram_bot_robert/
├── telegram_bot_robert.py           # Main bot file
├── accountability_db.json          # Database (auto-created)
├── backup_YYYYMMDD_HHMMSS.json    # Automatic backups
├── README.md                       # This file
├── requirements.txt                # Python dependencies
├── DEPLOYMENT_GUIDE.md            # Detailed deployment guide
├── IMPLEMENTATION_STATUS.md       # Development progress
└── FEATURE_CHECKLIST.md           # Feature selection guide

🐛 Troubleshooting

Common Issues

1. "Token file not found"

   • Ensure the token file exists and contains only your bot token
   • Check file permissions

2. "Database corruption"

   • Bot automatically restores from backup
   • Manual restore: copy a backup file to accountability_db.json

3. "Private messages not working"

   • Users must start a conversation with the bot first
   • Bot gracefully falls back to group messages

Logging

Logs are written to console with INFO level. For debugging:

logging.basicConfig(level=logging.DEBUG)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📊 Database Schema

{
  "users": {
    "user_id": {
      "username": "string",
      "joined_date": "ISO_date",
      "activity_totals": {"M": 100, "S": 200},
      "current_streak": 5,
      "longest_streak": 12,
      "achievements": ["streak_7", "total_100"],
      "goals": {"M": 100},
      "templates": {"morning": "M20 S30"}
    }
  },
  "weekly_logs": {
    "2024-W01": {
      "user_id": {
        "logs": {"2024-1-1": {"M": 20, "S": 30}},
        "missed_days": []
      }
    }
  }
}

🔒 Privacy & Security

• All data stored locally in JSON format
• No external API calls except to Telegram
• User data never shared or transmitted
• Automatic backup system with rotation
• Graceful error handling prevents data loss

📄 License

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

🙏 Acknowledgments

• Built with python-telegram-bot
• Timezone handling by pytz
• Inspired by the accountability and habit-tracking community

📞 Support

Need help? Check out:

• Deployment Guide for setup instructions
• Implementation Status for feature details
• Open an issue for bugs or feature requests

---

Made with ❤️ for the accountability community

"Small steps every day lead to big changes every year!" 🌟