Update Handlers

Handlers are used to instruct Hydrogram 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 hydrogram import Client
from hydrogram.handlers import MessageHandler

app = Client("my_account")


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


app.add_handler(MessageHandler(dump))

app.run()

Index


Details

class hydrogram.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 hydrogram.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 hydrogram.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 hydrogram.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 hydrogram.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 hydrogram.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 hydrogram.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 hydrogram.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.

class hydrogram.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 hydrogram.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 hydrogram.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.