Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# AIORateLimiter

class telegram.ext.AIORateLimiter(overall_max_rate=30, overall_time_period=1, group_max_rate=20, 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.

  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.

  Caution

  This class currently doesn’t take the `allow_paid_broadcast` parameter into account. This means that the rate limiting is applied just like for any other message.

  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.

  Use In

  `telegram.ext.ApplicationBuilder.rate_limiter()`

  See also

  Avoiding Flood Limits

  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.