Objects Reference

This is the quick reference for those objects returned by client methods or other useful modules that the library has to offer. They are kept in a separate page to help finding and discovering them.

Remember that this page only shows properties and methods, not attributes. Make sure to open the full documentation to find out about the attributes.

ChatGetter

All events base ChatGetter, and some of the objects below do too, so it’s important to know its methods.

chat	Returns the User, Chat or Channel where this object belongs to.
input_chat	This InputPeer is the input version of the chat where the message was sent.
chat_id	Returns the marked chat integer ID.
is_private	True if the message was sent as a private message.
is_group	True if the message was sent on a group or megagroup.
is_channel	True if the message was sent on a megagroup or channel.
get_chat	Returns chat, but will make an API call to find the chat unless it's already cached.
get_input_chat	Returns input_chat, but will make an API call to find the input chat unless it's already cached.

SenderGetter

Similar to ChatGetter, a SenderGetter is the same, but it works for senders instead.

sender	Returns the User or Channel that sent this object.
input_sender	This InputPeer is the input version of the user/channel who sent the message.
sender_id	Returns the marked sender integer ID, if present.
get_sender	Returns sender, but will make an API call to find the sender unless it's already cached.
get_input_sender	Returns input_sender, but will make an API call to find the input sender unless it's already cached.

Message

The Message type is very important, mostly because we are working with a library for a messaging platform, so messages are widely used: in events, when fetching history, replies, etc.

It bases ChatGetter and SenderGetter.

Properties

Note

We document custom properties here, not all the attributes of the Message (which is the information Telegram actually returns).

text	The message text, formatted using the client's default parse mode.
raw_text	The raw message text, ignoring any formatting.
is_reply	True if the message is a reply to some other message.
forward	The Forward information if this message is a forwarded message.
buttons	Returns a list of lists of MessageButton, if any.
button_count	Returns the total button count (sum of all buttons rows).
file	Returns a File wrapping the photo or document in this message.
photo	The Photo media in this message, if any.
document	The Document media in this message, if any.
web_preview	The WebPage media in this message, if any.
audio	The Document media in this message, if it's an audio file.
voice	The Document media in this message, if it's a voice note.
video	The Document media in this message, if it's a video.
video_note	The Document media in this message, if it's a video note.
gif	The Document media in this message, if it's a "gif".
sticker	The Document media in this message, if it's a sticker.
contact	The MessageMediaContact in this message, if it's a contact.
game	The Game media in this message, if it's a game.
geo	The GeoPoint media in this message, if it has a location.
invoice	The MessageMediaInvoice in this message, if it's an invoice.
poll	The MessageMediaPoll in this message, if it's a poll.
venue	The MessageMediaVenue in this message, if it's a venue.
action_entities	Returns a list of entities that took part in this action.
via_bot	The bot User if the message was sent via said bot.
via_input_bot	Returns the input variant of via_bot.
client	Returns the TelegramClient that patched this message.

Methods

respond	Responds to the message (not as a reply).
reply	Replies to the message (as a reply).
forward_to	Forwards the message.
edit	Edits the message if it's outgoing.
delete	Deletes the message.
get_reply_message	The Message that this message is replying to, or None.
click	Calls SendVote with the specified poll option or button.click on the specified button.
mark_read	Marks the message as read.
pin	Pins the message.
download_media	Downloads the media contained in the message, if any.
get_entities_text	Returns a list of (markup entity, inner text) (like bold or italics).
get_buttons	Returns buttons when that property fails (this is rarely needed).

File

The File type is a wrapper object returned by Message.file, and you can use it to easily access a document’s attributes, such as its name, bot-API style file ID, etc.

id	The old bot-API style file_id representing this file.
name	The file name of this document.
ext	The extension from the mime type of this file.
mime_type	The mime-type of this file.
width	The width in pixels of this media if it's a photo or a video.
height	The height in pixels of this media if it's a photo or a video.
size	The size in bytes of this file.
duration	The duration in seconds of the audio or video.
title	The title of the song.
performer	The performer of the song.
emoji	A string with all emoji that represent the current sticker.
sticker_set	The InputStickerSet to which the sticker file belongs.

Conversation

The Conversation object is returned by the client.conversation() method to easily send and receive responses like a normal conversation.

It bases ChatGetter.

send_message	Sends a message in the context of this conversation.
send_file	Sends a file in the context of this conversation.
mark_read	Marks as read the latest received message if message is None.
get_response	Gets the next message that responds to a previous one.
get_reply	Gets the next message that explicitly replies to a previous one.
get_edit	Awaits for an edit after the last message to arrive.
wait_read	Awaits for the sent message to be marked as read.
wait_event	Waits for a custom event to occur.
cancel	Cancels the current conversation.
cancel_all	Calls cancel on all conversations in this chat.

AdminLogEvent

The AdminLogEvent object is returned by the client.iter_admin_log() method to easily iterate over past “events” (deleted messages, edits, title changes, leaving members…)

These are all the properties you can find in it:

id	The ID of this event.
date	The date when this event occurred.
user_id	The ID of the user that triggered this event.
action	The original ChannelAdminLogEventAction.
old	The old value from the event.
new	The new value present in the event.
changed_about	Whether the channel's about was changed or not.
changed_title	Whether the channel's title was changed or not.
changed_username	Whether the channel's username was changed or not.
changed_photo	Whether the channel's photo was changed or not.
changed_sticker_set	Whether the channel's sticker set was changed or not.
changed_message	Whether a message in this channel was edited or not.
deleted_message	Whether a message in this channel was deleted or not.
changed_admin	Whether the permissions for an admin in this channel changed or not.
changed_restrictions	Whether a message in this channel was edited or not.
changed_invites	Whether the invites in the channel were toggled or not.
joined	Whether user joined through the channel's public username or not.
joined_invite	Whether a new user joined through an invite link to the channel or not.
left	Whether user left the channel or not.
changed_hide_history	Whether hiding the previous message history for new members in the channel was toggled or not.
changed_signatures	Whether the message signatures in the channel were toggled or not.
changed_pin	Whether a new message in this channel was pinned or not.
changed_default_banned_rights	Whether the default banned rights were changed or not.
stopped_poll	Whether a poll was stopped or not.

Button

The Button class is used when you login as a bot account to send messages with reply markup, such as inline buttons or custom keyboards.

These are the static methods you can use to create instances of the markup:

inline	Creates a new inline button with some payload data in it.
switch_inline	Creates a new inline button to switch to inline query.
url	Creates a new inline button to open the desired URL on click.
auth	Creates a new inline button to authorize the user at the given URL.
text	Creates a new keyboard button with the given text.
request_location	Creates a new keyboard button to request the user's location on click.
request_phone	Creates a new keyboard button to request the user's phone on click.
request_poll	Creates a new keyboard button to request the user to create a poll.
clear	Clears all keyboard buttons after sending a message with this markup.
force_reply	Forces a reply to the message with this markup.

InlineResult

The InlineResult object is returned inside a list by the client.inline_query() method to make an inline query to a bot that supports being used in inline mode, such as @like.

Note that the list returned is in fact a subclass of a list called InlineResults, which, in addition of being a list (iterator, indexed access, etc.), has extra attributes and methods.

These are the constants for the types, properties and methods you can find the individual results:

ARTICLE
PHOTO
GIF
VIDEO
VIDEO_GIF
AUDIO
DOCUMENT
LOCATION
VENUE
CONTACT
GAME
type	The always-present type of this result.
message	The always-present BotInlineMessage that will be sent if click is called on this result.
title	The title for this inline result.
description	The description for this inline result.
url	The URL present in this inline results.
photo	Returns either the WebDocument thumbnail for normal results or the Photo for media results.
document	Returns either the WebDocument content for normal results or the Document for media results.
click	Clicks this result and sends the associated message.
download_media	Downloads the media in this result (if there is a document, the document will be downloaded; otherwise, the photo will if present).

Dialog

The Dialog object is returned when you call client.iter_dialogs().

send_message	Sends a message to this dialog.
archive	Archives (or un-archives) this dialog.
delete	Deletes the dialog from your dialog list.

Draft

The Draft object is returned when you call client.iter_drafts().

entity	The entity that belongs to this dialog (user, chat or channel).
input_entity	Input version of the entity.
get_entity	Returns entity but will make an API call if necessary.
get_input_entity	Returns input_entity but will make an API call if necessary.
text	The markdown text contained in the draft.
raw_text	The raw (text without formatting) contained in the draft.
is_empty	Convenience bool to determine if the draft is empty or not.
set_message	Changes the draft message on the Telegram servers.
send	Sends the contents of this draft to the dialog.
delete	Deletes this draft, and returns True on success.

Utils

The telethon.utils module has plenty of methods that make using the library a lot easier. Only the interesting ones will be listed here.

get_display_name	Gets the display name for the given User, Chat or Channel.
get_extension	Gets the corresponding extension for any Telegram media.
get_inner_text	Gets the inner text that's surrounded by the given entities.
get_peer_id	Convert the given peer into its marked ID by default.
resolve_id	Given a marked ID, returns the original ID and its Peer type.
pack_bot_file_id	Inverse operation for resolve_bot_file_id.
resolve_bot_file_id	Given a Bot API-style file_id, returns the media it represents.
resolve_invite_link	Resolves the given invite link.