AutoReactorPy 🚀

A high-performance, asynchronous, 100% TOS-compliant Discord reaction mirroring bot built with Python 3.10+ and the official discord.py (v2.x) library.

AutoReactorPy automatically monitors predefined target Discord channels in a continuous round-robin sequence, scans channel message histories sequentially from oldest to newest, mirrors existing user reactions randomly, and persists progress state across server restarts using MongoDB (motor) or local progress.json. Designed to run flawlessly on both Android Termux and Ephemeral Cloud Hosting (Render / Railway).

---

🏗️ System Architecture Overview

 +---------------------------------------+
| Discord API |
+-------------------+-------------------+
| (Bot Token Auth)
v
+------------------------+ +-----------+-----------+ +------------------------+
| aiohttp Web Server | <--> | AutoReactorPy Bot | <--> | JSON / MongoDB Atlas |
| (Cloud Health Checks) | | (discord.py v2.x) | | (Progress State Engine)|
+------------------------+ +-----------+-----------+ +------------------------+
|
v
+-------------------+-------------------+
| Round-Robin Channel Scanner Loop |
| - Channel 1 -> Channel 2 -> Ch 3 |
| - History: Oldest to Newest |
| - Reaction Mirroring Logic |
| - 300s Post-Reaction Cooldown |
+---------------------------------------+

Core Features & Workflow:

1. Multi-Channel Round-Robin: Continuously monitors target channel IDs in sequential rotation.
2. Sequential History Scanning: Resumes scanning from the last processed last_message_id stored in progress.json / MongoDB.
3. Smart Reaction Mirroring Rules:
   • Skip zero reactions: Ignores messages with no existing reactions.
   • Skip duplicate reactions: Ignores messages the bot has already reacted to.
   • Mirror existing reactions: Randomly selects ONE existing reaction on eligible messages and duplicates it. Never adds unrepresented emojis.
4. Strict Cooldown Enforcement: Enforces a strict 5-minute (300-second) cooldown ONLY after a successful reaction. Skipped messages proceed instantly.
5. End-of-History Pointer Reset: Resets channel scan pointers to 0 when history end is reached, restarting from oldest messages.
6. Persistent State Management: Uses local progress.json and optional MongoDB Atlas (motor) to maintain progress state across restarts.
7. Cloud Health Check Web Server: Runs an async aiohttp HTTP server on PORT for uptime monitoring and health check pinging.
8. Error Handling & Rate Limit Mitigation: Handles rate limits (HTTP 429), permissions issues, and API exceptions gracefully without stopping background tasks.

---

⚙️ Environment Configuration

Copy .env.example to .env and configure your credentials:

cp .env.example .env

Variable	Required	Description
USER_TOKEN	Yes	Bot Token from Discord Developer Portal (or DISCORD_TOKEN).
TARGET_CHANNELS	Yes	Comma-separated target Discord Channel IDs (e.g. 111111,222222,333333).
PORT	No	Web server port for health checks (Default: 8080).
MONGO_URI	No	Optional MongoDB connection string (leave blank to use progress.json).
MONGO_DB_NAME	No	MongoDB Database Name (Default: autoreactor_db).
COOLDOWN_SECONDS	No	Reaction cooldown interval in seconds (Default: 300).

---

🖼️ Visual Setup & Deployment Guides

📱 1. Android Termux Deployment Guide

Follow these steps to run the bot 24/7 on an Android device using Termux:

1. Update packages and install dependencies:

   pkg update && pkg upgrade -y
   pkg install python git -y

2. Clone the repository:

   git clone https://github.com/gtajisan/AutoReactorPy.git
   cd AutoReactorPy

3. Create a virtual environment and install packages:

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

4. Configure environment variables:

   cp .env.example .env
   nano .env

5. Start the bot:

   python main.py

💡 Termux Tip: Acquire wake lock (termux-wake-lock) to keep CPU active when the screen turns off.

---

☁️ 2. Render Cloud Hosting Deployment Guide

Follow these steps to deploy on Render.com (Web Service):

1. Fork or Push repository to GitHub.
2. Create New Web Service on Render:
   • Connect your GitHub repository.
   • Environment: Python 3
   • Build Command: pip install -r requirements.txt
   • Start Command: python main.py
3. Set Environment Variables in Render Dashboard:
   • Add USER_TOKEN (or DISCORD_TOKEN), TARGET_CHANNELS, and PORT (10000 or 8080).
4. Health Check Path:
   • Render automatically pings the root / or /health endpoint on PORT.
5. Deploy: Click Create Web Service. Render will build and launch main.py.

---

🔒 Security Best Practices

• Never share your Bot Token or credentials: Keep your .env file secret and out of source control.
• Bot Permissions: Grant your bot only necessary guild permissions:
  • Read Messages / View Channels
  • Read Message History
  • Add Reactions
• Use Bot Token: Operates strictly via Official Discord Bot API tokens to guarantee compliance with Discord Terms of Service. Never use user tokens.

---

👨‍💻 Developer Info

Maintained and developed by Farhan Muh Tasim / gtajisan (https://github.com/gtajisan). Note: Hosted on secondary mirrors, but all core architecture is managed by gtajisan.

---

📄 License

Distributed under the MIT License. See LICENSE for details.