From 55f1c66f927c247833df4d615f9915d7a5dfb491 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Tue, 13 Feb 2018 18:13:49 +0100 Subject: [PATCH] Update "Update Handling" page with more examples too --- docs/source/resources/UpdateHandling.rst | 115 ++++++++++++++++++++--- 1 file changed, 101 insertions(+), 14 deletions(-) diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index 8fc12543..de390d7e 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -2,7 +2,7 @@ Update Handling =============== Updates are events that happen in your Telegram account (incoming messages, new channel posts, user name changes, ...) -and can be handled by using a callback function, that is, a function called every time an ``Update`` is received from +and can be handled by using a callback function, that is, a function called every time an :obj:`Update` is received from Telegram. To set an update handler simply call :obj:`set_update_handler ` @@ -15,32 +15,119 @@ Here's a complete example on how to set it up: from pyrogram import Client - def callback(update): + def update_handler(client, update, users, chats): print(update) + def main() + client = Client(session_name="example") + client.set_update_handler(update_handler) - client = Client(session_name="example") - client.set_update_handler(callback) + client.start() + client.idle() - client.start() - client.idle() + if __name__ == "__main__": + main() -The last line, :obj:`client.idle() ` is not strictly necessary but highly recommended; -it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the +The last line of the main() function, :obj:`client.idle() `, is not strictly necessary but highly +recommended; it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the :obj:`stop ` method which stops the Client and gently close the underlying connection. Examples -------- -- Echo: +- Simple Echo example for **Private Messages**: .. code-block:: python from pyrogram.api import types - def callback(update): - if isinstance(update, types.UpdateShortMessage) and not update.out: - client.send_message(update.user_id, update.message) + if isinstance(update, types.UpdateNewMessage): # Filter by UpdateNewMessage (PM and Groups) + message = update.message # type: types.Message - This checks if the update type is :obj:`UpdateShortMessage ` and that the - update is not generated by yourself (i.e., the message is not outgoing), then sends back the same message. \ No newline at end of file + if isinstance(message, types.Message): # Filter by Message to exclude MessageService and MessageEmpty + if isinstance(message.to_id, types.PeerUser): # Private Messages (Message from user) + client.send_message(message.from_id, message.message, reply_to_message_id=message.id) + + + +- Advanced Echo example for both **Private Messages** and **Basic Groups** (with mentions). + + .. code-block:: python + + from pyrogram.api import types + + def update_handler(client, update, users, chats): + if isinstance(update, types.UpdateNewMessage): # Filter by UpdateNewMessage (PM and Chats) + message = update.message + + if isinstance(message, types.Message): # Filter by Message to exclude MessageService and MessageEmpty + if isinstance(message.to_id, types.PeerUser): # Private Messages + text = '[{}](tg://user?id={}) said "{}" to me ([{}](tg://user?id={}))'.format( + users[message.from_id].first_name, + users[message.from_id].id, + message.message, + users[message.to_id.user_id].first_name, + users[message.to_id.user_id].id + ) + + client.send_message( + message.from_id, # Send the message to the private chat (from_id) + text, + reply_to_message_id=message.id + ) + else: # Group chats + text = '[{}](tg://user?id={}) said "{}" in **{}** group'.format( + users[message.from_id].first_name, + users[message.from_id].id, + message.message, + chats[message.to_id.chat_id].title + ) + + client.send_message( + message.to_id, # Send the message to the group chat (to_id) + text, + reply_to_message_id=message.id + ) + +- Advanced Echo example for **Supergroups** (with mentions): + + .. code-block:: python + + from pyrogram.api import types + + def update_handler(client, update, users, chats): + if isinstance(update, types.UpdateNewChannelMessage): # Filter by UpdateNewChannelMessage (Channels/Supergroups) + message = update.message + + if isinstance(message, types.Message): # Filter by Message to exclude MessageService and MessageEmpty + if chats[message.to_id.channel_id].megagroup: # Only handle messages from Supergroups not Channels + text = '[{}](tg://user?id={}) said "{}" in **{}** supergroup'.format( + users[message.from_id].first_name, + users[message.from_id].id, + message.message, + chats[message.to_id.channel_id].title + ) + + client.send_message( + message.to_id, + text, + reply_to_message_id=message.id + ) + +.. warning:: + The Advanced Examples above will make you reply to **all** new messages in private chats and in every single + group/supergroup you are in. Make sure you add an extra check to filter them: + + .. code-block:: python + + # Filter Groups by ID + if message.to_id.chat_id == MY_GROUP_ID: + ... + + # Filter Supergroups by ID + if message.to_id.channel_id == MY_SUPERGROUP_ID: + ... + + # Filter Supergroups by Username + if chats[message.to_id.channel_id].username == MY_SUPERGROUP_USERNAME: + ... \ No newline at end of file