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.