Skip to content
Back to top
View this page

# AIORateLimiter

class telegram.ext.AIORateLimiter(overall_max_rate=<FloodLimit.MESSAGES_PER_SECOND>, overall_time_period=1, group_max_rate=<FloodLimit.MESSAGES_PER_MINUTE_PER_GROUP>, group_time_period=60, max_retries=0)

  Bases: `telegram.ext.BaseRateLimiter`

  Implementation of `BaseRateLimiter` using the library aiolimiter.

  Important

  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.

  Attention

  - 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 or with `allow_paid_broadcast` set to `True`.

  Tip

  With Bot API 7.1 (PTB v27.1), Telegram introduced the parameter `allow_paid_broadcast`. This allows bots to send up to `1000` messages per second by paying a fee in Telegram Stars.

  Changed in version 21.11: This class automatically takes the `allow_paid_broadcast` parameter into account and throttles the requests accordingly.

  Note

  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.

  See also

  Avoiding Flood Limits

  Use In

  `telegram.ext.ApplicationBuilder.rate_limiter()`

  Available In

  `telegram.ext.ExtBot.rate_limiter`

  Added in version 20.0.

  Parameters:

    - overall_max_rate (`float`) – The maximum number of requests allowed for the entire bot per `overall_time_period`. When set to 0, no rate limiting will be applied. Defaults to `30`.

    - overall_time_period (`float`) – The time period (in seconds) during which the `overall_max_rate` is enforced. When set to 0, no rate limiting will be applied. Defaults to `1`.

    - group_max_rate (`float`) – The maximum number of requests allowed for requests related to groups and channels per `group_time_period`. When set to 0, no rate limiting will be applied. Defaults to `20`.

    - group_time_period (`float`) – The time period (in seconds) during which the `group_max_rate` is enforced. When set to 0, no rate limiting will be applied. Defaults to `60`.

    - max_retries (`int`) – The maximum number of retries to be made in case of a `RetryAfter` exception. If set to 0, no retries will be made. Defaults to `0`.

  async initialize()

    Does nothing.

  async process_request(callback, args, kwargs, endpoint, data, rate_limit_args)

    Processes a request by applying rate limiting.

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

    Parameters:

      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()

    Does nothing.