Clean up and complete RTD documentation

readthedocs/extra/examples/bots.rst

@@ -0,0 +1,59 @@
+====
+Bots
+====
+
+
+Talking to Inline Bots
+**********************
+
+You can query an inline bot, such as `@VoteBot`__ (note, *query*,
+not *interact* with a voting message), by making use of the
+`GetInlineBotResultsRequest`__ request:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import GetInlineBotResultsRequest
+
+        bot_results = client(GetInlineBotResultsRequest(
+            bot, user_or_chat, 'query', ''
+        ))
+
+And you can select any of their results by using
+`SendInlineBotResultRequest`__:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import SendInlineBotResultRequest
+
+        client(SendInlineBotResultRequest(
+            get_input_peer(user_or_chat),
+            obtained_query_id,
+            obtained_str_id
+        ))
+
+
+Talking to Bots with special reply markup
+*****************************************
+
+To interact with a message that has a special reply markup, such as
+`@VoteBot`__ polls, you would use `GetBotCallbackAnswerRequest`__:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import GetBotCallbackAnswerRequest
+
+        client(GetBotCallbackAnswerRequest(
+            user_or_chat,
+            msg.id,
+            data=msg.reply_markup.rows[wanted_row].buttons[wanted_button].data
+        ))
+
+It's a bit verbose, but it has all the information you would need to
+show it visually (button rows, and buttons within each row, each with
+its own data).
+
+__ https://t.me/vote
+__ https://lonamiwebs.github.io/Telethon/methods/messages/get_inline_bot_results.html
+__ https://lonamiwebs.github.io/Telethon/methods/messages/send_inline_bot_result.html
+__ https://lonamiwebs.github.io/Telethon/methods/messages/get_bot_callback_answer.html
+__ https://t.me/vote

readthedocs/extra/examples/chats-and-channels.rst

@@ -0,0 +1,205 @@
+===============================
+Working with Chats and Channels
+===============================
+
+
+Joining a chat or channel
+*************************
+
+Note that `Chat`__\ s are normal groups, and `Channel`__\ s are a
+special form of `Chat`__\ s,
+which can also be super-groups if their ``megagroup`` member is
+``True``.
+
+
+Joining a public channel
+************************
+
+Once you have the :ref:`entity <entities>` of the channel you want to join
+to, you can make use of the `JoinChannelRequest`__ to join such channel:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import JoinChannelRequest
+        client(JoinChannelRequest(channel))
+
+        # In the same way, you can also leave such channel
+        from telethon.tl.functions.channels import LeaveChannelRequest
+        client(LeaveChannelRequest(input_channel))
+
+
+For more on channels, check the `channels namespace`__.
+
+
+Joining a private chat or channel
+*********************************
+
+If all you have is a link like this one:
+``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have
+enough information to join! The part after the
+``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this
+example, is the ``hash`` of the chat or channel. Now you can use
+`ImportChatInviteRequest`__ as follows:
+
+    .. -block:: python
+
+        from telethon.tl.functions.messages import ImportChatInviteRequest
+        updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))
+
+
+Adding someone else to such chat or channel
+*******************************************
+
+If you don't want to add yourself, maybe because you're already in,
+you can always add someone else with the `AddChatUserRequest`__,
+which use is very straightforward:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import AddChatUserRequest
+
+        client(AddChatUserRequest(
+            chat_id,
+            user_to_add,
+            fwd_limit=10  # allow the user to see the 10 last messages
+        ))
+
+
+Checking a link without joining
+*******************************
+
+If you don't need to join but rather check whether it's a group or a
+channel, you can use the `CheckChatInviteRequest`__, which takes in
+the `hash`__ of said channel or group.
+
+__ https://lonamiwebs.github.io/Telethon/constructors/chat.html
+__ https://lonamiwebs.github.io/Telethon/constructors/channel.html
+__ https://lonamiwebs.github.io/Telethon/types/chat.html
+__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html
+__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html
+__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html
+__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html
+__ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html
+__ https://github.com/LonamiWebs/Telethon/wiki/Joining-a-chat-or-channel#joining-a-private-chat-or-channel
+
+
+Retrieving all chat members (channels too)
+******************************************
+
+In order to get all the members from a mega-group or channel, you need
+to use `GetParticipantsRequest`__. As we can see it needs an
+`InputChannel`__, (passing the mega-group or channel you're going to
+use will work), and a mandatory `ChannelParticipantsFilter`__. The
+closest thing to "no filter" is to simply use
+`ChannelParticipantsSearch`__ with an empty ``'q'`` string.
+
+If we want to get *all* the members, we need to use a moving offset and
+a fixed limit:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import GetParticipantsRequest
+        from telethon.tl.types import ChannelParticipantsSearch
+        from time import sleep
+
+        offset = 0
+        limit = 100
+        all_participants = []
+
+        while True:
+            participants = client.invoke(GetParticipantsRequest(
+                channel, ChannelParticipantsSearch(''), offset, limit
+            ))
+            if not participants.users:
+                break
+            all_participants.extend(participants.users)
+            offset += len(participants.users)
+
+
+Note that ``GetParticipantsRequest`` returns `ChannelParticipants`__,
+which may have more information you need (like the role of the
+participants, total count of members, etc.)
+
+__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html
+__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html
+__ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html
+__ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html
+__ https://lonamiwebs.github.io/Telethon/constructors/channels/channel_participants.html
+
+
+Recent Actions
+**************
+
+"Recent actions" is simply the name official applications have given to
+the "admin log". Simply use `GetAdminLogRequest`__ for that, and
+you'll get AdminLogResults.events in return which in turn has the final
+`.action`__.
+
+__ https://lonamiwebs.github.io/Telethon/methods/channels/get_admin_log.html
+__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html
+
+
+Admin Permissions
+*****************
+
+Giving or revoking admin permissions can be done with the `EditAdminRequest`__:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditAdminRequest
+        from telethon.tl.types import ChannelAdminRights
+
+        # You need both the channel and who to grant permissions
+        # They can either be channel/user or input channel/input user.
+        #
+        # ChannelAdminRights is a list of granted permissions.
+        # Set to True those you want to give.
+        rights = ChannelAdminRights(
+            post_messages=None,
+            add_admins=None,
+            invite_users=None,
+            change_info=True,
+            ban_users=None,
+            delete_messages=True,
+            pin_messages=True,
+            invite_link=None,
+            edit_messages=None
+        )
+
+        client(EditAdminRequest(channel, who, rights))
+
+
+Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set
+to ``True`` the ``post_messages`` and ``edit_messages`` fields. Those that
+are ``None`` can be omitted (left here so you know `which are available`__.
+
+__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_admin.html
+__ https://github.com/Kyle2142
+__ https://github.com/LonamiWebs/Telethon/issues/490
+__ https://lonamiwebs.github.io/Telethon/constructors/channel_admin_rights.html
+
+
+Increasing View Count in a Channel
+**********************************
+
+It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and
+while I don't understand why so many people ask this, the solution is to
+use `GetMessagesViewsRequest`__, setting ``increment=True``:
+
+    .. code-block:: python
+
+
+        # Obtain `channel' through dialogs or through client.get_entity() or anyhow.
+        # Obtain `msg_ids' through `.get_message_history()` or anyhow. Must be a list.
+
+        client(GetMessagesViewsRequest(
+            peer=channel,
+            id=msg_ids,
+            increment=True
+        ))
+
+__ https://github.com/LonamiWebs/Telethon/issues/233
+__ https://github.com/LonamiWebs/Telethon/issues/305
+__ https://github.com/LonamiWebs/Telethon/issues/409
+__ https://github.com/LonamiWebs/Telethon/issues/447
+__ https://lonamiwebs.github.io/Telethon/methods/messages/get_messages_views.html

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