Update Handlers¶

Handlers are used to instruct Pyrogram about which kind of updates you’d like to handle with your callback functions. For a much more convenient way of registering callback functions have a look at Decorators instead.

from pyrogram import Client
from pyrogram.handlers import MessageHandler

app = Client("my_account")

def dump(client, message):
    print(message)

app.add_handler(MessageHandler(dump))

app.run()

Details¶

class pyrogram.handlers.MessageHandler¶

The Message handler class. Used to handle new messages. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_message() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new Message arrives. It takes (client, message) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
message (Message) – The received message.

class pyrogram.handlers.EditedMessageHandler¶

The EditedMessage handler class. Used to handle edited messages.: It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_edited_message() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new edited message arrives. It takes (client, message) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
edited_message (Message) – The received edited message.

class pyrogram.handlers.DeletedMessagesHandler¶

The deleted messages handler class. Used to handle deleted messages coming from any chat (private, group, channel). It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_deleted_messages() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when one or more messages have been deleted. It takes (client, messages) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
messages (List of Message) – The deleted messages, as list.

class pyrogram.handlers.BusinessMessageHandler¶

The BusinessMessage handler class. Used to handle new business messages.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_business_message() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new Message arrives. It takes (client, message) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
message (Message) – The received message.

class pyrogram.handlers.EditedBusinessMessageHandler¶

The EditedBusinessMessage handler class. Used to handle edited business messages.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_edited_business_message() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new edited message arrives. It takes (client, message) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
edited_message (Message) – The received edited message.

class pyrogram.handlers.DeletedBusinessMessagesHandler¶

The deleted business messages handler class. Used to handle deleted messages coming from business connection.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_deleted_business_messages() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when one or more messages have been deleted. It takes (client, messages) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of messages to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
messages (List of Message) – The deleted messages, as list.

class pyrogram.handlers.BusinessConnectionHandler¶

The BusinessConnection handler class. Used to handle changes in business connections.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_business_connection() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a business connection has changed. It takes (client, update) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
update (BusinessConnection) – Information about business connection.

class pyrogram.handlers.CallbackQueryHandler¶

The CallbackQuery handler class. Used to handle callback queries coming from inline buttons. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_callback_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new CallbackQuery arrives. It takes (client, callback_query) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of callback queries to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
callback_query (CallbackQuery) – The received callback query.

class pyrogram.handlers.ChatBoostHandler¶

The ChatBoost handler class. Used to handle applied chat boosts. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_chat_boost() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new boost applied. It takes (client, boost) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
boost (ChatBoost) – The applied chat boost.

class pyrogram.handlers.ChatJoinRequestHandler¶

The ChatJoinRequest handler class. Used to handle join chat requests. It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_chat_join_request() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new ChatJoinRequest event arrives. It takes (client, chat_join_request) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
chat_join_request (ChatJoinRequest) – The received chat join request.

class pyrogram.handlers.ChatMemberUpdatedHandler¶

The ChatMemberUpdated handler class. Used to handle changes in the status of a chat member. It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_chat_member_updated() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new ChatMemberUpdated event arrives. It takes (client, chat_member_updated) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
chat_member_updated (ChatMemberUpdated) – The received chat member update.

class pyrogram.handlers.ChosenInlineResultHandler¶

The ChosenInlineResultHandler handler class. Used to handle chosen inline results coming from inline queries. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_chosen_inline_result() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new chosen inline result arrives. It takes (client, chosen_inline_result) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of chosen inline results to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
chosen_inline_result (ChosenInlineResult) – The received chosen inline result.

class pyrogram.handlers.InlineQueryHandler¶

The InlineQuery handler class. Used to handle inline queries. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_inline_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new InlineQuery arrives. It takes (client, inline_query) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of inline queries to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the inline query handler.
inline_query (InlineQuery) – The received inline query.

class pyrogram.handlers.MessageReactionCountHandler¶

The MessageReactionCount handler class. Used to handle changes in the anonymous reaction of a message.

It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_message_reaction_count() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new MessageReactionCount event arrives. It takes (client, reactions) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
reactions (MessageReactionCountUpdated) – The received message reaction count update.

class pyrogram.handlers.MessageReactionHandler¶

The MessageReaction handler class. Used to handle changes in the reaction of a message.

It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_message_reaction() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new MessageReaction event arrives. It takes (client, reactions) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
reactions (MessageReactionUpdated) – The received message reaction update.

class pyrogram.handlers.PollHandler¶

The Poll handler class. Used to handle polls updates.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_poll() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new poll update arrives. It takes (client, poll) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of polls to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the poll handler.
poll (Poll) – The received poll.

class pyrogram.handlers.PreCheckoutQueryHandler¶

The PreCheckoutQueryHandler handler class. Used to handle pre-checkout queries coming from buy buttons. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_pre_checkout_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new PreCheckoutQuery arrives. It takes (client, pre_checkout_query) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of callback queries to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the message handler.
pre_checkout_query (PreCheckoutQuery) – The received callback query.

class pyrogram.handlers.PurchasedPaidMediaHandler¶

The PurchasedPaidMedia handler class. Used to handle purchased paid medias. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_purchased_paid_media() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a paid media purchased. It takes (client, update) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
update (PurchasedPaidMedia) – Information about who bought paid media.

class pyrogram.handlers.ShippingQueryHandler¶

The ShippingQueryHandler handler class. Used to handle shipping queries coming only from invoice buttons with flexible price.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_shipping_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new PreCheckoutQuery arrives. It takes (client, query) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of callback queries to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the shipping query handler.
query (ShippingQuery) – New incoming shipping query. Only for invoices with flexible price.

class pyrogram.handlers.StoryHandler¶

The Story handler class. Used to handle new stories. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_story() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new Stories arrives. It takes (client, story) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of stories to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the story handler.
story (Story) – The received story.

class pyrogram.handlers.UserStatusHandler¶

The UserStatus handler class. Used to handle user status updates (user going online or offline). It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_user_status() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new user status update arrives. It takes (client, user) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of users to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the user status handler.
user (User) – The user containing the updated status.

class pyrogram.handlers.StartHandler¶

The Start handler class. Used to handle client start. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_start() decorator.

Parameters:: callback (Callable) – Pass a function that will be called when a client starts. It takes (client) as positional argument (look at the section below for a detailed description).
Other Parameters:: client (Client) – The Client itself. Useful, for example, when you want to change the proxy before a new connection is established.

class pyrogram.handlers.StopHandler¶

The Stop handler class. Used to handle client stop. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_stop() decorator.

Parameters:: callback (Callable) – Pass a function that will be called when a client stops. It takes (client) as positional argument (look at the section below for a detailed description).
Other Parameters:: client (Client) – The Client itself. Useful, for example, when you want to change the proxy before a new connection is established.

class pyrogram.handlers.ConnectHandler¶

The Connect handler class. Used to handle connections. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_connect() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a connection occurs. It takes (client) as positional argument (look at the section below for a detailed description).

Other Parameters:

client (Client) – The Client itself. Useful, for example, when you want to change the proxy before a new connection is established.
session (Session) – The Session used for the connection.

class pyrogram.handlers.DisconnectHandler¶

The Disconnect handler class. Used to handle disconnections. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_disconnect() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a disconnection occurs. It takes (client) as positional argument (look at the section below for a detailed description).

Other Parameters:

client (Client) – The Client itself. Useful, for example, when you want to change the proxy before a new connection is established.
session (Session) – The Session used for the connection.

class pyrogram.handlers.ErrorHandler¶

The Error handler class. Used to handle unexpected errors.

It is intended to be used with add_handler().

For a more convenient way to register this handler, see the on_error() decorator.

Parameters:

callback (Callable) – A function that will be called whenever an unexpected error is raised. It takes the following positional arguments: (exception, handler, client, *args).
exceptions (Exception | List of Exception, optional) – An exception type or a sequence of exception types that this handler should handle. If None, the handler will catch any exception that is a subclass of Exception.
filters (Filter, optional) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other parameters passed to the callback:

client (Client):: The Client instance, useful when calling other API methods inside the error handler.
exception (Exception):: The Exception instance that was raised.
handler (Handler):: The Handler instance from which the exception was raised.
update (Update):: The received update, which can be one of the many single Updates listed in the Update base type.
users (dict):: Dictionary of all User mentioned in the update. You can access extra info about the user (such as first_name, last_name, etc…) by using the IDs you find in the update argument (e.g.: users[1768841572]).
chats (dict):: Dictionary of all Chat mentioned in the update. You can access extra info about the chat (such as title, participants_count, etc…) by using the IDs you find in the update argument (e.g.: chats[1701277281]).

class pyrogram.handlers.ManagedBotUpdatedHandler¶

The ManagedBotUpdated handler class. Used to handle new managed bot creation updates. It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_managed_bot() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new managed bot creation update arrives. It takes (client, managed_bot_updated) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of users to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the handler.
managed_bot_updated (ManagedBotUpdated) – A new bot was created to be managed by the bot or token of a bot was changed.

class pyrogram.handlers.RawUpdateHandler¶

The Raw Update handler class. Used to handle raw updates. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_raw_update() decorator.

Parameters:

callback (Callable) – A function that will be called when a new update is received from the server. It takes (client, update, users, chats) as positional arguments (look at the section below for a detailed description).
filters (Filters) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other Parameters:

client (Client) – The Client itself, useful when you want to call other API methods inside the update handler.
update (Update) – The received update, which can be one of the many single Updates listed in the Update base type.
users (dict) – Dictionary of all User mentioned in the update. You can access extra info about the user (such as first_name, last_name, etc…) by using the IDs you find in the update argument (e.g.: users[1768841572]).
chats (dict) – Dictionary of all Chat mentioned in the update. You can access extra info about the chat (such as title, participants_count, etc…) by using the IDs you find in the update argument (e.g.: chats[1701277281]).

Note

The following Empty or Forbidden types may exist inside the users and chats dictionaries. They mean you have been blocked by the user or banned from the group/channel.

Update Handlers¶

Index¶

Details¶