Telegram Reminder Bot 🤖

A powerful Telegram bot that helps you manage reminders with support for one-time and recurring reminders. Never forget important tasks, meetings, or events again!

✨ Features

📅 Flexible Reminder Types

• One-time reminders - Set specific date/time reminders
• Weekly reminders - Recurring every week
• Yearly reminders - Recurring every year

🎯 Smart Time Parsing

• Full date/time: 2024-12-25 14:30 Buy Christmas gifts
• Date with hour only: 2024-12-25 14 Meeting (defaults to 14:00)
• Date only: 2024-12-25 Shopping (defaults to 10:00)
• Multiple date formats: DD/MM/YYYY, YYYY-MM-DD, DD-MM-YYYY

🔄 Recurring Reminders

• Weekly with time: weekly 09:00 Team meeting
• Weekly at current time: weekly Grocery shopping
• Yearly with time: yearly 18:00 Anniversary dinner
• Yearly at current time: yearly Pay subscription

📋 Reminder Management

• /list - View pending reminders
• /listall - View all reminders (including sent ones)
• /delete <ID> - Delete specific reminders by ID
• User-specific reminders (privacy protected)

⚡ Smart Delivery

• Checks every minute for due reminders
• Sends overdue reminders even if time has passed
• Automatic scheduling for recurring reminders
• Handles timezone-aware scheduling

🚀 Quick Start

Prerequisites

• Python 3.8+
• Telegram Bot Token (get from @BotFather)

Installation

1. Clone the repository

git clone <your-repo-url>
cd viberemind

2. Install dependencies

pip install -r requirements.txt

3. Configure environment

cp .env.example .env
# Edit .env and add your TELEGRAM_BOT_TOKEN

4. Run the bot

python3 viberemind.py

📖 Usage Examples

One-time Reminders

2024-12-25 14:30 Buy Christmas gifts
25/12/2024 09:00 Doctor appointment
14:30 31/12/2024 New Year party
2024-12-25 14 Team meeting
2024-12-25 Shopping

Recurring Reminders

weekly 09:00 Team standup
yearly 12:00 Birthday celebration
weekly Take out trash
yearly Renew insurance

Commands

/start - Start the bot
/help - Show detailed help
/list - View pending reminders
/listall - View all reminders
/delete 5 - Delete reminder with ID 5

🏗️ Production Deployment

Automated Deployment (Linux)

1. Run deployment script

chmod +x deploy.sh
sudo ./deploy.sh

2. Configure bot token

sudo nano /opt/reminder-bot/.env
# Add your TELEGRAM_BOT_TOKEN

3. Start the service

sudo systemctl start reminder-bot

Service Management

# Check status
sudo systemctl status reminder-bot

# View logs
sudo journalctl -u reminder-bot -f

# Restart service
sudo systemctl restart reminder-bot

# Stop service
sudo systemctl stop reminder-bot

Updates

cd /opt/reminder-bot
sudo -u reminder-bot git pull
sudo -u reminder-bot venv/bin/pip install -r requirements.txt --upgrade
sudo systemctl restart reminder-bot

🗃️ Database Schema

The bot uses SQLite with the following schema:

CREATE TABLE reminders (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    chat_id INTEGER NOT NULL,
    reminder_text TEXT NOT NULL,
    reminder_time TEXT NOT NULL,
    sent BOOLEAN DEFAULT 0,
    recurring_type TEXT DEFAULT NULL,
    next_reminder_time TEXT DEFAULT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
TELEGRAM_BOT_TOKEN	Bot token from @BotFather	✅ Yes	-
LOG_LEVEL	Logging level	❌ No	INFO
DATABASE_FILE	SQLite database path	❌ No	reminders.db

File Structure

viberemind/
├── viberemind.py          # Main bot application
├── requirements.txt       # Python dependencies
├── deploy.sh             # Production deployment script
├── .env.example          # Environment template
├── DEPLOYMENT.md         # Deployment guide
└── README.md            # This file

🛡️ Security Features

• User Isolation - Users can only see/manage their own reminders
• Input Validation - Comprehensive validation of dates and commands
• Secure Storage - Environment variables for sensitive data
• Sandboxed Execution - Runs as non-privileged user in production

🐛 Troubleshooting

Common Issues

Bot not starting:

# Check logs
sudo journalctl -u reminder-bot -n 50

# Verify token
sudo cat /opt/reminder-bot/.env

Reminders not sending:

# Check if service is running
sudo systemctl status reminder-bot

# Check database permissions
ls -la /opt/reminder-bot/reminders.db

Permission errors:

# Fix ownership
sudo chown -R reminder-bot:reminder-bot /opt/reminder-bot

📈 Development

Local Development

1. Set up development environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Create development config

cp .env.example .env
# Add your development bot token

3. Run in development mode

python3 viberemind.py

Adding New Features

1. Database changes go in init_database()
2. New commands need handlers in main()
3. Update help text in help_command()
4. Add tests for new functionality

📝 License

This project is open source. Feel free to use, modify, and distribute as needed.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

• Issues: GitHub Issues
• Questions: Create an issue with the question label
• Feature Requests: Create an issue with the enhancement label

---

Made with ❤️ for better time management