Assignment Reminder Bot

This is a Telegram bot that manages weekly assignments for a specific group.

Features

• Connects to a specific Telegram group
• Sends weekly assignment reminders
• Tracks assignment confirmations via inline keyboards
• Sends reminder messages for unconfirmed assignments (after 2 days)
• Requests volunteers when assignments aren't confirmed in time (after 5 days)
• Celebrates when all assignments are confirmed
• Rotates assignments among group members

Setup

1. Create a virtual environment and install dependencies:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Create a Telegram bot:

   • Talk to @BotFather on Telegram
   • Use the /newbot command to create a new bot
   • Note the bot token that @BotFather provides

3. Find your group's chat ID:

   • Add the bot to your Telegram group
   • Send a message to the group
   • Check the bot's API updates to find the chat ID

4. Configure the bot:

   • Copy the configuration template:

     cp config.ini.example config.ini
     

   • Edit config.ini with your actual credentials:
     • TELEGRAM_BOT_TOKEN: Your Telegram bot token from @BotFather
     • TARGET_GROUP_ID: The chat ID of your target group

5. Run the bot:

   python src/bot.py
   

How It Works

1. The bot sends a weekly reminder message with inline buttons for each assignment
2. Each assigned person confirms their assignment by clicking the button
3. If someone doesn't confirm within 2 days, the bot sends a reminder
4. If someone doesn't confirm within 5 days, the bot requests volunteers for that assignment
5. When all assignments are confirmed, the bot sends a celebration message

Configuration

The bot can be configured using either:

1. Environment variables
2. A config.ini file

The following variables are required:

• TELEGRAM_BOT_TOKEN: Your Telegram bot token
• TARGET_GROUP_ID: The chat ID of the target group

Requirements

• Python 3.7+
• python-telegram-bot
• schedule
• python-dotenv

Development

To run the bot with the virtual environment:

source venv/bin/activate  # On Windows: venv\Scripts\activate
python src/bot.py

To deactivate the virtual environment:

deactivate

Testing

The project includes unit tests to verify the functionality. To run the tests:

1. Make sure you're in the virtual environment:

   source venv/bin/activate
   

2. Run all tests:

   python -m pytest tests/
   

3. Run tests with coverage report:

   python -m pytest tests/ --cov=src --cov-report=html
   

4. Run a specific test file:

   python -m pytest tests/test_bot.py
   

Documentation

The code is documented using standard Python docstrings that follow the Google Python Style Guide. To generate HTML documentation:

1. Build the documentation:

   source venv/bin/activate
   cd docs
   make html
   

2. Open the generated documentation:

   open build/html/index.html
   

Production Deployment

For production deployment, you would:

1. Change the scheduler to run weekly instead of every minute
2. Implement proper user management from the Telegram group
3. Add database storage instead of JSON files
4. Add proper error handling and logging
5. Deploy to a server or cloud platform

Future Enhancements

• Integration with HashiCorp Vault for credential management
• Database storage for assignments and user data
• Web interface for managing assignments
• Email notifications as a backup
• Support for multiple groups