Crafting aiogram 3 Filters for Specific Command Handlers

What will you learn?

In this tutorial, you will master the art of creating custom filters in aiogram 3 to fine-tune your Telegram bot’s message handlers. You will learn how to make your bot respond exclusively to specific commands or disregard command messages altogether, ensuring precise and tailored bot behavior.

Introduction to the Problem and Solution

When developing Telegram bots using aiogram, a powerful asynchronous framework in Python, you may encounter scenarios where you need to customize your bot’s message handlers. This customization could involve activating handlers only for certain commands or excluding command messages entirely. By implementing custom filters in aiogram 3, you can control when a handler should be triggered based on specific criteria.

To address this challenge effectively, we will explore the process of crafting custom filters using aiogram 3’s robust filtering system. This involves understanding the underlying mechanisms of filters within the framework and applying our logic to define when a handler should be executed. We will start by setting up a basic bot structure and then introduce a specialized filter for handling specific commands with precision.


from aiogram import Bot, Dispatcher, types
from aiogram.types import Message
from aiogram.utils import executor

bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

class CommandFilter:
    def __init__(self, command):
        self.command = f"/{command}"

    async def __call__(self, message: types.Message):
        return message.text.startswith(self.command)

async def handle_start_command(message: Message):
    await message.answer("Welcome!")

if __name__ == "__main__":

# Copyright PHD


The provided solution showcases the flexibility of aiogram by creating a custom filter named CommandFilter. Here is a breakdown of the key components:

  • CommandFilter Class: Represents our custom filter that checks if an incoming message starts with a specified command.
  • __init__ Method: Initializes instances of CommandFilter, ensuring compatibility with Telegram’s command format.
  • __call__ Method: Allows instances of CommandFilter to be called and returns True if the incoming message matches the specified command.
  • Handler Registration: The decorator @dp.message_handler(CommandFilter(command=”start”)) associates handle_start_command() as a response specifically for /start.

By implementing this approach, you can precisely control which messages trigger specific handlers based on predefined conditions, enabling effective differentiation between various commands or exclusion of unwanted messages.

    1. How can I modify my bot not to listen to any commands? To achieve this, avoid using any specific command-related filters or conditions that match against commands in your handlers.

    2. Can I use multiple custom filters together? Yes! Aiogram supports chaining multiple filters either by listing them within the same decorator call or stacking multiple decorators.

    3. Is it possible to apply these filters globally? While filters are typically applied at the handler level, applying them globally would require overriding default dispatcher behavior�making it more complex beyond basic usage patterns.

    4. How do I make my filter case-insensitive? You can modify your CommandFilter.__call__() method logic to compare lowercased versions of user input and specified commands for case insensitivity.

    5. Can this method work with non-command messages? Absolutely! Customizing your filter allows you to capture any pattern you define, not limited to just messages starting with /commands.

    6. What other kinds of filters can I create? The possibilities are vast; from user ID-based permissions to regex-patterns capturing text structures�you have the freedom to tailor handlers very precisely.


By harnessing aiogram’s extensible capabilities through crafting customized filters like “CommandFitler,” developers can exert precise control over their bots’ responsiveness. This ensures that actions align closely with users’ interactions, promoting relevance and efficiency throughout all engagements�a valuable asset for mastering effective bot design and deployment strategies.

Leave a Comment