From 8536a7e5a4a91094e3a169e7d2e05023bfa2bebd Mon Sep 17 00:00:00 2001
From: Lonami <totufals@hotmail.com>
Date: Thu, 19 Oct 2017 12:17:27 +0200
Subject: [PATCH] Mention .get_entity and .get_input_entity

---
 Retrieving-an-entity.md | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/Retrieving-an-entity.md b/Retrieving-an-entity.md
index d6d61cc..780b8ab 100644
--- a/Retrieving-an-entity.md
+++ b/Retrieving-an-entity.md
@@ -1,5 +1,28 @@
+An "entity" is used to refer to either an [`User`](https://lonamiwebs.github.io/Telethon/types/user.html) or a [`Chat`](https://lonamiwebs.github.io/Telethon/types/chat.html) (which includes a [`Channel`](https://lonamiwebs.github.io/Telethon/constructors/channel.html)). The most straightforward way to get an entity is to use `TelegramClient.get_entity()`. This method accepts either a string, which can be a username or a phone number, or an integer that will be the ID of an **user**. You can use it like so:
+```python
+lonami  = client.get_entity('lonami')
+contact = client.get_entity('+34xxxxxxxxx')
+friend  = client.get_entity(friend_id)
+```
+
+For the last one to work, the library must have "seen" the user at least once. The library will "see" the user as long as any request contains them, so if you've called `.get_dialogs()` for instance, and your friend was there, the library will know about them. For more, read about the [Session Files](Session-Files).
+
+If you want to get a channel or chat by ID, you need to specify that they are a channel or a chat. The library can't infer what they are by just their ID (unless the ID is marked, but this is only done internally), so you need to wrap the ID around a [`Peer`](https://lonamiwebs.github.io/Telethon/types/peer.html) object:
+```python
+from telethon.tl.types import PeerUser, PeerChat, PeerChannel
+my_user    = client.get_entity(PeerUser(some_id))
+my_chat    = client.get_entity(PeerChat(some_id))
+my_channel = client.get_entity(PeerChannel(some_id))
+```
+
+**Note** that most requests don't ask for an `User`, or a `Chat`, but rather for `InputUser`, `InputChat`, and so on. If this is the case, you should prefer `.get_input_entity()` over `.get_entity()`, as it will be immediate if you provide an ID (whereas `.get_entity()` may need to find who the entity is first).
+
+## Via your open "chats" (dialogs)
+
+[There's a page for that](Retrieving-all-dialogs).
+
 ## Via ResolveUsernameRequest
-An "entity" is used to refer to either an [`User`](https://lonamiwebs.github.io/Telethon/types/user.html) or a [`Chat`](https://lonamiwebs.github.io/Telethon/types/chat.html) (which includes a [`Channel`](https://lonamiwebs.github.io/Telethon/constructors/channel.html)). Perhaps the most straightforward way to get these is by [resolving their username](https://lonamiwebs.github.io/Telethon/methods/contacts/resolve_username.html):
+This is the request used by `.get_entity` internally, but you can also use it by hand:
 
 ```python
 from telethon.tl.functions.contacts import ResolveUsernameRequest
@@ -24,9 +47,11 @@ user = next(u for u in messages.users if u.id == fwd_header.from_id)
 channel = next(c for c in messages.chats if c.id == fwd_header.channel_id)
 ```
 
+Or you can just call `.get_entity()` with the ID, as you should have seen that user or channel before. A call to `GetMessagesRequest` may still be neeed.
+
 ## Via GetContactsRequest
 
-If the user you want to talk to is a contact, you can use [`GetContactsRequest`](https://lonamiwebs.github.io/Telethon/methods/contacts/get_contacts.html):
+The library will call this for you if you pass a phone number to `.get_entity`, but again, it can be done manually. If the user you want to talk to is a contact, you can use [`GetContactsRequest`](https://lonamiwebs.github.io/Telethon/methods/contacts/get_contacts.html):
 
 ```python
 from telethon.tl.functions.contacts import GetContactsRequest
@@ -36,8 +61,4 @@ contacts = client(GetContactsRequest(0))
 if isinstance(contacts, Contacts):
     users = contacts.users
     contacts = contacts.contacts
-```
-
-## Via open dialogs
-
-[There's a page for that](Retrieving-all-dialogs).
\ No newline at end of file
+```
\ No newline at end of file