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, MessageHandler

app = Client("my_account")


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


app.add_handler(MessageHandler(dump))

app.run()

Details

class pyrogram.MessageHandler

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

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

The Disconnect handler class. Used to handle disconnections. It is intended to be used with :meth:~Client.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

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.