Peers, users and chats

The term peer may sound strange at first, but it’s the best we have after much consideration. This section aims to explain what peers are, and how they relate to users, group chats, and broadcast channels.

Telethon Peer

The Peer type in Telethon is the base class for User, Group and Channel. Therefore, a Telethon “peer” represents an entity with various attributes: identifier, username, photo, title, and other information depending on its type.

The PeerRef type represents a reference to a Peer, and can be obtained from its ref attribute. Each peer type has its own reference type, namely UserRef, GroupRef and ChannelRef.

Most methods accept either the Peer or PeerRef (and their subclasses) as input. You do not need to fetch the full Peer to get_messages() or send_file()s— a PeerRef is enough.
Some methods will only work on groups and channels (like get_participants()), or users (like inline_query()).

A Telethon “chat” refers to either groups and channels, or the place where messages are sent to. In the latter case, the chat could also belong to a user, so it would be represented by a Peer.

A Telethon “group” is used to refer to either small group chats or supergroups. This matches what the interface of official applications call these entities.

A Telethon “user” is used to refer to either user accounts or bot accounts. This matches Telegram’s API, as both are represented by the same user object.

Telegram Peer


This section is mainly of interest if you plan to use the Raw API.

Telegram uses Peers to categorize users, groups and channels, much like how Telethon does. It also has the concept of InputPeers, which are commonly used as input parameters when sending requests. These match the concept of Telethon’s peer references.

The main confusion in Telegram’s API comes from the word “chat”.

In the TL schema definitions, there are two boxed types, User and Chat. A boxed User can only be the bare user, but the boxed Chat can be either a bare chat or a bare channel.

A bare chat always refers to small groups. A bare channel can have either the broadcast or the megagroup flag set to True.

A bare channel with the broadcast flag set to True is known as a broadcast channel. A bare channel with the megagroup flag set to True is known as a supergroup.

A bare chat has less features available than a bare channel megagroup. Official clients are very good at hiding this difference. They will implicitly convert bare chat to bare channel megagroup when doing certain operations. Doing things like setting a username is actually a two-step process (migration followed by updating the username). Official clients transparently merge the history of migrated channel with their old chat.

In Telethon:

Telethon classes aim to map to similar concepts in official applications.

Bot API Peer

The Bot API does not use the word “peer”, but instead opts to use “chat” and “user” only, despite chats also being able to reference users. The Bot API follows a certain convention when it comes to chat and user identifiers:

  • User IDs are positive.

  • Chat IDs are negative.

  • Channel IDs are also negative, but are prefixed by -100.

Telethon does not support Bot API’s formatted identifiers, and instead expects you to create the appropriated PeerRef:

from telethon.types import UserRef, GroupRef, ChannelRef

user = UserRef(123)  # user_id 123 from bot API becomes 123
group = GroupRef(456)  # chat_id -456 from bot API becomes 456
channel = ChannelRef(789)  # chat_id -100789 from bot API becomes 789

While using a Telethon Client logged in to a bot account, the above may work for certain methods. However, user accounts often require what’s known as an “access hash”, obtained by encountering the peer first.

Encountering peers

The way you encounter peers in Telethon is no different from official clients. If you:

  • …have joined a group or channel, or have sent private messages to some user, you can get_dialogs().

  • …know the user is in your contact list, you can get_contacts().

  • …know the user has a common chat with you, you can get_participants() of the chat in common.

  • …know the username of the user, group, or channel, you can resolve_username().

  • …are a bot responding to users, you will be able to access the types.Message.sender.

Access hashes and authorizations

Users, supergroups and channels all need an access hash. This value is proof that you’re authorized to access the peer in question. This value is also account-bound. You cannot obtain an access hash in Account-A and use it in Account-B.

In Telethon, the PeerRef is the recommended way to deal with the identifier-authorization pairs. This compact type can be used anywhere a peer is expected. It’s designed to be easy to store and cache in any way your application chooses. You can easily serialize it to a string and back via str(ref) and types.PeerRef.from_str().

Bot accounts can get away with an invalid access hash for certain operations under certain conditions. The same is true for user accounts, although to a lesser extent. When you create a PeerRef without specifying an authorization, a bogus access hash will be used.