Be explicit that phone numbers only work if in your contacts

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

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
+    You **don't** need to get the entity before using it! Just let the
-    the library do its job. Use the phone, username, ID or input
+    library do its job. Use a phone from your contacts, username, ID or
-    entity (preferred but not necessary), whatever you already have.
+    input entity (preferred but not necessary), whatever you already have.
 
 All methods in the :ref:`telegram-client` call `.get_input_entity()
 <telethon.client.users.UserMethods.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() <telethon.client.users.UserMethods.get_entity>`
-    beforehand, just use the username or phone, or the entity retrieved by
+    beforehand, just use the username, a phone from your contacts, or the entity
-    other means like `client.get_dialogs()
+    retrieved by other means like `client.get_dialogs()
     <telethon.client.dialogs.DialogMethods.get_dialogs>`.
 
 On top of the normal types, the API also make use of what they call their

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

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`
+            Using phone numbers (from people in your contact list), exact
-            rely on a `get_input_entity` first, which in turn needs the
+            names, integer IDs or :tl:`Peer` rely on a `get_input_entity`
-            entity to be in cache, unless a :tl:`InputPeer` was passed.
+            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.