class telegram.ext.BaseHandler(callback, block=True)[source]

Bases: typing.Generic, ABC

The base class for all update handlers. Create custom handlers by inheriting from it.


When setting block to False, you cannot rely on adding custom attributes to telegram.ext.CallbackContext. See its docs for more info.

This class is a Generic class and accepts two type variables:

  1. The type of the updates that this handler will handle. Must coincide with the type of the first argument of callback. check_update() must only accept updates of this type.

  2. The type of the second argument of callback. Must coincide with the type of the parameters handle_update.context and collect_additional_context.context as well as the second argument of callback. Must be either CallbackContext or a subclass of that class.


    For this type variable, one should usually provide a TypeVar that is also used for the mentioned method arguments. That way, a type checker can check whether this handler fits the definition of the Application.

Changed in version 20.0:

  • The attribute run_async is now block.

  • This class was previously named Handler.


The callback function for this handler.


coroutine function


Determines whether the callback will run in a blocking way.




Give a string representation of the handler in the form ClassName[callback=...].

As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().



abstract check_update(update)[source]

This method is called to determine if an update should be handled by this handler instance. It should always be overridden.


Custom updates types can be handled by the application. Therefore, an implementation of this method should always check the type of update.


update (object | telegram.Update) – The update to be tested.


Either None or False if the update should not be handled. Otherwise an object that will be passed to handle_update() and collect_additional_context() when the update gets handled.

collect_additional_context(context, update, application, check_result)[source]

Prepares additional arguments for the context. Override if needed.

async handle_update(update, application, check_result, context)[source]

This method is called if it was determined that an update should indeed be handled by this instance. Calls callback along with its respectful arguments. To work with the telegram.ext.ConversationHandler, this method returns the value returned from callback. Note that it can be overridden if needed by the subclassing handler.