class telegram.ext.AIORateLimiter(overall_max_rate=30, overall_time_period=1, group_max_rate=20, group_time_period=60, max_retries=0)[source]

Bases: telegram.ext.BaseRateLimiter

Implementation of BaseRateLimiter using the library aiolimiter.


If you want to use this class, you must install PTB with the optional requirement rate-limiter, i.e.

pip install "python-telegram-bot[rate-limiter]"

The rate limiting is applied by combining two levels of throttling and process_request() roughly boils down to:

async with group_limiter(group_id):
    async with overall_limiter:
        await callback(*args, **kwargs)

Here, group_id is determined by checking if there is a chat_id parameter in the data. The overall_limiter is applied only if a chat_id argument is present at all.


  • Some bot methods accept a chat_id parameter in form of a @username for supergroups and channels. As we can’t know which @username corresponds to which integer chat_id, these will be treated as different groups, which may lead to exceeding the rate limit.

  • As channels can’t be differentiated from supergroups by the @username or integer chat_id, this also applies the group related rate limits to channels.

  • A RetryAfter exception will halt all requests for retry_after + 0.1 seconds. This may be stricter than necessary in some cases, e.g. the bot may hit a rate limit in one group but might still be allowed to send messages in another group.


This class is to be understood as minimal effort reference implementation. If you would like to handle rate limiting in a more sophisticated, fine-tuned way, we welcome you to implement your own subclass of BaseRateLimiter. Feel free to check out the source code of this class for inspiration.

Added in version 20.0.

async initialize()[source]

Does nothing.

async process_request(callback, args, kwargs, endpoint, data, rate_limit_args)[source]

Processes a request by applying rate limiting.

See telegram.ext.BaseRateLimiter.process_request() for detailed information on the arguments.


rate_limit_args (None | int) – If set, specifies the maximum number of retries to be made in case of a RetryAfter exception. Defaults to AIORateLimiter.max_retries.

async shutdown()[source]

Does nothing.