diff --git a/readthedocs/extra/basic/entities.rst b/readthedocs/extra/basic/entities.rst index ab04a165..c0473247 100644 --- a/readthedocs/extra/basic/entities.rst +++ b/readthedocs/extra/basic/entities.rst @@ -20,6 +20,13 @@ in response to certain methods, such as :tl:`GetUsersRequest`. or even entire :tl:`User`, :tl:`Chat` and :tl:`Channel` objects and even phone numbers from people you have in your contacts. + To "encounter" an ID, you would have to "find it" like you would in the + normal app. If the peer is in your dialogs, you would need to + `client.get_dialogs() `. + If the peer is someone in a group, you would similarly + `client.get_participants(group) `. + + Getting entities **************** diff --git a/readthedocs/extra/basic/telegram-client.rst b/readthedocs/extra/basic/telegram-client.rst index decb3765..81edf83a 100644 --- a/readthedocs/extra/basic/telegram-client.rst +++ b/readthedocs/extra/basic/telegram-client.rst @@ -58,6 +58,11 @@ Many other common methods for quick scripts are also available: # Note that you can use 'me' or 'self' to message yourself client.send_message('username', 'Hello World from Telethon!') + # .send_message's parse mode defaults to markdown, so you + # can use **bold**, __italics__, [links](https://example.com), `code`, + # and even [mentions](@username)/[mentions](tg://user?id=123456789) + client.send_message('username', '**Using** __markdown__ `too`!') + client.send_file('username', '/home/myself/Pictures/holidays.jpg') # The utils package has some goodies, like .get_display_name() @@ -83,15 +88,16 @@ a single line. Available methods ***************** -This page lists all the "handy" methods available for you to use in the -``TelegramClient`` class. These are simply wrappers around the "raw" -Telegram API, making it much more manageable and easier to work with. +The :ref:`reference ` lists all the "handy" methods +available for you to use in the ``TelegramClient`` class. These are simply +wrappers around the "raw" Telegram API, making it much more manageable and +easier to work with. Please refer to :ref:`accessing-the-full-api` if these aren't enough, and don't be afraid to read the source code of the InteractiveTelegramClient_ or even the TelegramClient_ itself to learn how it works. -To see the methods available in the client, see :ref:`telethon-package`. +See the mentioned :ref:`telethon-package` to find the available methods. .. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py .. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst index 9851282f..4465bb70 100644 --- a/readthedocs/extra/examples/chats-and-channels.rst +++ b/readthedocs/extra/examples/chats-and-channels.rst @@ -35,6 +35,10 @@ to, you can make use of the `JoinChannelRequest`__ to join such channel: For more on channels, check the `channels namespace`__. +__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html +__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html + + Joining a private chat or channel ********************************* @@ -51,6 +55,9 @@ example, is the ``hash`` of the chat or channel. Now you can use updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg')) +__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html + + Adding someone else to such chat or channel ******************************************* @@ -63,13 +70,15 @@ use is very straightforward, or `InviteToChannelRequest`__ for channels: # For normal chats from telethon.tl.functions.messages import AddChatUserRequest + # Note that ``user_to_add`` is NOT the name of the parameter. + # It's the user you want to add (``user_id=user_to_add``). client(AddChatUserRequest( chat_id, user_to_add, fwd_limit=10 # Allow the user to see the 10 last messages )) - # For channels + # For channels (which includes megagroups) from telethon.tl.functions.channels import InviteToChannelRequest client(InviteToChannelRequest( @@ -78,6 +87,9 @@ use is very straightforward, or `InviteToChannelRequest`__ for channels: )) +__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html +__ https://lonamiwebs.github.io/Telethon/methods/channels/invite_to_channel.html + Checking a link without joining ******************************* @@ -86,14 +98,7 @@ 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/channels/invite_to_channel.html + __ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html @@ -151,7 +156,7 @@ 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/input_channel.html __ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html __ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html __ https://github.com/LonamiWebs/Telethon/issues/573 @@ -208,20 +213,88 @@ Giving or revoking admin permissions can be done with the `EditAdminRequest`__: # User will now be able to change group info, delete other people's # messages and pin messages. - -| Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all -| parameters to ``True`` to give a user full permissions, as not all -| permissions are related to both broadcast channels/megagroups. -| -| E.g. trying to set ``post_messages=True`` in a megagroup will raise an -| error. It is recommended to always use keyword arguments, and to set only -| the permissions the user needs. If you don't need to change a permission, -| it can be omitted (full list `here`__). + + +.. note:: + + Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all + parameters to ``True`` to give a user full permissions, as not all + permissions are related to both broadcast channels/megagroups. + + E.g. trying to set ``post_messages=True`` in a megagroup will raise an + error. It is recommended to always use keyword arguments, and to set only + the permissions the user needs. If you don't need to change a permission, + it can be omitted (full list `here`__). + + +Restricting Users +***************** + +Similar to how you give or revoke admin permissions, you can edit the +banned rights of an user through `EditAdminRequest`__ and its parameter +`ChannelBannedRights`__: + + .. code-block:: python + + from telethon.tl.functions.channels import EditBannedRequest + from telethon.tl.types import ChannelBannedRights + + from datetime import datetime, timedelta + + # Restricting an user for 7 days, only allowing view/send messages. + # + # Note that it's "reversed". You must set to ``True`` the permissions + # you want to REMOVE, and leave as ``None`` those you want to KEEP. + rights = ChannelBannedRights( + until_date=datetime.now() + timedelta(days=7), + view_messages=None, + send_messages=None, + send_media=True, + send_stickers=True, + send_gifs=True, + send_games=True, + send_inline=True, + embed_links=True + ) + + # The above is equivalent to + rights = ChannelBannedRights( + until_date=datetime.now() + timedelta(days=7), + send_media=True, + send_stickers=True, + send_gifs=True, + send_games=True, + send_inline=True, + embed_links=True + ) + + client(EditBannedRequest(channel, user, rights)) + + +Kicking a member +**************** + +Telegram doesn't actually have a request to kick an user from a group. +Instead, you need to restrict them so they can't see messages. Any date +is enough: + + .. code-block:: python + + from telethon.tl.functions.channels import EditBannedRequest + from telethon.tl.types import ChannelBannedRights + + client(EditBannedRequest(channel, user, ChannelBannedRights( + until_date=None, + view_messages=True + ))) + __ 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 +__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_banned.html +__ https://lonamiwebs.github.io/Telethon/constructors/channel_banned_rights.html Increasing View Count in a Channel diff --git a/readthedocs/extra/examples/projects-using-telethon.rst b/readthedocs/extra/examples/projects-using-telethon.rst new file mode 100644 index 00000000..d688360c --- /dev/null +++ b/readthedocs/extra/examples/projects-using-telethon.rst @@ -0,0 +1,41 @@ +======================= +Projects using Telethon +======================= + +This page lists some real world examples showcasing what can be built with +the library. + +.. note:: + + Do you have a project that uses the library or know of any that's not + listed here? Feel free to leave a comment at + `issue 744 `_ + so it can be included in the next revision of the documentation! + + +telegram-export +*************** + +`Link `_ / +`Author's website `_ + +A tool to download Telegram data (users, chats, messages, and media) +into a database (and display the saved data). + + +mautrix-telegram +**************** + +`Link `_ / +`Author's website `_ + +A Matrix-Telegram hybrid puppeting/relaybot bridge. + + +TelegramTUI +*********** + +`Link `_ / +`Author's website `_ + +A Telegram client on your terminal. diff --git a/readthedocs/index.rst b/readthedocs/index.rst index a3982d86..89d2c510 100644 --- a/readthedocs/index.rst +++ b/readthedocs/index.rst @@ -62,6 +62,7 @@ heavy job for you, so you can focus on developing an application. extra/examples/working-with-messages extra/examples/chats-and-channels extra/examples/bots + extra/examples/projects-using-telethon .. _Troubleshooting: diff --git a/telethon/telegram_client.py b/telethon/telegram_client.py index 22ad6074..631adfb8 100644 --- a/telethon/telegram_client.py +++ b/telethon/telegram_client.py @@ -712,6 +712,13 @@ class TelegramClient(TelegramBareClient): """ Sends the given message to the specified entity (user/chat/channel). + The default parse mode is the same as the official applications + (a custom flavour of markdown). ``**bold**, `code` or __italic__`` + are available. In addition you can send ``[links](https://example.com)`` + and ``[mentions](@username)`` (or using IDs like in the Bot API: + ``[mention](tg://user?id=123456789)``) and ``pre`` blocks with three + backticks. + Args: entity (`entity`): To who will it be sent.