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 DeletedMessagesHandler CallbackQueryHandler

InlineQueryHandler ChosenInlineResultHandler UserStatusHandler

PollHandler DisconnectHandler RawUpdateHandler

---

Details

class pyrogram.handlers.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.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_query() 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.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 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.

• UserEmpty

• ChatEmpty

• ChatForbidden

• ChannelForbidden