Handlers

MessageHandler The Message handler class.
DeletedMessagesHandler The deleted Messages handler class.
CallbackQueryHandler The CallbackQuery handler class.
UserStatusHandler The UserStatus handler class.
DisconnectHandler The Disconnect handler class.
RawUpdateHandler The Raw Update handler class.
class pyrogram.MessageHandler(callback: callable, filters=None)

The Message handler class. Used to handle text, media and service 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_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.DeletedMessagesHandler(callback: callable, filters=None)

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 (Messages) – The deleted messages.
class pyrogram.CallbackQueryHandler(callback: callable, filters=None)

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.UserStatusHandler(callback: callable, filters=None)

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 UserStatus update arrives. It takes (client, user_status) 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 user status handler.
  • user_status (UserStatus) – The received UserStatus update.
class pyrogram.DisconnectHandler(callback: callable)

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.RawUpdateHandler(callback: callable)

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 updates field you see in the Update 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.