Router#

class aiogram.dispatcher.router.Router(*, name: Optional[str] = None)[source]#

Bases: object

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

Event handlers can be registered in observer by two ways:

  • By observer method - router.<event_type>.register(handler, <filters, ...>)

  • By decorator - @router.<event_type>(<filters, ...>)

__init__(*, name: Optional[str] = None) None[source]#
Parameters:

name – Optional router name, can be useful for debugging

include_router(router: Router) Router[source]#

Attach another router.

Parameters:

router

Returns:

Event observers#

Warning

All handlers always should be asynchronous. The name of the handler function is not important. The event argument name is also not important but it is recommended to not overlap the name with contextual data in due to function can not accept two arguments with the same name.

Here is the list of available observers and examples of how to register handlers

In these examples only decorator-style registering handlers are used, but if you don’t like @decorators just use <event type>.register(...) method instead.

Update#

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

Note

By default Router already has an update handler which route all event types to another observers.

Message#

Attention

Be attentive with filtering this event

You should expect that this event can be with different sets of attributes in different cases

(For example text, sticker and document are always of different content types of message)

Recommended way to check field availability before usage, for example via magic filter: F.text to handle text, F.sticker to handle stickers only and etc.

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

Edited message#

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

Channel post#

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

Edited channel post#

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

Inline query#

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

Chosen inline query#

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

Callback query#

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

Shipping query#

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

Pre checkout query#

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

Poll#

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

Poll answer#

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

Errors#

@router.errors()
async def error_handler(exception: ErrorEvent) -> 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 1. 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_2.py#
router2 = Router()

@router2.message()
...
module_2.py#
from module_2 import router2


router1 = Router()
router1.include_router(router2)

How it works?#

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

Nested routers example

In this case update propagation flow will have form:

Nested routers example