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[BaseStorage] = None, run_tasks_by_default: bool = False, throttling_rate_limit=0.1, no_throttle_error=False, filters_factory=None)[source]
Bases:
DataMixin
,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 for using in production.
Note that the webhook will be deleted!
- async process_updates(updates, fast: bool = True)[source]
Process list of updates
- Parameters
updates –
fast –
- Returns
- async process_update(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: bool = True, error_sleep: int = 5, allowed_updates: Optional[List[str]] = None)[source]
Start long-polling
- Parameters
timeout –
relax –
limit –
reset_webhook –
fast –
error_sleep –
allowed_updates –
- 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_result: 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_result: True) async def some_chosen_inline_handler(chosen_inline_result: 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_my_chat_member_handler(callback: Callable, *custom_filters, run_task: Optional[bool] = None, **kwargs) None [source]
Register handler for my_chat_member
Example:
dp.register_my_chat_member_handler(some_my_chat_member_handler)
- Parameters
callback –
custom_filters –
run_task – run callback in task (no wait results)
kwargs –
- my_chat_member_handler(*custom_filters, run_task=None, **kwargs)[source]
Decorator for my_chat_member handler
Example:
@dp.my_chat_member_handler() async def some_handler(my_chat_member: types.ChatMemberUpdated)
- Parameters
custom_filters –
run_task – run callback in task (no wait results)
kwargs –
- register_chat_member_handler(callback: Callable, *custom_filters, run_task: Optional[bool] = None, **kwargs) None [source]
Register handler for chat_member
Example:
dp.register_chat_member_handler(some_chat_member_handler)
- Parameters
callback –
custom_filters –
run_task – run callback in task (no wait results)
kwargs –
- chat_member_handler(*custom_filters, run_task=None, **kwargs)[source]
Decorator for chat_member handler
Example:
@dp.chat_member_handler() async def some_handler(chat_member: types.ChatMemberUpdated)
- Parameters
custom_filters –
run_task – run callback in task (no wait results)
kwargs –
- register_chat_join_request_handler(callback: Callable, *custom_filters, run_task: Optional[bool] = None, **kwargs) None [source]
Register handler for chat_join_request
Example:
dp.register_chat_join_request(some_chat_join_request)
- Parameters
callback –
custom_filters –
run_task – run callback in task (no wait results)
kwargs –
- chat_join_request_handler(*custom_filters, run_task=None, **kwargs)[source]
Decorator for chat_join_request handler
Example:
@dp.chat_join_request() async def some_handler(chat_member: types.ChatJoinRequest)
- 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) 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, AbstractFilter], validator: Optional[Callable] = None, event_handlers: Optional[List[Handler]] = None, exclude_event_handlers: Optional[Iterable[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, AbstractFilter])[source]
Unregister filter
- Parameters
callback – callable of subclass of
AbstractFilter