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(regexp='^[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_poll_handler(callback, *custom_filters, run_task=None, **kwargs)[source]

Register handler for poll

Example:

dp.register_poll_handler(some_poll_handler)
Parameters
  • callback

  • custom_filters

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

  • kwargs

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

Decorator for poll handler

Example:

@dp.poll_handler()
async def some_poll_handler(poll: types.Poll)
Parameters
  • custom_filters

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

  • kwargs

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

Register handler for poll_answer

Example:

dp.register_poll_answer_handler(some_poll_answer_handler)
Parameters
  • callback

  • custom_filters

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

  • kwargs

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

Decorator for poll_answer handler

Example:

@dp.poll_answer_handler()
async def some_poll_answer_handler(poll_answer: types.PollAnswer)
Parameters
  • 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: Optional[Union[str, int]] = None, user: Optional[Union[str, int]] = 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_id=None, chat_id=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_id – user id

  • chat_id – chat id

  • no_error – return boolean value instead of raising error

Returns

bool

async check_key(key, chat_id=None, user_id=None)[source]

Get information about key in bucket

Parameters
  • key

  • chat_id

  • user_id

Returns

async release_key(key, chat_id=None, user_id=None)[source]

Release blocked key

Parameters
  • key

  • chat_id

  • user_id

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

throttled(on_throttled: Optional[Callable] = None, key=None, rate=None, user_id=None, chat_id=None)[source]

Meta-decorator for throttling. Invokes on_throttled if the handler was throttled.

Example:

async def handler_throttled(message: types.Message, **kwargs):
    await message.answer("Throttled!")

@dp.throttled(handler_throttled)
async def some_handler(message: types.Message):
    await message.answer("Didn't throttled!")
Parameters
  • on_throttled – the callable object that should be either a function or return a coroutine

  • key – key in storage

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

  • user_id – user id

  • chat_id – chat id

Returns

decorator

bind_filter(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter], validator: Optional[Callable] = None, event_handlers: Optional[List[aiogram.dispatcher.handler.Handler]] = None, exclude_event_handlers: Optional[Iterable[aiogram.dispatcher.handler.Handler]] = None)[source]

Register filter

Parameters
  • callback – callable or subclass of AbstractFilter

  • validator – custom validator.

  • event_handlers – list of instances of Handler

  • exclude_event_handlers – list of excluded event handlers (Handler)

unbind_filter(callback: Union[Callable, aiogram.dispatcher.filters.filters.AbstractFilter])[source]

Unregister filter

Parameters

callback – callable of subclass of AbstractFilter

setup_middleware(middleware)[source]

Setup middleware

Parameters

middleware

Returns