Update Handlers¶

A handler is the object that binds a callback function to a kind of update. Every on_message()-style decorator builds one of these and registers it for you; add_handler() takes one directly, which is what you want when handlers are built at runtime.

from pyrogram import Client, filters
from pyrogram.handlers import MessageHandler


async def echo(client, message):
    await message.reply(message.text)


app = Client("my_account")
app.add_handler(MessageHandler(echo, filters.text & filters.private))
app.run()

Every handler takes the same two arguments: a callback and an optional filters. The callback’s second parameter is the parsed update, and which type that is depends on the handler — a Message for MessageHandler, a CallbackQuery for CallbackQueryHandler, and so on.

See More on Updates for handler groups, propagation and priority.

Messages¶

class pyrogram.handlers.MessageHandler[source]¶

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[source]¶

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[source]¶

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.MessageReactionHandler[source]¶

The MessageReaction handler class. Used to handle changes in the reaction of a message.

It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_message_reaction() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new MessageReaction event arrives. It takes (client, reactions) 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.
reactions (MessageReactionUpdated) – The received message reaction update.

class pyrogram.handlers.MessageReactionCountHandler[source]¶

The MessageReactionCount handler class. Used to handle changes in the anonymous reaction of a message.

It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_message_reaction_count() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new MessageReactionCount event arrives. It takes (client, reactions) 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.
reactions (MessageReactionCountUpdated) – The received message reaction count update.

class pyrogram.handlers.PollHandler[source]¶

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.StoryHandler[source]¶

The Story handler class. Used to handle new stories. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_story() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new Stories arrives. It takes (client, story) 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 stories 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 story handler.
story (Story) – The received story.

Business connections¶

class pyrogram.handlers.BusinessConnectionHandler[source]¶

The BusinessConnection handler class. Used to handle changes in business connections.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_business_connection() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a business connection has changed. It takes (client, update) 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.
update (BusinessConnection) – Information about business connection.

class pyrogram.handlers.BusinessMessageHandler[source]¶

The BusinessMessage handler class. Used to handle new business messages.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_business_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.EditedBusinessMessageHandler[source]¶

The EditedBusinessMessage handler class. Used to handle edited business 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_business_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.DeletedBusinessMessagesHandler[source]¶

The deleted business messages handler class. Used to handle deleted messages coming from business connection.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_deleted_business_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.

Bots¶

class pyrogram.handlers.CallbackQueryHandler[source]¶

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[source]¶

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[source]¶

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.GuestMessageHandler[source]¶

The Guest Message handler class. Used to handle guest messages. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_guest_message() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new guest 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.ManagedBotUpdatedHandler[source]¶

The ManagedBotUpdated handler class. Used to handle new managed bot creation updates. It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_managed_bot() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new managed bot creation update arrives. It takes (client, managed_bot_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 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 handler.
managed_bot_updated (ManagedBotUpdated) – A new bot was created to be managed by the bot or token of a bot was changed.

class pyrogram.handlers.StartHandler[source]¶

The Start handler class. Used to handle client start. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_start() decorator.

Parameters:: callback (Callable) – Pass a function that will be called when a client starts. 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.

Chats and members¶

class pyrogram.handlers.ChatMemberUpdatedHandler[source]¶

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.ChatJoinRequestHandler[source]¶

The ChatJoinRequest handler class. Used to handle join chat requests. It is intended to be used with add_handler().

For a nicer way to register this handler, have a look at the on_chat_join_request() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new ChatJoinRequest event arrives. It takes (client, chat_join_request) 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_join_request (ChatJoinRequest) – The received chat join request.

class pyrogram.handlers.ChatBoostHandler[source]¶

The ChatBoost handler class. Used to handle applied chat boosts. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_chat_boost() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new boost applied. It takes (client, boost) 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.
boost (ChatBoost) – The applied chat boost.

class pyrogram.handlers.UserStatusHandler[source]¶

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.

Payments¶

class pyrogram.handlers.PreCheckoutQueryHandler[source]¶

The PreCheckoutQueryHandler handler class. Used to handle pre-checkout queries coming from buy buttons. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_pre_checkout_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new PreCheckoutQuery arrives. It takes (client, pre_checkout_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.
pre_checkout_query (PreCheckoutQuery) – The received callback query.

class pyrogram.handlers.ShippingQueryHandler[source]¶

The ShippingQueryHandler handler class. Used to handle shipping queries coming only from invoice buttons with flexible price.

It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_shipping_query() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a new PreCheckoutQuery arrives. It takes (client, 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 shipping query handler.
query (ShippingQuery) – New incoming shipping query. Only for invoices with flexible price.

class pyrogram.handlers.PurchasedPaidMediaHandler[source]¶

The PurchasedPaidMedia handler class. Used to handle purchased paid medias. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_purchased_paid_media() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a paid media purchased. It takes (client, update) 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.
update (PurchasedPaidMedia) – Information about who bought paid media.

Client lifecycle¶

class pyrogram.handlers.ConnectHandler[source]¶

The Connect handler class. Used to handle connections. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_connect() decorator.

Parameters:

callback (Callable) – Pass a function that will be called when a connection 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.
session (Session) – The Session used for the connection.

class pyrogram.handlers.DisconnectHandler[source]¶

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.StopHandler[source]¶

The Stop handler class. Used to handle client stop. It is intended to be used with add_handler()

For a nicer way to register this handler, have a look at the on_stop() decorator.

Parameters:: callback (Callable) – Pass a function that will be called when a client stops. 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.ErrorHandler[source]¶

The Error handler class. Used to handle unexpected errors.

It is intended to be used with add_handler().

For a more convenient way to register this handler, see the on_error() decorator.

Parameters:

callback (Callable) – A function that will be called whenever an unexpected error is raised. It takes the following positional arguments: (exception, handler, client, *args).
exceptions (Exception | List of Exception, optional) – An exception type or a sequence of exception types that this handler should handle. If None, the handler will catch any exception that is a subclass of Exception.
filters (Filter, optional) – Pass one or more filters to allow only a subset of updates to be passed in your callback function.

Other parameters passed to the callback:

client (Client):: The Client instance, useful when calling other API methods inside the error handler.
exception (Exception):: The Exception instance that was raised.
handler (Handler):: The Handler instance from which the exception was raised.
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 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]).

Raw updates¶

class pyrogram.handlers.RawUpdateHandler[source]¶

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.

UserEmpty
ChatEmpty
ChatForbidden
ChannelForbidden

Base class¶

class pyrogram.handlers.Handler[source]¶