discord-py

discord.py Quick Reference

This skill provides guidance for building Discord bots with the discord.py library.

Quick Start: Minimal Bot

import discord

intents = discord.Intents.default()
intents.message_content = True  # Required for reading message content

client = discord.Client(intents=intents)

@client.event
async def on_ready():
    print(f'Logged in as {client.user}')

@client.event
async def on_message(message):
    if message.author == client.user:
        return  # Ignore self
    if message.content.startswith('$hello'):
        await message.channel.send('Hello!')

client.run('YOUR_BOT_TOKEN')

Important: Never name your file discord.py - it conflicts with the library.

Critical: Intents Setup

Intents are required in discord.py 2.0+. They control which events your bot receives.

Basic Setup

intents = discord.Intents.default()  # Common intents, excludes privileged

Enabling Specific Intents

intents = discord.Intents.default()
intents.message_content = True  # Read message text (privileged)
intents.members = True          # Member join/leave events (privileged)
intents.presences = True        # Status updates (privileged)

Privileged Intents Require Portal Setup

These three intents must ALSO be enabled in the Discord Developer Portal:

1. Message Content Intent - Required for reading message text
2. Server Members Intent - Required for member events and accurate member lists
3. Presence Intent - Required for tracking user status/activity

Go to: Discord Developer Portal > Your App > Bot > Privileged Gateway Intents

Client vs Bot

When to Use Bot (commands extension)

from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.command()
async def ping(ctx):
    await ctx.send('Pong!')

bot.run('TOKEN')

Event Handling

Common events (decorate with @client.event or @bot.event):

Commands Extension Basics

from discord.ext import commands

bot = commands.Bot(command_prefix='!', intents=intents)

@bot.command()
async def greet(ctx, name: str):
    """Greet someone by name."""
    await ctx.send(f'Hello, {name}!')

@bot.command(name='add')
async def add_numbers(ctx, a: int, b: int):
    """Add two numbers."""
    await ctx.send(f'{a} + {b} = {a + b}')

Command Groups

@bot.group()
async def settings(ctx):
    if ctx.invoked_subcommand is None:
        await ctx.send('Use !settings <subcommand>')

@settings.command()
async def show(ctx):
    await ctx.send('Current settings: ...')

Slash Commands Basics

import discord
from discord import app_commands

intents = discord.Intents.default()
client = discord.Client(intents=intents)
tree = app_commands.CommandTree(client)

@tree.command(name='ping', description='Check bot latency')
async def ping(interaction: discord.Interaction):
    await interaction.response.send_message(f'Pong! {round(client.latency * 1000)}ms')

@client.event
async def on_ready():
    await tree.sync()  # Sync commands with Discord
    print(f'Synced commands for {client.user}')

client.run('TOKEN')

Slash Command with Parameters

@tree.command(name='greet', description='Greet a user')
@app_commands.describe(user='The user to greet')
async def greet(interaction: discord.Interaction, user: discord.Member):
    await interaction.response.send_message(f'Hello, {user.mention}!')

Sending Messages

# In event handler
await message.channel.send('Hello!')
await message.channel.send('With embed', embed=embed)
await message.channel.send('With file', file=discord.File('image.png'))

# Reply to message
await message.reply('Replying to you!')

# In slash command
await interaction.response.send_message('Response')
await interaction.response.send_message('Only you see this', ephemeral=True)

# Edit/followup for slash commands
await interaction.response.defer()
await interaction.followup.send('Delayed response')

Common Patterns

Check if Message Author is Bot Owner

@bot.command()
@commands.is_owner()
async def shutdown(ctx):
    await ctx.send('Shutting down...')
    await bot.close()

Permission Checks

@bot.command()
@commands.has_permissions(manage_messages=True)
async def clear(ctx, amount: int):
    await ctx.channel.purge(limit=amount + 1)

Error Handling

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingPermissions):
        await ctx.send('You lack permissions for this command.')
    elif isinstance(error, commands.CommandNotFound):
        pass  # Ignore unknown commands
    else:
        raise error

Fetching Latest Documentation

When you need up-to-date API details or are unsure about a feature, fetch the official documentation:

# Core API reference
WebFetch: https://discordpy.readthedocs.io/en/latest/api.html

# Commands extension
WebFetch: https://discordpy.readthedocs.io/en/latest/ext/commands/api.html

# Slash commands (app_commands)
WebFetch: https://discordpy.readthedocs.io/en/latest/interactions/api.html

# Intents guide
WebFetch: https://discordpy.readthedocs.io/en/latest/intents.html

# Quickstart guide
WebFetch: https://discordpy.readthedocs.io/en/latest/quickstart.html

# Frequently asked questions
WebFetch: https://discordpy.readthedocs.io/en/latest/faq.html

Always fetch documentation when:

• The user asks about a feature not covered in this skill
• You need to verify exact method signatures or parameters
• Working with less common features (webhooks, voice, threads, forums)
• The user reports behavior different from what you expect

Additional Resources

• For detailed API reference, see reference.md
• For complete code examples, see examples.md
• Official docs: https://discordpy.readthedocs.io/en/latest/