Handling Updates

Calling API methods sequentially is cool, but how to react when, for example, a new message arrives? This page deals with updates and how to handle such events in Pyrogram. Let’s have a look at how they work.

Defining Updates

First, let’s define what are these updates. As hinted already, updates are simply events that happen in your Telegram account (incoming messages, new members join, bot button presses, etc…), which are meant to notify you about a new specific state that has changed. These updates are handled by registering one or more callback functions in your app using Handlers.

Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback function will be called back by the framework and its body executed.

Registering a Handler

To explain how handlers work let’s have a look at the most used one, the MessageHandler, which will be in charge for handling Message updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles settings them up once you learn from this section.

Using add_handler()

The add_handler() method takes any handler instance that wraps around your defined callback function and registers it in your Client. Here’s a full example that prints out the content of a message as soon as it arrives:

from pyrogram import Client, MessageHandler


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


app = Client("my_account")

my_handler = MessageHandler(my_function)
app.add_handler(my_handler)

app.run()
  1. Let’s examine these four new pieces. First one: a callback function we defined which accepts two arguments - (client, message). This will be the function that gets executed every time a new message arrives and Pyrogram will call that function by passing the client instance and the new message instance as argument.

    def my_function(client, message):
        print(message)
    
  2. Second one: the MessageHandler. This object tells Pyrogram the function we defined above must only handle updates that are in form of a Message:

    my_handler = MessageHandler(my_function)
    
  3. Third: the method add_handler(). This method is used to actually register the handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase begins.

    app.add_handler(my_handler)
    
  4. Last one, the run() method. What this does is simply call start() and a special method idle() that keeps your main scripts alive until you press CTRL+C; the client will be automatically stopped after that.

    app.run()
    

Using Decorators

All of the above will become quite verbose, especially in case you have lots of handlers to register. A much nicer way to do so is by decorating your callback function with the on_message() decorator.

from pyrogram import Client

app = Client("my_account")


@app.on_message()
def my_handler(client, message):
    print(message)


app.run()

Note

Due to how these decorators work in Pyrogram, they will wrap your defined callback function in a tuple consisting of (handler, group); this will be the value held by your function identifier (e.g.: my_function from the example above).

In case, for some reason, you want to get your own function back after it has been decorated, you need to access my_function[0].callback, that is, the callback field of the handler object which is the first element in the tuple, accessed by bracket notation [0].