add a bunch more readthedocs from wiki

2025-08-11 03:09:31 +00:00 · 2017-11-20 12:12:31 +08:00
parent 34e7ae026e
commit f6ec7e47a7
17 changed files with 1067 additions and 133 deletions
--- a/readthedocs/extra/advanced-usage/working-with-messages.rst
+++ b/readthedocs/extra/advanced-usage/working-with-messages.rst
@@ -0,0 +1,103 @@
+=========================
+Working with messages
+=========================
+
+.. note::
+    Make sure you have gone through :ref:`prelude` already!
+
+
+Forwarding messages
+*******************
+
+Note that ForwardMessageRequest_ (note it's Message, singular) will *not* work if channels are involved.
+This is because channel (and megagroups) IDs are not unique, so you also need to know who the sender is
+(a parameter this request doesn't have).
+
+Either way, you are encouraged to use ForwardMessagesRequest_ (note it's Message*s*, plural) *always*,
+since it is more powerful, as follows:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import ForwardMessagesRequest
+        #                                             note the s ^
+
+        messages = foo()  # retrieve a few messages (or even one, in a list)
+        from_entity = bar()
+        to_entity = baz()
+
+        client(ForwardMessagesRequest(
+            from_peer=from_entity,  # who sent these messages?
+            id=[msg.id for msg in messages],  # which are the messages?
+            to_peer=to_entity  # who are we forwarding them to?
+        ))
+
+The named arguments are there for clarity, although they're not needed because they appear in order.
+You can obviously just wrap a single message on the list too, if that's all you have.
+
+
+Searching Messages
+*******************
+
+Messages are searched through the obvious SearchRequest_, but you may run into issues_. A valid example would be:
+
+    .. code-block:: python
+
+        result = client(SearchRequest(
+            entity, 'query', InputMessagesFilterEmpty(), None, None, 0, 0, 100
+        ))
+
+It's important to note that the optional parameter ``from_id`` has been left omitted and thus defaults to ``None``.
+Changing it to InputUserEmpty_, as one could think to specify "no user", won't work because this parameter is a flag,
+and it being unspecified has a different meaning.
+
+If one were to set ``from_id=InputUserEmpty()``, it would filter messages from "empty" senders,
+which would likely match no users.
+
+If you get a ``ChatAdminRequiredError`` on a channel, it's probably because you tried setting the ``from_id`` filter,
+and as the error says, you can't do that. Leave it set to ``None`` and it should work.
+
+As with every method, make sure you use the right ID/hash combination for your ``InputUser`` or ``InputChat``,
+or you'll likely run into errors like ``UserIdInvalidError``.
+
+
+Sending stickers
+*****************
+
+Stickers are nothing else than ``files``, and when you successfully retrieve the stickers for a certain sticker set,
+all you will have are ``handles`` to these files. Remember, the files Telegram holds on their servers can be referenced
+through this pair of ID/hash (unique per user), and you need to use this handle when sending a "document" message.
+This working example will send yourself the very first sticker you have:
+
+    .. code-block:: python
+
+        # Get all the sticker sets this user has
+        sticker_sets = client(GetAllStickersRequest(0))
+
+        # Choose a sticker set
+        sticker_set = sticker_sets.sets[0]
+
+        # Get the stickers for this sticker set
+        stickers = client(GetStickerSetRequest(
+            stickerset=InputStickerSetID(
+                id=sticker_set.id, access_hash=sticker_set.access_hash
+            )
+        ))
+
+        # Stickers are nothing more than files, so send that
+        client(SendMediaRequest(
+            peer=client.get_me(),
+            media=InputMediaDocument(
+                id=InputDocument(
+                    id=stickers.documents[0].id,
+                    access_hash=stickers.documents[0].access_hash
+                ),
+                caption=''
+            )
+        ))
+
+
+.. _ForwardMessageRequest: https://lonamiwebs.github.io/Telethon/methods/messages/forward_message.html
+.. _ForwardMessagesRequest: https://lonamiwebs.github.io/Telethon/methods/messages/forward_messages.html
+.. _SearchRequest: https://lonamiwebs.github.io/Telethon/methods/messages/search.html
+.. _issues: https://github.com/LonamiWebs/Telethon/issues/215
+.. _InputUserEmpty: https://lonamiwebs.github.io/Telethon/constructors/input_user_empty.html