Dispatcher

Basics

Coming soon…

Available handlers

Coming soon…

Handler class

Coming soon…

Features

Coming soon…

Dispatcher class

class aiogram.Dispatcher(bot, loop=None, storage: Optional[aiogram.dispatcher.storage.BaseStorage] = None, run_tasks_by_default: bool = False, throttling_rate_limit=0.1, no_throttle_error=False, filters_factory=None)[source]

Bases: aiogram.utils.mixins.DataMixin, aiogram.utils.mixins.ContextInstanceMixin

Simple Updates dispatcher

It will process incoming updates: messages, edited messages, channel posts, edited channel posts, inline queries, chosen inline results, callback queries, shipping queries, pre-checkout queries.

async skip_updates()[source]

You can skip old incoming updates from queue. This method is not recommended to use if you use payments or you bot has high-load.

Returns

None

async process_updates(updates, fast: Optional[bool] = True)[source]

Process list of updates

Parameters

  • updates –

  • fast –

Returns

async process_update(update: aiogram.types.update.Update)[source]

Process single update object

Parameters

update –

Returns

async reset_webhook(check=True) → bool[source]

Reset webhook

Parameters

check – check before deleting

Returns

async start_polling(timeout=20, relax=0.1, limit=None, reset_webhook=None, fast: Optional[bool] = True, error_sleep: int = 5)[source]

Start long-polling

Parameters

  • timeout –

  • relax –

  • limit –

  • reset_webhook –

  • fast –

Returns

stop_polling()[source]

Break long-polling process.

Returns

async wait_closed()[source]

Wait for the long-polling to close

Returns

is_polling()[source]

Check if polling is enabled

Returns

register_message_handler(callback, *custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Register handler for message

# This handler works only if state is None (by default).
dp.register_message_handler(cmd_start, commands=['start', 'about'])
dp.register_message_handler(entry_point, commands=['setup'])

# This handler works only if current state is "first_step"
dp.register_message_handler(step_handler_1, state="first_step")

# If you want to handle all states by one handler, use `state="*"`.
dp.register_message_handler(cancel_handler, commands=['cancel'], state="*")
dp.register_message_handler(cancel_handler, lambda msg: msg.text.lower() == 'cancel', state="*")
Parameters

  • callback –

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • custom_filters – list of custom filters

  • kwargs –

  • state –

Returns

decorated function

message_handler(*custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Decorator for message handler

Examples:

Simple commands handler:

@dp.message_handler(commands=['start', 'welcome', 'about'])
async def cmd_handler(message: types.Message):

Filter messages by regular expression:

@dp.message_handler(rexexp='^[a-z]+-[0-9]+')
async def msg_handler(message: types.Message):

Filter messages by command regular expression:

@dp.message_handler(filters.RegexpCommandsFilter(regexp_commands=['item_([0-9]*)']))
async def send_welcome(message: types.Message):

Filter by content type:

@dp.message_handler(content_types=ContentType.PHOTO | ContentType.DOCUMENT)
async def audio_handler(message: types.Message):

Filter by custom function:

@dp.message_handler(lambda message: message.text and 'hello' in message.text.lower())
async def text_handler(message: types.Message):

Use multiple filters:

@dp.message_handler(commands=['command'], content_types=ContentType.TEXT)
async def text_handler(message: types.Message):

Register multiple filters set for one handler:

@dp.message_handler(commands=['command'])
@dp.message_handler(lambda message: demojize(message.text) == ':new_moon_with_face:')
async def text_handler(message: types.Message):

This handler will be called if the message starts with ‘/command’ OR is some emoji

By default content_type is ContentType.TEXT

Parameters

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • custom_filters – list of custom filters

  • kwargs –

  • state –

  • run_task – run callback in task (no wait results)

Returns

decorated function

register_edited_message_handler(callback, *custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Register handler for edited message

Parameters

  • callback –

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

edited_message_handler(*custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Decorator for edited message handler

You can use combination of different handlers

@dp.message_handler()
@dp.edited_message_handler()
async def msg_handler(message: types.Message):
Parameters

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

register_channel_post_handler(callback, *custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Register handler for channel post

Parameters

  • callback –

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

channel_post_handler(*custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Decorator for channel post handler

Parameters

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

register_edited_channel_post_handler(callback, *custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Register handler for edited channel post

Parameters

  • callback –

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

edited_channel_post_handler(*custom_filters, commands=None, regexp=None, content_types=None, state=None, run_task=None, **kwargs)[source]

Decorator for edited channel post handler

Parameters

  • commands – list of commands

  • regexp – REGEXP

  • content_types – List of content types.

  • custom_filters – list of custom filters

  • state –

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

register_inline_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)[source]

Register handler for inline query

Example:

dp.register_inline_handler(some_inline_handler, lambda inline_query: True)
Parameters

  • callback –

  • custom_filters – list of custom filters

  • state –

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

inline_handler(*custom_filters, state=None, run_task=None, **kwargs)[source]

Decorator for inline query handler

Example:

@dp.inline_handler(lambda inline_query: True)
async def some_inline_handler(inline_query: types.InlineQuery)
Parameters

  • state –

  • custom_filters – list of custom filters

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

decorated function

register_chosen_inline_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)[source]

Register handler for chosen inline query

Example:

dp.register_chosen_inline_handler(some_chosen_inline_handler, lambda chosen_inline_query: True)
Parameters

  • callback –

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

chosen_inline_handler(*custom_filters, state=None, run_task=None, **kwargs)[source]

Decorator for chosen inline query handler

Example:

@dp.chosen_inline_handler(lambda chosen_inline_query: True)
async def some_chosen_inline_handler(chosen_inline_query: types.ChosenInlineResult)
Parameters

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

Returns

register_callback_query_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)[source]

Register handler for callback query

Example:

dp.register_callback_query_handler(some_callback_handler, lambda callback_query: True)
Parameters

  • callback –

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

callback_query_handler(*custom_filters, state=None, run_task=None, **kwargs)[source]

Decorator for callback query handler

Example:

@dp.callback_query_handler(lambda callback_query: True)
async def some_callback_handler(callback_query: types.CallbackQuery)
Parameters

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

register_shipping_query_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)[source]

Register handler for shipping query

Example:

dp.register_shipping_query_handler(some_shipping_query_handler, lambda shipping_query: True)
Parameters

  • callback –

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

shipping_query_handler(*custom_filters, state=None, run_task=None, **kwargs)[source]

Decorator for shipping query handler

Example:

@dp.shipping_query_handler(lambda shipping_query: True)
async def some_shipping_query_handler(shipping_query: types.ShippingQuery)
Parameters

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

register_pre_checkout_query_handler(callback, *custom_filters, state=None, run_task=None, **kwargs)[source]

Register handler for pre-checkout query

Example:

dp.register_pre_checkout_query_handler(some_pre_checkout_query_handler, lambda shipping_query: True)
Parameters

  • callback –

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

pre_checkout_query_handler(*custom_filters, state=None, run_task=None, **kwargs)[source]

Decorator for pre-checkout query handler

Example:

@dp.pre_checkout_query_handler(lambda shipping_query: True)
async def some_pre_checkout_query_handler(shipping_query: types.ShippingQuery)
Parameters

  • state –

  • custom_filters –

  • run_task – run callback in task (no wait results)

  • kwargs –

register_errors_handler(callback, *custom_filters, exception=None, run_task=None, **kwargs)[source]

Register handler for errors

Parameters

  • callback –

  • exception – you can make handler for specific errors type

  • run_task – run callback in task (no wait results)

errors_handler(*custom_filters, exception=None, run_task=None, **kwargs)[source]

Decorator for errors handler

Parameters

  • exception – you can make handler for specific errors type

  • run_task – run callback in task (no wait results)

Returns

current_state(*, chat: Union[str, int, None] = None, user: Union[str, int, None] = None) → aiogram.dispatcher.storage.FSMContext[source]

Get current state for user in chat as context

with dp.current_state(chat=message.chat.id, user=message.user.id) as state:
    pass

state = dp.current_state()
state.set_state('my_state')
Parameters

  • chat –

  • user –

Returns

async throttle(key, *, rate=None, user=None, chat=None, no_error=None) → bool[source]

Execute throttling manager. Returns True if limit has not exceeded otherwise raises ThrottleError or returns False

Parameters

  • key – key in storage

  • rate – limit (by default is equal to default rate limit)

  • user – user id

  • chat – chat id

  • no_error – return boolean value instead of raising error

Returns

bool

async check_key(key, chat=None, user=None)[source]

Get information about key in bucket

Parameters

  • key –

  • chat –

  • user –

Returns

async release_key(key, chat=None, user=None)[source]

Release blocked key

Parameters

  • key –

  • chat –

  • user –

Returns

async_task(func)[source]

Execute handler as task and return None. Use this decorator for slow handlers (with timeouts)

@dp.message_handler(commands=['command'])
@dp.async_task
async def cmd_with_timeout(message: types.Message):
    await asyncio.sleep(120)
    return SendMessage(message.chat.id, 'KABOOM').reply(message)
Parameters

func –

Returns