Update "Update Handling" page with more examples too

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 <pyrogram.Client.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.start()
-    client.set_update_handler(callback)
+        client.idle()
 
-    client.start()
+    if __name__ == "__main__":
-    client.idle()
+        main()
 
-The last line, :obj:`client.idle() <pyrogram.Client.idle>` is not strictly necessary but highly recommended;
+The last line of the main() function, :obj:`client.idle() <pyrogram.Client.idle>`, is not strictly necessary but highly
-it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the
+recommended; it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the
 :obj:`stop <pyrogram.Client.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.UpdateNewMessage): # Filter by UpdateNewMessage (PM and Groups)
-            if isinstance(update, types.UpdateShortMessage) and not update.out:
+                message = update.message  # type: types.Message
-                client.send_message(update.user_id, update.message)
 
-    This checks if the update type is :obj:`UpdateShortMessage <pyrogram.api.types.UpdateShortMessage>` and that the
+                if isinstance(message, types.Message):  # Filter by Message to exclude MessageService and MessageEmpty
-    update is not generated by yourself (i.e., the message is not outgoing), then sends back the same message.
+                    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:
+            ...