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

Index#

MessageHandler
EditedMessageHandler
DeletedMessagesHandler
CallbackQueryHandler

InlineQueryHandler
ChosenInlineResultHandler
ChatMemberUpdatedHandler
UserStatusHandler

PollHandler
DisconnectHandler
RawUpdateHandler

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.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.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.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.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.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.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.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.

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

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 and Channel 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.