🧹 PurgeBot - The Ultimate Discord Message Management Solution

Effortlessly manage your Discord server's message history with the most powerful and reliable purge bot available.

🚀 Why Choose PurgeBot?

Managing message history in Discord has never been easier. PurgeBot is the premium solution trusted by server administrators who demand performance, reliability, and precision in their moderation tools.

🎯 Surgical Precision

• Target specific users, roles, webhooks, or everyone
• Filter by date range (1-30 days)
• Server-wide, category, or channel-specific operations
• Skip protected channels during bulk operations
• Include threads in purge operations (automatically unarchives if needed)
• Include bot messages (role, everyone, inactive)

💪 Powerful Features

6 Specialized Purge Commands

• /purge user - Remove all messages from a specific user
• /purge role - Clear messages from all members with a specific role
• /purge everyone - Complete channel or category cleanup
• /purge inactive - Clean up messages from users who left your server
• /purge webhook - Remove all messages sent by webhooks
• /purge deleted - Remove messages from deleted Discord accounts

✨ Premium — Server Customization

Unlock per-server customization with a Server Subscription:

• /customize - Customize the bot's appearance for your server (requires Administrator permission)
  • Custom bot nickname per server
  • Custom bot avatar per server
  • Remove the "Powered by PurgeBot" branded footer

🔍 Advanced Content Filtering

Filter messages with precision using our intelligent filtering system:

• Smart Auto-Detection - Automatically detects regex patterns vs plain text
• Multiple Filter Modes:
  • contains - Messages containing specific text
  • regex - Advanced pattern matching
  • exact - Exact message matches
  • starts_with - Messages starting with text
  • ends_with - Messages ending with text
• Case Sensitivity Control - Optional case-sensitive matching

📊 Admin Commands & Error Logging

For self-hosted instances, PurgeBot includes powerful admin tools:

• PostgreSQL Error Logging - Persistent error tracking with full context (guild, channel, user, stack traces)
• Remote Error Management - View and manage errors directly from Discord:
  • /admin error list - View recent errors
  • /admin error check <error_id> - Detailed error information
  • /admin error delete <error_id> - Remove specific error
  • /admin error clear [filters] - Bulk deletion with filters (level, area, date)
• Guild-Specific Registration - Admin commands only appear in your designated support server
• No SSH Required - Manage and debug your bot entirely from Discord

Real-Time Progress Tracking

Watch your purge operations in real-time with:

• Message count and channel tracking
• One-click cancellation for any operation

🛡️ Security & Permissions

PurgeBot respects Discord's permission system:

Required Bot Permissions:

• Send Messages - Send the progress and completed view
• View Channel - Access channel content
• Read Message History - Scan existing messages
• Manage Messages - Delete targeted messages

User Requirements:

• Users must have Manage Messages permission to execute purge commands
• Server administrators maintain full control over who can use PurgeBot

🎮 Perfect For:

• Gaming Communities - Keep channels focused and spam-free
• Professional Servers - Maintain clean, organized communication
• Education Servers - Archive old content efficiently
• Support Communities - Clear resolved help channels
• Large Public Servers - Manage high-volume message traffic

🚦 Getting Started is Easy!

1️⃣ Add PurgeBot to Your Server

2️⃣ Use /help to See All Commands

3️⃣ Start Purging with Confidence!

📖 Example Commands

Purge Commands:

# Delete spam messages from a specific user
/purge user target_id:channel user:@spammer filter:spam

# Remove all messages with links from a role
/purge role target_id:server role:@members filter:"https://" filter_mode:contains

# Clean up messages matching a regex pattern
/purge everyone target_id:channel filter:"(buy|sell|trade)" filter_mode:regex days:7

# Delete messages starting with specific prefix (case-sensitive)
/purge inactive target_id:category filter:"!" filter_mode:starts_with case_sensitive:true

# Include threads when purging (will unarchive archived threads)
/purge everyone target_id:channel include_threads:true days:7

# Include bot messages when purging a role
/purge role target_id:server role:@bots include_bots:true

# Remove all webhook messages from a channel
/purge webhook target_id:channel

# Remove recent webhook messages matching a pattern
/purge webhook target_id:category days:7 filter:"alert" filter_mode:contains

Admin Commands (Self-hosted only, requires setup):

# View recent errors
/admin error list limit:25

# View recent errors from a specific guild
/admin error list limit:25 guild_id:1412752753348055111

# Check specific error details
/admin error check error_id:42

# Delete specific error
/admin error delete error_id:42

# Clear errors by level
/admin error clear level:ERROR

# Clear errors older than 30 days
/admin error clear older_than_days:30

# Clear errors by area
/admin error clear area:COMMANDS

💬 Need Help?

• Join Our Support Server - Get instant help from our team
• Report Issues - Help us improve PurgeBot

🔧 Self-Hosting (Advanced Users)

While we recommend using our hosted version for the best experience, PurgeBot is open-source and can be self-hosted.

View Self-Hosting Instructions

Prerequisites

• Node.js 18.0.0 or higher
• Discord Bot Token
• PostgreSQL database (optional - for error logging and customization storage)

Quick Installation

1. Clone the repository:

git clone https://github.com/biast12/PurgeBot
cd PurgeBot

2. Install dependencies:

npm install

3. Configure your bot (create config.json from config.example.json):

{
  "token": "your_bot_token_here",

  "databaseUrl": "postgresql://username:password@localhost:5432/purgebot",

  "adminIds": ["your_discord_user_id", "other_admin_id"],
  "adminGuildId": "your_support_server_id",

  "premiumSkuId": "your_sku_id_here"
}

Config Fields:

• token - Your Discord bot token (required)
• databaseUrl - PostgreSQL connection string for error logging and customization storage (optional)
• adminIds - Array of Discord user IDs authorized for admin commands (optional)
• adminGuildId - Guild ID where admin commands are registered (optional)
• premiumSkuId - Discord SKU ID for the Server Subscription (optional, enables /customize)

4. Register commands:

npm run build
npm run register  # Register global and admin commands

5. Start the bot:

npm start         # Development (with ts-node)
npm run start:prod  # Production (compiled)

PostgreSQL Error Logging Setup (Optional)

PurgeBot can persist errors and customizations to a PostgreSQL database for remote debugging and per-guild settings:

1. Create a PostgreSQL database using any provider (local, Neon, Supabase, Railway, etc.)

2. Run the schema to create the required tables:

   psql your_connection_string -f schema.sql

3. Add to config.json:

   {
     "databaseUrl": "postgresql://username:password@localhost:5432/purgebot"
   }

Error Logging Features:

• Automatic error capture with full context (guild, channel, user, stack traces)
• Indexed for fast queries (by level, area, guild, timestamp)
• Remote access via Discord admin commands (no SSH needed)

Admin Commands Setup (Optional)

Configure admin commands for remote bot management:

1. Get Your Discord User ID:

   • Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
   • Right-click your username → "Copy User ID"

2. Get Your Admin Guild ID:

   • Right-click your support server → "Copy Server ID"

3. Add to config.json:

   {
     "adminIds": ["648679147085889536", "1356612233878179921"],
     "adminGuildId": "1412752753348055111"
   }

4. Register Commands:

   npm run register

   Admin commands will only appear in the specified guild.

Troubleshooting

Admin Commands Not Appearing

• Verify adminGuildId is set correctly in config.json
• Run npm run register after changing configuration
• Admin commands only appear in the specified guild, not globally

Build Scripts

Windows:

• run.bat - Start the bot
• run.sh - Start the bot (Linux/macOS)

🏆 Why We're Different

Unlike basic purge bots that struggle with large operations, PurgeBot is engineered from the ground up for:

• Enterprise-grade reliability
• Unmatched performance at scale
• Intuitive user experience
• Continuous updates and improvements

🎯 Ready to Transform Your Server Management?

Don't let message clutter slow down your community. Join thousands of server owners who trust PurgeBot for their message management needs.

---

PurgeBot - Professional Message Management for Discord