Discord Bulk Message Purge Tool - Documentation

Overview

A Python script for deleting messages from Discord channels without requiring npm/discord.js dependencies. Uses only Python standard library + requests.

Location: /scripts/discord-purge-tool.py (in the subfolder of the skill)

Quick Start

1. Configure Bot Token

Create token.json in the workspace directory:

{
  "token": "tokenhere"
}

OR set environment variable:

$env:DISCORD_TOKEN = "YOUR_BOT_TOKEN_HERE"

2. ask for confirmation

• ask from the user if they really want to delete x amount of messages in the current channel

3. Run the Tool

From this skill's directory:

# Delete last 5 messages
python scripts/discord-purge-tool.py --channel-id <CHANNEL_ID>

# Delete custom count
python scripts/discord-purge-tool.py purge 25 --channel-id <CHANNEL_ID>

# Larger purge (handles batches automatically)
python scripts/discord-purge-tool.py purge 200 --channel-id <CHANNEL_ID>

Usage Examples

Typical User Requests (I auto-detect intent):

• "delete 50 messages in #general"
• "purge the last 100 messages"
• "clean up #productivity"
• "remove old spam from chat"
• "clear the discord channel"
• "bulk delete last 25 messages in [channel]"

Script Commands:

# Delete last X messages (default: 5)
python scripts/discord-purge-tool.py purge <count> --channel-id <CHANNEL_ID>

# Auto-detect channel from context if mentioned earlier
python scripts/discord-purge-tool.py purge 50

Features

• ✅ Standard library only - No npm/discord.js required
• ✅ Rate limiting - Handles Discord's 100 messages per batch limit automatically
• ✅ Flexible arguments - Works with multiple input formats
• ✅ Live mode - Actual deletion when token configured
• ✅ Error handling - Shows detailed error messages

Rate Limiting

Discord enforces:

• Max 100 messages per bulk delete request (hard API limit)
• Waits automatically between batches for larger purges

The tool handles this transparently, so you don't need to worry about it.

Permissions Required

Your Discord bot must have MANAGE_MESSAGES permission in target channels:

1. Go to your Discord server settings
2. find the role your bot uses
3. add "manage Messages" permission

Error Codes

• 403 Forbidden - Bot lacks MANAGE_MESSAGES permission in channel
• 400 Bad Request - Invalid channel ID or no messages found
• Other errors - Displayed in output with details

Configuration

token.json

{
  "token": "YOUR_BOT_TOKEN_HERE"
}

Or environment variable:

$env:DISCORD_TOKEN = "YOUR_BOT_TOKEN_HERE"

Command Reference

Troubleshooting

"403 Forbidden" error

The bot doesn't have MANAGE_MESSAGES permission. Fix by:

1. Adding permissions via Discord settings
2. OR setting DISCORD_TOKEN env variable and running from this skill's directory

"400 Bad Request" error

Check that:

• Channel ID is correct
• Channel exists and has messages
• Token file is valid JSON with "token" key

Notes

• Script path is relative: scripts/discord-purge-tool.py
• Works from this skill's directory or when DISCORD_TOKEN env variable is set