PeppyWebMonitorBot 🤖

PeppyWebMonitorBot is an intelligent Telegram bot that monitors websites for content changes and sends real-time notifications. Stay informed about updates on your favorite websites without manual checking - let the bot do the work for you!

📋 Table of Contents

• Features
• How It Works
• Prerequisites
• Installation
• Configuration
• Usage
  • Available Commands
  • Usage Examples
• Deployment
• Project Structure
• Contributing
• License

✨ Features

• 🔔 Real-Time Monitoring: Automatically checks websites every 60 seconds for content changes
• 📱 Telegram Integration: Receive instant notifications directly in your Telegram chat
• 👥 Multi-User Support: Control access with allowed user IDs for security
• 📊 User Management: Each user can monitor up to 5 URLs simultaneously
• 💾 Persistent Storage: SQLite database stores all monitoring tasks and user data
• 🔒 Secure Configuration: Environment-based configuration for sensitive data
• ⚡ Asynchronous Architecture: Built with asyncio for efficient concurrent monitoring
• 🎯 Interactive Commands: Easy-to-use command interface with inline keyboard support
• ✅ URL Validation: Automatic validation of URLs before monitoring starts

🔍 How It Works

PeppyWebMonitorBot operates by:

1. Accepting URLs from authorized users via Telegram commands
2. Creating Background Tasks that periodically fetch website content
3. Comparing Content between checks to detect changes
4. Sending Notifications to users when changes are detected
5. Managing Tasks through an SQLite database for persistence

The bot uses asynchronous programming to handle multiple monitoring tasks simultaneously without blocking, ensuring efficient resource usage and responsive user interactions.

📦 Prerequisites

• Python 3.8+ installed on your system
• A Telegram Bot Token (obtain from @BotFather)
• Your Telegram User ID (obtain from @userinfobot)
• Basic knowledge of Python and command-line operations

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/peppy-webmonitor-bot-2024.git
cd peppy-webmonitor-bot-2024

2. Create a Virtual Environment (Recommended)

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux/macOS
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

The following packages will be installed:

• python-telegram-bot==21.6 - Telegram Bot API wrapper
• httpx==0.27.2 - Async HTTP client for fetching web content
• python-dotenv==1.0.1 - Environment variable management
• validators==0.34.0 - URL validation
• And other supporting dependencies

⚙️ Configuration

1. Create Environment File

Copy the placeholder file and rename it:

# Windows
copy .env.placeholeder .env

# Linux/macOS
cp .env.placeholeder .env

2. Configure Environment Variables

Edit the .env file with your configuration:

# Your Telegram Bot API Token from @BotFather
TOKEN_API="1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"

# Comma-separated list of allowed Telegram User IDs
ALLOWED_IDS="123456789,987654321"

# Internal state for conversation handler (leave as 0)
STATE_REQUEST_URL=0

How to Obtain Required Values:

TOKEN_API:

1. Open Telegram and search for @BotFather
2. Send /newbot command
3. Follow the instructions to create your bot
4. Copy the provided API token

ALLOWED_IDS:

1. Open Telegram and search for @userinfobot
2. Start the bot and it will show your User ID
3. Add your ID (and any other authorized users) to the configuration

STATE_REQUEST_URL:

• Keep this value as 0 (used internally by the conversation handler)

3. Database Configuration

The bot automatically creates an SQLite database (miodatabase.db) on first run. No manual setup required.

📖 Usage

Starting the Bot

Run the bot from the command line:

python peppybot.py

You should see:

INFO - Starting bot...
INFO - Bot started successfully

Available Commands

Command	Description
/start	Initialize the bot and register your user account
/follow	Begin monitoring a new website URL
/unfollow	Stop monitoring a specific URL (shows selection menu)
/stop	Stop all monitoring tasks and deactivate the bot
/list	Display all URLs you're currently monitoring
/cancel	Cancel the current operation
/help	Show all available commands

Usage Examples

Example 1: Start Monitoring a Website

User: /follow
Bot: Please enter the URL you wish to follow:

User: https://example.com
Bot: URL added successfully!

The bot will now check this URL every 60 seconds and notify you of any changes.

Example 2: View Your Monitored URLs

User: /list
Bot: 
1. https://example.com
2. https://news.website.com
3. https://blog.example.org

Example 3: Unfollow a URL

User: /unfollow
Bot: Please select the URL you wish to unfollow:
     [1. https://example.com]
     [2. https://news.website.com]
     
User: *clicks on button*
Bot: Monitoring of https://example.com stopped.

Example 4: Receive Change Notification

Bot: 🔔 Change detected on https://example.com
     The content has been updated.

Example 5: Stop All Monitoring

User: /stop
Bot: All monitoring has been stopped. You can reactivate me using /start.

Workflow Example

Here's a complete workflow from start to finish:

1. User: /start
   Bot: Hello @username, it's a pleasure to meet you! I am @PeppyWebMonitorBot...

2. User: /follow
   Bot: Please enter the URL you wish to follow:

3. User: https://github.com/trending
   Bot: URL added successfully!

4. User: /follow
   Bot: Please enter the URL you wish to follow:

5. User: https://news.ycombinator.com
   Bot: URL added successfully!

6. User: /list
   Bot: 
   1. https://github.com/trending
   2. https://news.ycombinator.com

7. [Bot automatically detects a change]
   Bot: 🔔 Change detected on https://github.com/trending

8. User: /unfollow
   Bot: [Shows inline keyboard with options]
   User: [Selects URL to unfollow]
   Bot: Monitoring of https://github.com/trending stopped.

🌐 Deployment

Local Deployment

Simply run the bot on your local machine:

python peppybot.py

Keep the terminal window open. The bot will run until you stop it with Ctrl+C.

Cloud Deployment Options

Option 1: VPS (Recommended)

Deploy on services like:

• DigitalOcean
• AWS EC2
• Google Cloud Platform
• Azure Virtual Machines

Use screen or tmux to keep the bot running:

screen -S peppybot
python peppybot.py
# Press Ctrl+A then D to detach

Option 2: PaaS Platforms

Deploy on platforms like:

• Heroku
• Railway.app
• Render.com

Note: Some free hosting services may restrict HTTP requests to specific URLs. Check the allowed URL list for your hosting provider.

Option 3: Docker Container

Create a Dockerfile:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "peppybot.py"]

Build and run:

docker build -t peppybot .
docker run -d --env-file .env peppybot

📁 Project Structure

peppy-webmonitor-bot-2024/
├── peppybot.py          # Main bot application and monitoring logic
├── command.py           # Command handlers for Telegram commands
├── database.py          # SQLite database management
├── utility.py           # Helper functions (URL validation, content fetching)
├── requirements.txt     # Python dependencies
├── .env.placeholeder    # Environment variables template
├── .env                 # Your configuration (not tracked by git)
├── miodatabase.db       # SQLite database (auto-created)
├── README.md            # This file
└── note.txt             # Additional notes

Key Components:

• peppybot.py: Core application containing the WebMonitoringBot class, task management, and main execution loop
• command.py: Implements all Telegram command handlers (/start, /follow, /unfollow, etc.)
• database.py: Manages SQLite database operations for users, URLs, and tasks
• utility.py: Contains helper methods for URL validation, content fetching, and change detection

🤝 Contributing

Contributions are welcome! To contribute:

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

📄 License

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

🐛 Troubleshooting

Common Issues:

Bot doesn't respond:

• Verify your TOKEN_API is correct
• Check that your user ID is in ALLOWED_IDS
• Ensure the bot is running (python peppybot.py)

URL not being monitored:

• Verify the URL is valid and accessible
• Check that you haven't reached the 5 URL limit
• Review logs for error messages

Database errors:

• Delete miodatabase.db and restart the bot
• Check file permissions in the project directory

---

Made with ❤️ by Giuseppe | Powered by Python & Telegram Bot API