Clean up and complete RTD documentation

2025-08-09 05:19:41 +00:00 · 2018-01-05 00:59:53 +01:00
parent 6cb5931e7a
commit cb45e8fca9
29 changed files with 1096 additions and 702 deletions
--- a/readthedocs/extra/examples/working-with-messages.rst
+++ b/readthedocs/extra/examples/working-with-messages.rst
@@ -0,0 +1,108 @@
+=====================
+Working with messages
+=====================
+
+
+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