UnbanBot

A fast, secure, and smart Discord utility bot designed to filter and unban users based on their ban reasons.

• 🔍 Filter by Reason: Effortlessly find specific users in your server's ban list simply by searching for keywords inside their original ban reason.
• ⚡ Automated Unbanning: Safely unban groups of players at once who were banned under a specific reason. Great for undoing rogue mod sweeps!
• 🛡️ Rate Limit Protected: Employs user-side 10-second cooldowns and dynamically handles official Discord API Backoff rules internally to avoid suspensions.
• 📜 Full Terminal Logging: Neatly outputs all cooldown misses, unban arrays, interaction requests, and metrics locally without spamming your channels.

Before running the bot yourself, ensure you have the following installed and prepped:

• Node.js (Version v16.9.0 or higher required by Discord.js v14)
• A Discord Bot Token from the Discord Developer Portal
• ⚠️ Gateway Intents: You must enable the Server Members Intent in the "Bot" tab of your Discord Developer Portal!
• ⚠️ Critical Requirement: The bot's owner MUST have 2FA enabled on their Discord account if the target Server requires 2FA for Moderation actions.

Follow these simple steps to run this bot locally on your own machine or a VPS.

Open your terminal and clone this repository down to your machine:

git clone https://github.com/viswagfx/UnbanBot.git
cd UnbanBot

Install all the required background packages (discord.js and dotenv).

npm install

Inside your project directory, you'll see a .env file (or you can create one if missing). Open it and paste in your bot token like this:

DISCORD_TOKEN=your_bot_token_here

Note: Never share your .env file or commit it to GitHub. It is properly ignored via .gitignore.

Start up your bot using the simplest Node command:

node index.js

The terminal will automatically declare once the Slash Commands have been refreshed and your bot logs in!

Note: Slash commands might take a brief second to globally sync across Discord interfaces the very first time you boot the bot!