diff --git a/readthedocs/extra/advanced-usage/mastering-telethon.rst b/readthedocs/extra/advanced-usage/mastering-telethon.rst index 8d17ee87..60803db4 100644 --- a/readthedocs/extra/advanced-usage/mastering-telethon.rst +++ b/readthedocs/extra/advanced-usage/mastering-telethon.rst @@ -54,6 +54,11 @@ There are a lot of things that work as entities: usernames, phone numbers, chat links, invite links, IDs, and the types themselves. That is, you can use any of those when you see an "entity" is needed. +.. note:: + + Remember that the phone number must be in your contact list before you + can use it. + You should use, **from better to worse**: 1. Input entities. For example, `event.input_chat diff --git a/readthedocs/extra/basic/entities.rst b/readthedocs/extra/basic/entities.rst index 5b5f6453..3f8d30f7 100644 --- a/readthedocs/extra/basic/entities.rst +++ b/readthedocs/extra/basic/entities.rst @@ -52,7 +52,7 @@ in response to certain methods, such as :tl:`GetUsersRequest`. provide something that can be turned into an entity. These things include, but are not limited to, usernames, exact titles, IDs, :tl:`Peer` objects, or even entire :tl:`User`, :tl:`Chat` and :tl:`Channel` objects and even - phone numbers from people you have in your contacts. + phone numbers **from people you have in your contact list**. 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 @@ -105,9 +105,9 @@ you're able to just do this: .. note:: - You **don't** need to get the entity before using it! Just let - the library do its job. Use the phone, username, ID or input - entity (preferred but not necessary), whatever you already have. + You **don't** need to get the entity before using it! Just let the + library do its job. Use a phone from your contacts, username, ID or + input entity (preferred but not necessary), whatever you already have. All methods in the :ref:`telegram-client` call `.get_input_entity() ` prior @@ -131,8 +131,8 @@ Entities vs. Input Entities Don't worry if you don't understand this section, just remember some of the details listed here are important. When you're calling a method, don't call `client.get_entity() ` - beforehand, just use the username or phone, or the entity retrieved by - other means like `client.get_dialogs() + beforehand, just use the username, a phone from your contacts, or the entity + retrieved by other means like `client.get_dialogs() `. On top of the normal types, the API also make use of what they call their diff --git a/readthedocs/extra/examples/telegram-client.rst b/readthedocs/extra/examples/telegram-client.rst index d5516a07..b97cff6c 100644 --- a/readthedocs/extra/examples/telegram-client.rst +++ b/readthedocs/extra/examples/telegram-client.rst @@ -632,6 +632,7 @@ all the members from a chat first): for message in client.iter_messages('username'): ... + # Note that for this to work the phone number must be in your contacts some_id = client.get_peer_id('+34123456789') The documentation for shown methods are `get_entity diff --git a/telethon/client/users.py b/telethon/client/users.py index 9e2029f0..1d4639c1 100644 --- a/telethon/client/users.py +++ b/telethon/client/users.py @@ -152,9 +152,10 @@ class UserMethods(TelegramBaseClient): Similar limits apply to invite links, and you should use their ID instead. - Using phone numbers, exact names, integer IDs or :tl:`Peer` - rely on a `get_input_entity` first, which in turn needs the - entity to be in cache, unless a :tl:`InputPeer` was passed. + Using phone numbers (from people in your contact list), exact + names, integer IDs or :tl:`Peer` rely on a `get_input_entity` + first, which in turn needs the entity to be in cache, unless + a :tl:`InputPeer` was passed. Unsupported types will raise ``TypeError``. @@ -252,7 +253,7 @@ class UserMethods(TelegramBaseClient): If the username or ID from the invite link is not found in the cache, it will be fetched. The same rules apply to phone - numbers (``'+34 123456789'``). + numbers (``'+34 123456789'``) from people in your contact list. If an exact name is given, it must be in the cache too. This is not reliable as different people can share the same name @@ -315,7 +316,7 @@ class UserMethods(TelegramBaseClient): Gets the ID for the given peer, which may be anything entity-like. This method needs to be ``async`` because `peer` supports usernames, - invite-links, phone numbers, etc. + invite-links, phone numbers (from people in your contact list), etc. If ``add_mark is False``, then a positive ID will be returned instead. By default, bot-API style IDs (signed) are returned.