Bot de moderación para Discord en Python: avisos, silenciar, expulsar, banear y borrar mensajes

discord.py
python-dotenv

DISCORD_TOKEN=pega-aquí-tu-token
CANAL_REGISTRO=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()  # lee el token y el canal de registro del fichero .env

# Basta con los intents por defecto: los comandos con barra llegan como interacciones.
client = discord.Client(intents=discord.Intents.default())
tree = app_commands.CommandTree(client)

# Los avisos se guardan en un fichero junto al bot: no se pierden al reiniciar.
AVISOS = Path("avisos.json")
CANAL_REGISTRO = int(os.getenv("CANAL_REGISTRO") or 0)


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


def guardar_avisos(datos: dict) -> None:
    AVISOS.write_text(json.dumps(datos, ensure_ascii=False, indent=2), "utf-8")


def no_se_puede(interaction: discord.Interaction, miembro: discord.Member) -> str | None:
    """Discord no deja moderar a quien está a tu altura o por encima: lo miramos antes."""
    guild = interaction.guild
    if miembro == interaction.user:
        return "No puedes usarlo contigo."
    if miembro.id == guild.owner_id:
        return "Al dueño del servidor no se le puede moderar."
    if miembro.top_role >= guild.me.top_role:
        return f"El rol de {miembro.display_name} está a mi altura o por encima: sube el mío en «Ajustes del servidor» → «Roles»."
    if interaction.user.id != guild.owner_id and miembro.top_role >= interaction.user.top_role:
        return f"El rol de {miembro.display_name} está a tu altura o por encima."
    return None


async def registrar(interaction: discord.Interaction, accion: str, miembro: discord.Member, motivo: str) -> None:
    """Apunta la acción en el canal de registro, si hay uno en el .env."""
    canal = client.get_channel(CANAL_REGISTRO)
    if canal is None:
        return
    tarjeta = discord.Embed(title=accion, color=0x5B4AE8, timestamp=discord.utils.utcnow())
    tarjeta.add_field(name="Miembro", value=f"{miembro.mention} ({miembro})")
    tarjeta.add_field(name="Por", value=interaction.user.mention)
    tarjeta.add_field(name="Motivo", value=motivo, inline=False)
    await canal.send(embed=tarjeta)


async def avisar_por_privado(miembro: discord.Member, texto: str) -> None:
    # Antes de expulsar o banear: después ya no se le puede escribir.
    try:
        await miembro.send(texto)
    except discord.HTTPException:
        pass  # tiene los mensajes privados cerrados


@tree.command(name="aviso", description="Da un aviso a un miembro (queda apuntado)")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
@app_commands.describe(miembro="A quién", motivo="Por qué")
async def aviso(interaction: discord.Interaction, miembro: discord.Member, motivo: str):
    if error := no_se_puede(interaction, miembro):
        await interaction.response.send_message(error, ephemeral=True)
        return
    datos = leer_avisos()
    lista = datos.setdefault(str(interaction.guild.id), {}).setdefault(str(miembro.id), [])
    lista.append({"motivo": motivo, "por": interaction.user.id, "fecha": discord.utils.utcnow().isoformat()})
    guardar_avisos(datos)
    await interaction.response.send_message(f"⚠️ {miembro.mention}, tienes un aviso: {motivo} (llevas {len(lista)}).")
    await registrar(interaction, f"Aviso n.º {len(lista)}", miembro, motivo)


@tree.command(name="avisos", description="Los avisos que lleva un miembro")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
async def avisos(interaction: discord.Interaction, miembro: discord.Member):
    lista = leer_avisos().get(str(interaction.guild.id), {}).get(str(miembro.id), [])
    if not lista:
        await interaction.response.send_message(f"{miembro.display_name} no tiene avisos.", ephemeral=True)
        return
    lineas = [f"{n}. {a['fecha'][:10]} — {a['motivo']} (<@{a['por']}>)" for n, a in enumerate(lista[-15:], 1)]
    await interaction.response.send_message(f"Avisos de {miembro.display_name} ({len(lista)}):\n" + "\n".join(lineas), ephemeral=True)


@tree.command(name="silenciar", description="Aísla temporalmente a un miembro: no puede escribir ni hablar")
@app_commands.guild_only()
@app_commands.default_permissions(moderate_members=True)
@app_commands.describe(minutos="De 1 minuto a 28 días (40320 minutos)")
async def silenciar(interaction: discord.Interaction, miembro: discord.Member,
                    minutos: app_commands.Range[int, 1, 40320], motivo: str = "Sin motivo"):
    if error := no_se_puede(interaction, miembro):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await miembro.timeout(datetime.timedelta(minutes=minutos), reason=motivo)
    await interaction.response.send_message(f"🔇 {miembro.mention} silenciado {minutos} min: {motivo}")
    await registrar(interaction, f"Silenciado {minutos} min", miembro, motivo)


@tree.command(name="expulsar", description="Echa a un miembro (puede volver con otra invitación)")
@app_commands.guild_only()
@app_commands.default_permissions(kick_members=True)
async def expulsar(interaction: discord.Interaction, miembro: discord.Member, motivo: str = "Sin motivo"):
    if error := no_se_puede(interaction, miembro):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await avisar_por_privado(miembro, f"Te han expulsado de {interaction.guild.name}: {motivo}")
    await miembro.kick(reason=motivo)
    await interaction.response.send_message(f"👢 {miembro} expulsado: {motivo}")
    await registrar(interaction, "Expulsado", miembro, motivo)


@tree.command(name="banear", description="Echa a un miembro y no le deja volver")
@app_commands.guild_only()
@app_commands.default_permissions(ban_members=True)
@app_commands.describe(dias_mensajes="Borrar sus mensajes de los últimos días (0 a 7)")
async def banear(interaction: discord.Interaction, miembro: discord.Member, motivo: str = "Sin motivo",
                 dias_mensajes: app_commands.Range[int, 0, 7] = 0):
    if error := no_se_puede(interaction, miembro):
        await interaction.response.send_message(error, ephemeral=True)
        return
    await avisar_por_privado(miembro, f"Te han baneado de {interaction.guild.name}: {motivo}")
    await interaction.guild.ban(miembro, reason=motivo, delete_message_seconds=dias_mensajes * 86400)
    await interaction.response.send_message(f"🔨 {miembro} baneado: {motivo}")
    await registrar(interaction, "Baneado", miembro, motivo)


@tree.command(name="borrar", description="Borra los últimos mensajes de este canal")
@app_commands.guild_only()
@app_commands.default_permissions(manage_messages=True)
async def borrar(interaction: discord.Interaction, cantidad: app_commands.Range[int, 1, 100]):
    # Borrar muchos tarda: primero le decimos a Discord que espere.
    await interaction.response.defer(ephemeral=True)
    borrados = await interaction.channel.purge(limit=cantidad)
    await interaction.followup.send(f"Borrados {len(borrados)} mensajes.", ephemeral=True)


@tree.error
async def al_fallar(interaction: discord.Interaction, error: app_commands.AppCommandError):
    original = getattr(error, "original", error)
    if isinstance(original, discord.Forbidden):
        texto = "Me falta un permiso para eso, o el rol de esa persona está por encima del mío."
    else:
        texto = "Algo ha fallado: mira la consola del bot."
        print(f"Error: {original!r}")
    if interaction.response.is_done():
        await interaction.followup.send(texto, ephemeral=True)
    else:
        await interaction.response.send_message(texto, ephemeral=True)


@client.event
async def on_ready():
    await tree.sync()  # publica los seis comandos
    print(f"Conectado como {client.user}")


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