When you first dive into building a Discord bot with discord.py, your instinct is probably to go straight for the on_message event. It feels intuitive: the bot sees a message, you check what the message says, and then you do something. I've seen a lot of junior devs start this way, and for a bot that only does one thing—like responding "Pong!" to "Ping!"—it's perfectly fine. But the moment you want to build something actually useful, like a team coffee tracker, this approach falls apart.

The If-Else Nightmare

Imagine we're building a bot that lets team members log how many coffees they've had today. In a naive implementation, you'd put everything inside a single asynchronous function. You'd have to manually check if the message starts with your prefix, then split the string to figure out which command was called, and then manually cast the remaining text into an integer for the coffee count.

@bot.event
async def on_message(message):
    if message.author == bot.user:
        return

    if message.content.startswith('!'):
        parts = message.content.split(' ')
        command = parts[0][1:] # Strip the '!'
        
        if command == 'coffee':
            try:
                count = int(parts[1])
                await message.channel.send(f"Logged {count} coffees!")
            except (IndexError, ValueError):
                await message.channel.send("You forgot the number!")
        elif command == 'stats':
            await message.channel.send("Here are the totals...")
        # Imagine 20 more 'elif' blocks here

This is what I call the "if-else nightmare." It's brittle. If a user adds an extra space, your split(' ') might return empty strings. If they forget an argument, your bot crashes or throws a messy IndexError. More importantly, as you add features, this one function becomes a thousand-line monster that's impossible to test or maintain. You're spending more time writing boilerplate string parsing than actually building features.

Leveraging the Command Framework

The professional way to handle this is to move away from raw events and use the commands.Bot class. This shifts the responsibility of parsing the message from you to the library. Instead of one giant switchboard, you define discrete functions decorated with @bot.command(). This allows you to use Python's type hinting to handle argument conversion automatically.

from discord.ext import commands

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

@bot.command()
async def coffee(ctx, amount: int):
    # The library already checked if 'amount' is an integer
    await ctx.send(f"Logged {amount} coffees!")

@bot.command()
async def stats(ctx):
    await ctx.send("Here are the totals...")

Notice the difference. I didn't have to split the string, I didn't have to wrap the input in a try/except block for the integer conversion, and I didn't have to write a single if statement to route the command. The ctx (context) object replaces the raw message, giving you easier access to the channel, the author, and the server in one neat package.

Where the Trade-off Lies

You might wonder why anyone ever uses on_message. The trade-off is control versus convenience. The command framework is a layer of abstraction. If you need to build a bot that reacts to *every* message (like a profanity filter or a custom auto-responder), the framework won't help you—you'll still need on_message.

However, there's a catch: if you use both, on_message will actually block your commands from running. Because on_message is an event that fires every time, it "consumes" the message. To fix this, you have to explicitly tell the bot to keep processing the message by adding await bot.process_commands(message) at the end of your event handler. It's a small detail, but it's the most common reason people think their commands "stopped working" after adding a custom event.

📋 Practical Task

Build a Team Task-Assigner Bot

Create a Discord bot using the commands.Bot framework that implements a task assignment system. Your bot should have two specific commands:

• !assign [user] [task_name]: This should take a member object and a string, then respond with a confirmation message like: "Task 'Fix CSS' has been assigned to @User!"
• !clear: This should simply respond letting the user know the task list has been wiped.

Requirements:

• Use type hinting in the assign command so that the bot automatically resolves the member mention into a discord.Member object.
• Ensure you are using a command_prefix.
• Implement a custom on_message event that prints the content of every message to the console, but ensure your !assign and !clear commands still function correctly.