LLM Output

Telegram Bot Scheduler

A flexible task scheduling system for Telegram bots that allows you to run scripts, commands, and functions at specified intervals.

Features

• Schedule tasks using human-readable time expressions
• Run Python scripts, shell commands, or custom functions
• Configure all tasks in a single JSON file
• Receive notifications on task completion or errors
• Manage tasks via command line or Telegram bot commands
• Simple configuration with no coding required for basic tasks

Installation

1. Clone this repository:

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

2. Install dependencies:

   pip install python-telegram-bot python-dotenv schedule
   

3. Create a .env file with your Telegram bot token:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   

Configuration

All scheduled tasks are configured in the config.json file under the scheduled_tasks section:

{
    "admin_users": [123456789],
    "notification_users": [123456789],
    "scheduled_tasks": [
        {
            "name": "daily_report",
            "schedule": "every day at 9:00",
            "task_type": "script",
            "script_path": "scripts/daily_report.py",
            "enabled": true,
            "notify_on_completion": true,
            "notify_on_error": true,
            "timeout": 300
        }
    ]
}

Task Properties

• name: A unique identifier for the task
• schedule: When the task should run (e.g., "every day at 9:00")
• task_type: Type of task ("script" or "command")
• script_path: Path to a Python script (for "script" type)
• command: Shell command to execute (for "command" type)
• enabled: Whether the task is active
• notify_on_completion: Whether to send a notification when the task completes successfully
• notify_on_error: Whether to send a notification when the task fails
• timeout: Maximum execution time in seconds

Schedule Format Examples

• every minute - Run every minute
• every hour - Run every hour
• every day at 9:00 - Run daily at 9:00 AM
• every monday at 3:00 - Run weekly on Mondays at 3:00 AM
• every month at 9:00 - Run on the first day of each month at 9:00 AM

Usage

Starting the Bot

Run the main script to start the bot and scheduler:

python main.py

Managing Tasks via Command Line

You can manage tasks using the manage_tasks.py script:

# List all tasks
python manage_tasks.py list

# Show details of a specific task
python manage_tasks.py show daily_report

# Run a task immediately
python manage_tasks.py run daily_report

# Enable a task
python manage_tasks.py enable weekly_backup

# Disable a task
python manage_tasks.py disable hourly_check

# Reload tasks from config.json after making changes
python manage_tasks.py reload

Telegram Bot Commands

If you're an admin user, you can manage tasks directly through the Telegram bot:

/tasks - List all scheduled tasks
/task_status daily_report - Show details of a specific task
/enable_task weekly_backup - Enable a task
/disable_task hourly_check - Disable a task

Example Tasks

Daily Report

{
    "name": "daily_report",
    "schedule": "every day at 9:00",
    "task_type": "script",
    "script_path": "scripts/daily_report.py",
    "enabled": true,
    "notify_on_completion": true,
    "notify_on_error": true,
    "timeout": 300
}

Hourly System Check

{
    "name": "hourly_check",
    "schedule": "every hour",
    "task_type": "command",
    "command": "python scripts/hourly_check.py",
    "enabled": true,
    "notify_on_completion": false,
    "notify_on_error": true,
    "timeout": 60
}

Weekly Backup

{
    "name": "weekly_backup",
    "schedule": "every monday at 3:00",
    "task_type": "command",
    "command": "bash scripts/backup.sh",
    "enabled": true,
    "notify_on_completion": true,
    "notify_on_error": true,
    "timeout": 1800
}

Creating Custom Tasks

Python Script Tasks

1. Create a new Python script in the scripts/ directory:

#!/usr/bin/env python3
import os
import sys
from notify import NotificationClient

# Add parent directory to path so we can import from the main project
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

def main():
    # Your task logic here
    result = "Task completed successfully!"
    
    # Send notification
    client = NotificationClient()
    client.broadcast_notification(result)
    return 0

if __name__ == "__main__":
    sys.exit(main())

2. Make it executable:

chmod +x scripts/your_script.py

3. Add the task to config.json:

{
    "name": "your_custom_task",
    "schedule": "every day at 12:00",
    "task_type": "script",
    "script_path": "scripts/your_script.py",
    "enabled": true,
    "notify_on_completion": true,
    "notify_on_error": true,
    "timeout": 300
}

Shell Command Tasks

Add a command task to config.json:

{
    "name": "disk_cleanup",
    "schedule": "every sunday at 2:00",
    "task_type": "command",
    "command": "find /tmp -type f -atime +7 -delete",
    "enabled": true,
    "notify_on_completion": true,
    "notify_on_error": true,
    "timeout": 600
}

Example: Disk Space Monitor

Let's create a task that checks disk space and sends an alert if it's low:

1. Create a script in scripts/check_disk_space.py:

#!/usr/bin/env python3
import os
import sys
import subprocess

# Add parent directory to path so we can import from the main project
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

from notify import NotificationClient

def main():
    # Get disk usage
    df = subprocess.check_output(['df', '-h', '/']).decode('utf-8')
    lines = df.strip().split('\n')
    usage_line = lines[1]
    parts = usage_line.split()
    usage_percent = int(parts[4].strip('%'))
    
    # Send alert if disk usage is above 80%
    if usage_percent > 80:
        client = NotificationClient()
        message = f"⚠️ WARNING: Disk usage is at {usage_percent}%!\n{usage_line}"
        client.broadcast_notification(message)
        print(f"Alert sent: {message}")
    else:
        print(f"Disk usage is normal: {usage_percent}%")
    
    return 0

if __name__ == "__main__":
    sys.exit(main())

2. Make it executable:

chmod +x scripts/check_disk_space.py

3. Add to config.json:

{
    "name": "disk_space_check",
    "schedule": "every day at 8:00",
    "task_type": "script",
    "script_path": "scripts/check_disk_space.py",
    "enabled": true,
    "notify_on_completion": false,
    "notify_on_error": true,
    "timeout": 60
}

4. Reload the tasks:

python manage_tasks.py reload

Troubleshooting

• If a task isn't running, check if it's enabled in config.json
• Verify the schedule format is correct
• Check the log file (telegram_bot.log) for errors
• Try running the task manually with python manage_tasks.py run task_name
• Make sure scripts have the correct permissions (chmod +x scripts/your_script.py)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.