Router

Imports:

  • Recommended: from aiogram import Router
  • Real location: from aiogram.dispatcher.dispatcher import Router

Initializer specification

Argument Type Description
use_builtin_filters bool Register builtin filters in filters factory. Has no effect when filters is already registered in parent router. (default: True)

Example:

router = Router()

Router can route update and it nested update types like messages, callback query, polls and all other event types.

Event observers

Here is used event-observer pattern. (Read more on observer page >>)

Event handlers can be registered in observer by two ways:

  1. By observer method - router.<event_type>.register(handler, <filters, ...>)
  2. By decorator - @router.<event_type>(<filters, ...>)

Warning

All handlers is always should be an asynchronous. Name of handler function is not important. Event argument name is also is not important but is recommended to don't overlap the name with contextual data in due to function can not accept two arguments with the same name.

Here is list of available observers and examples how to register handlers (In examples used only @decorator-style):

Update

@router.update()
async def message_handler(update: types.Update) -> Any: pass

Should be used for handling updates. By default Router is already have an update handler which route all event types to another observers.

Message

@router.message()
async def message_handler(message: types.Message) -> Any: pass

Is useful for handling message

Edited message

@router.edited_message()
async def edited_message_handler(edited_message: types.Message) -> Any: pass

Is useful for handling edited messages

Channel post

@router.channel_post()
async def channel_post_handler(channel_post: types.Message) -> Any: pass

Is useful for handling channel posts

Edited channel post

@router.edited_channel_post()
async def edited_channel_post_handler(edited_channel_post: types.Message) -> Any: pass

Is useful for handling edited channel posts

Inline query

@router.inline_query()
async def inline_query_handler(inline_query: types.Message) -> Any: pass

Is useful for handling inline query

Chosen inline query

@router.chosen_inline_result()
async def chosen_inline_result_handler(chosen_inline_result: types.ChosenInlineResult) -> Any: pass

Is useful for handling chosen inline query

Callback query

@router.callback_query()
async def callback_query_handler(callback_query: types.CallbackQuery) -> Any: pass

Is useful for handling callback query's

Shipping query

@router.shipping_query()
async def shipping_query_handler(shipping_query: types.ShippingQuery) -> Any: pass

Is useful for handling shipping query

Pre checkout query

@router.pre_checkout_query()
async def pre_checkout_query_handler(pre_checkout_query: types.PreCheckoutQuery) -> Any: pass

Is useful for handling pre-checkout query

Poll

@router.poll()
async def poll_handler(poll: types.Poll) -> Any: pass

Is useful for handling polls

Poll answer

@router.poll_answer()
async def poll_answer_handler(poll_answer: types.PollAnswer) -> Any: pass

Is useful for handling polls answers

Errors

@router.errors()
async def error_handler(exception: Exception) -> Any: pass

Is useful for handling errors from other handlers

Nested routers

Warning

Routers by the way can be nested to an another routers with some limitations:

  1. Router CAN NOT include itself
  2. Routers CAN NOT be used for circular including (router 1 include router 2, router 2 include router 3, router 3 include router 1)

Example:

# module_1.py
router1 = Router()
router2 = Router()

router2.include_router(router1)

How it works?

For example dispatcher has 2 routers, last one router is also have one nested router:

nested routers example (Click on image to zoom it)

In this case update propagation flow will have form:

update propagation flow (Click on image to zoom it)