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.