Discord Moderation Bot in Python: Warn, Mute, Kick, Ban and Purge Messages

discord.py
python-dotenv

DISCORD_TOKEN=paste-your-token-here
LOG_CHANNEL=123456789012345678

import datetime
import json
import os
from pathlib import Path

import discord
from discord import app_commands
from dotenv import load_dotenv

load_dotenv()  # reads the token and the log channel from the .env file

# The default intents are enough: slash commands arrive as interactions.
client = discord.Client(intents=discord.Intents.default())
tree = app_commands.CommandTree(client)

# Warnings are saved in a file next to the bot: they aren't lost on restart.
WARNINGS = Path("warnings.json")
LOG_CHANNEL = int(os.getenv("LOG_CHANNEL") or 0)


def load_warnings() -> dict:
    return json.loads(WARNINGS.read_text("utf-8")) if WARNINGS.exists() else {}


def save_warnings(data: dict) -> None:
    WARNINGS.write_text(json.dumps(data, ensure_ascii=False, indent=2), "utf-8")


def not_allowed(interaction: discord.Interaction, member: discord.Member) -> str | None:
    """Discord won't let you moderate someone at your level or above: we check it first."""
    guild = interaction.guild
    if member == interaction.user:
        return "You can't use it on yourself."
    if member.id == guild.owner_id:
        return "The server owner can't be moderated."
    if member.top_role >= guild.me.top_role:
        return f"{member.display_name}'s role is at my level or above: move mine up in “Server Settings” → “Roles”."
    if interaction.user.id != guild.owner_id and member.top_role >= interaction.user.top_role:
        return f"{member.display_name}'s role is at your level or above."
    return None


async def log(interaction: discord.Interaction, action: str, member: discord.Member, reason: str) -> None:
    """Records the action in the log channel, if there's one in the .env."""
    channel = client.get_channel(LOG_CHANNEL)
    if channel is None:
        return
    card = discord.Embed(title=action, color=0x5B4AE8, timestamp=discord.utils.utcnow())
    card.add_field(name="Member", value=f"{member.mention} ({member})")
    card.add_field(name="By", value=interaction.user.mention)
    card.add_field(name="Reason", value=reason, inline=False)
    await channel.send(embed=card)


async def dm(member: discord.Member, text: str) -> None:
    # Before kicking or banning: afterwards you can't message them any more.
    try:
        await member.send(text)
    except discord.HTTPException:
        pass  # they have DMs closed


@tree.command(name="warn", description="Gives a member a warning (it's recorded)")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
@app_commands.describe(member="Who", reason="Why")
async def warn(interaction: discord.Interaction, member: discord.Member, reason: str):
    if error := not_allowed(interaction, member):
        await interaction.response.send_message(error, ephemeral=True)
        return
    data = load_warnings()
    entries = data.setdefault(str(interaction.guild.id), {}).setdefault(str(member.id), [])
    entries.append({"reason": reason, "by": interaction.user.id, "date": discord.utils.utcnow().isoformat()})
    save_warnings(data)
    await interaction.response.send_message(f"⚠️ {member.mention}, you have a warning: {reason} (that's {len(entries)}).")
    await log(interaction, f"Warning #{len(entries)}", member, reason)


@tree.command(name="warnings", description="The warnings a member has")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
async def warnings(interaction: discord.Interaction, member: discord.Member):
    entries = load_warnings().get(str(interaction.guild.id), {}).get(str(member.id), [])
    if not entries:
        await interaction.response.send_message(f"{member.display_name} has no warnings.", ephemeral=True)
        return
    lines = [f"{n}. {w['date'][:10]} — {w['reason']} (<@{w['by']}>)" for n, w in enumerate(entries[-15:], 1)]
    await interaction.response.send_message(f"Warnings for {member.display_name} ({len(entries)}):\n" + "\n".join(lines), ephemeral=True)


@tree.command(name="mute", description="Times a member out: they can't type or talk")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
@app_commands.describe(minutes="From 1 minute to 28 days (40320 minutes)")
async def mute(interaction: discord.Interaction, member: discord.Member,
               minutes: app_commands.Range[int, 1, 40320], reason: str = "No reason"):
    if error := not_allowed(interaction, member):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await member.timeout(datetime.timedelta(minutes=minutes), reason=reason)
    await interaction.response.send_message(f"🔇 {member.mention} muted for {minutes} min: {reason}")
    await log(interaction, f"Muted {minutes} min", member, reason)


@tree.command(name="kick", description="Removes a member (they can come back with another invite)")
@app_commands.guild_only()
@app_commands.default_permissions(kick_members=True)
async def kick(interaction: discord.Interaction, member: discord.Member, reason: str = "No reason"):
    if error := not_allowed(interaction, member):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await dm(member, f"You've been kicked from {interaction.guild.name}: {reason}")
    await member.kick(reason=reason)
    await interaction.response.send_message(f"👢 {member} kicked: {reason}")
    await log(interaction, "Kicked", member, reason)


@tree.command(name="ban", description="Removes a member and doesn't let them back")
@app_commands.guild_only()
@app_commands.default_permissions(ban_members=True)
@app_commands.describe(delete_days="Delete their messages from the last few days (0 to 7)")
async def ban(interaction: discord.Interaction, member: discord.Member, reason: str = "No reason",
              delete_days: app_commands.Range[int, 0, 7] = 0):
    if error := not_allowed(interaction, member):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await dm(member, f"You've been banned from {interaction.guild.name}: {reason}")
    await interaction.guild.ban(member, reason=reason, delete_message_seconds=delete_days * 86400)
    await interaction.response.send_message(f"🔨 {member} banned: {reason}")
    await log(interaction, "Banned", member, reason)


@tree.command(name="purge", description="Deletes the latest messages in this channel")
@app_commands.guild_only()
@app_commands.default_permissions(manage_messages=True)
async def purge(interaction: discord.Interaction, amount: app_commands.Range[int, 1, 100]):
    # Deleting many takes a while: first we tell Discord to wait.
    await interaction.response.defer(ephemeral=True)
    deleted = await interaction.channel.purge(limit=amount)
    await interaction.followup.send(f"Deleted {len(deleted)} messages.", ephemeral=True)


@tree.error
async def on_error(interaction: discord.Interaction, error: app_commands.AppCommandError):
    original = getattr(error, "original", error)
    if isinstance(original, discord.Forbidden):
        text = "I'm missing a permission for that, or that person's role is above mine."
    else:
        text = "Something went wrong: check the bot's console."
        print(f"Error: {original!r}")
    if interaction.response.is_done():
        await interaction.followup.send(text, ephemeral=True)
    else:
        await interaction.response.send_message(text, ephemeral=True)


@client.event
async def on_ready():
    await tree.sync()  # publishes the six commands
    print(f"Logged in as {client.user}")


client.run(os.environ["DISCORD_TOKEN"])