General objects

Update

class Update(*, update_id, message=None, edited_message=None, channel_post=None, edited_channel_post=None, inline_query=None, chosen_inline_result=None, callback_query=None, shipping_query=None, pre_checkout_query=None, poll=None)

This class represents an incoming update

Parameters

  • update_id (int) – The update’s unique identifier. Update identifiers start from a certain positive number and increase sequentially. If there are no new updates for at least a week, then identifier of the next update will be chosen randomly instead of sequentially.

  • message (Message) – Optional: New incoming message of any kind

  • edited_message (Message) – Optional: New version of a message that is known to the bot and was edited

  • channel_post (Message) – Optional: New incoming channel post of any kind

  • edited_channel_post (Message) – Optional: New version of a channel post that is known to the bot and was edited

  • inline_query (object_inline_query) – Optional: New incoming query

  • chosen_inline_result (object_chosen_inline_result) – Optional: The result of an inline query that was chosen by a user and sent to their chat partner

  • callback_query (CallbackQuery) – Optional: New incoming callback query

  • shipping_query (object_shipping_query) – Optional: New incoming shipping query. Only for invoices with flexible price

  • pre_checkout_query (object_pre_checkout_query) – Optional: New incoming pre-checkout query. Contains full information about checkout

  • poll (Poll) – Optional: New poll state. Bots receive only updates about stopped polls and polls, which are sent by the bot

Message

class Message(*, message_id, from_user=None, date, chat=None, forward_from=None, forward_from_chat=None, forward_from_message_id=None, forward_signature=None, forward_sender_name=None, forward_date=None, reply_to_message=None, edit_date=None, media_group_id=None, author_signature=None, text=None, entities=None, caption_entities=None, audio=None, document=None, animation=None, game=None, photo=None, sticker=None, video=None, voice=None, video_note=None, caption=None, contact=None, location=None, venue=None, poll=None, new_chat_members=None, left_chat_member=None, new_chat_title=None, new_chat_photo=None, delete_chat_photo=None, group_chat_created=None, supergroup_chat_created=None, channel_chat_created=None, migrate_to_chat_id=None, migrate_from_chat_id=None, pinned_message=None, invoice=None, successful_payment=None, connected_website=None, passport_data=None, reply_markup=None, new_chat_member=None, new_chat_participant=None)

This class represents a message

Parameters

  • message_id (int) – Unique message identifier

  • from_user (User) – Optional: User from which the message is from. Empty for messages sent to channels

  • date (int) – Date the message was sent in Unix time

  • chat (Chat) – Optional: Conversation the message belongs to

  • forward_from (User) – Optional: For forwarded messages, sender of the original messages

  • forward_from_chat (Chat) – Optional: For messages forwarded from channels, information about the original channel

  • forward_from_message_id (int) – Optional: For messages forwarded from channels, identifier of the original message in the channel

  • forward_signature (str) – Optional: For messages forwarded from channels, signature of the post author if present

  • forward_sender_name (str) – Optional: Sender’s name for messages forwarded from users who disallow adding a link to their account in forwarded messages

  • forward_date (int,) – Optional: For forwarded messages, date the original message was sent in Unix time

  • reply_to_message (Message) – Optional: For replies, the original message

  • edit_date (int) – Optional: Date the message was last edited in Unix time

  • media_group_id (str) – Optional: The unique identifier of a media message group this message belongs to

  • author_signature (str) – Optional: Signature of the post author for messages in channels

  • text (str) – Optional: For text messages, the actual UTF-8 text of the message, 0-4096 characters.

  • entities (list of MessageEntity) – Optional: For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text

  • caption_entities (list of MessageEntity) – Optional: For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption

  • audio (Audio) – Optional: If the message is an audio file, information about the file

  • document (Document) – Optional: If the message is a general file, information about the file

  • animation (Animation) – Optional: If the message is an animation, information about the animation. For backward compatibility, when this field is set, the document field will also be set

  • game (Game) – Optional: If the message is a game, information about the game.

  • photo (list of PhotoSize) – Optional: If the message is a photo, available sizes of the photo

  • sticker (Sticker) – Optional: If the message is a sticker, information about the sticker.

  • video (Video) – Optional: If the message is a video, information about the video.

  • voice (Voice) – Optional: If the message is a voice message, information about the voice message

  • video_note (VideoNote,) – Optional: If the message ia a video note, information about the video message

  • caption (str) – Optional: Caption for the animation, audio, document, photo, video or voice, 0-1024 Characters

  • contact (Contact) – Optional: If the message is a shared contact, information about the contact

  • location (Location) – Optional: If the message is a shared location information about the location

  • venue (Venue) – Optional: If the message is a venue, information, about the venue

  • poll (Poll) – Optional: If the message is a native poll, information about the poll

  • new_chat_members (list of User) – Optional: New members that were added to the group or supergroup and information about them

  • left_chat_member (User) – Optional: Information about a member, who was removed from the group

  • new_chat_member (User) – Optional: Information about a user, who was added to the group

  • new_chat_participant (User) – Optional: Information about a new chat participant, who was added to the group

  • new_chat_title (str) – Optional: New chat title

  • new_chat_photo (list of PhotoSize) – Optional: New chat photo

  • delete_chat_photo (bool) – Optional: Service Message: The chat photo was deleted

  • group_chat_created (bool) – Optional: Service Message: The group has been created

  • supergroup_chat_created (bool) – Optional: Service message: The supergroup has been created. For more information, see https://core.telegram.org/bots/api#message

  • channel_chat_created (bool) – Optional: Service message: the channel has been created. For more information, see https://core.telegram.org/bots/api#message

  • migrate_to_chat_id (int) – Optional: The group has been migrated to a supergroup with the specified identifier

  • migrate_from_chat_id (int) – Optional: The supergroup has been migrated from a group with the specified identifier

  • pinned_message (Message) – Optional: Specified message was pinned

  • invoice (Invoice) – Optional: If the message is a invoice for payment, information about the invoice

  • successful_payment (SuccessfulPayment) – Optional: If the message is a service message about a successful payment, information about the payment

  • connected_website (str) – Optional: The domain name of the website on which the user has logged in

  • passport_data (PassportData) – Optional: Telegram Passport data

  • reply_markup (InlineKeyboardMarkup) – Optional: Inline keyboard attached to the message

MessageEntity

class MessageEntity(*, type_result, offset, length, url=None, user=None)

This class represents one special entity in a text message

Parameters

  • type_result (str) – Type of the entity. Can be _mention_(@username), hashtag, cashtag, bot_command, url, email, phone_number, bold, italic, code, pre, text_link or text_mention

  • offset (int) – Offset in UTF-16 code units to the start of the entity

  • length (int) – Length oh the entity in UTF-16 code units

  • url (str) – Optional: For text_link only, url that will be opened after user taps on the text

  • user (User) – Optional: for text_mention only, the mentioned user

User

class User(*, id_unique, is_bot, first_name, last_name=None, username=None, language_code=None)

This class represents an User no matter if it’s an real user or an bot

Parameters

  • id_unique (int) – Unique id of the target

  • is_bot (bool) – Gives information whether the user is a bot or not

  • first_name (str) – User’s or bot’s first name

  • last_name (str, optional) – User’s or bot’s last name

  • username (str, optional) – User’s or bot’s username

  • language_code (str, optional) – IETF language tag of the user’s language

UserProfilePhotos

class UserProfilePhotos(*, total_count, photos)

Represents a list of profile photos

Parameters

  • total_count (int) – Total number of profile pictures the target user has

  • photos (list of list of PhotoSize) – List of profile pictures

Chat

class Chat(*, id_unique, type_result, title=None, username=None, first_name=None, last_name=None, photo=None, description=None, invite_link=None, pinned_message=None, permissions=None, sticker_set_name=None, can_set_sticker_set=None)

This object represents a chat

Parameters

  • id_unique (int) – Unique identifier for the chat

  • type_result (str) – Type of chat, can be either “private”, “group”, “supergroup” or “channel”

  • title (str) – Optional: Title, for supergroups, channels and group chats

  • username (str) – Optional: Username, for private chats, supergroups and channel is available

  • first_name (str) – Optional: First name of the other party in a private chat

  • last_name (str) – Optional: Last name of the other party in a private chat

  • photo (ChatPhoto) – Optional: Chat photo. Returned only in get_chat

  • description (str) – Optional: Description, for groups, supergroups and channel chats. Returned only in get_chat

  • invite_link (str) – Optional: Chat invite link, for groups, supergroups and channel chats. Returned only in get_chat

  • pinned_message (Message) – Optional: Pinned message, for groups, supergroups and channels. Returned only in get_chat

  • permissions (ChatPermissions) – Optional: Default chat member permissions. Returned only in get_chat

  • sticker_set_name (str) – Optional: Name of sticker set for supergroups. Returned only in get_chat

  • can_set_sticker_set (bool) – Optional: True if the bot can change the supergroup set. Returned only in get_chat

ChatPhoto

class ChatPhoto(*, small_file_id, big_file_id)

This class represents a chat photo

Parameters

  • small_file_id (str) – File identifier of small (160x160) chat photo

  • big_file_id (str) – File identifier of big (640x640) chat photo

ChatPermissions

class ChatPermissions(*, can_send_messages=None, can_send_media_messages=None, can_send_polls=None, can_send_other_messages=None, can_add_web_page_previews=None, can_change_info=None, can_invite_users=None, can_pin_messages=None)

This class describes actions that a non-administrator user is allowed to take in a chat

Parameters

  • can_send_messages (bool) – Optional: True, if the user is allowed to send text messages, contacts, locations and venues

  • can_send_media_messages (bool) – Optional: True, if the user is allowed to send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages

  • can_send_polls (bool) – Optional: True, if the user is allowed to send polls, implies can_send_messages

  • can_send_other_messages (bool) – Optional: True, if the user is allowed to send animations, games, stickers and use inline bots, implies can_send_media_messages

  • can_add_web_page_previews (bool) – Optional: True, if the user is allowed to add web page previews to their messages, implies can_send_media_messages

  • can_change_info (bool) – Optional: True, if the user is allowed to change the chat title, photo and other settings. Ignored in public supergroups

  • can_invite_users (bool) – Optional: True, if the user is allowed to invite new users to the chat

  • can_pin_messages (bool) – Optional: True, if the user is allowed to pin messages. Ignored in public supergroups

CallbackQuery

class CallbackQuery(*, id_unique, from_user, message=None, inline_message_id=None, chat_instance=None, data=None, game_short_name=None)

This object represents an incoming callback query from a callback button in an inline keyboard. * If the button that originated the query was attached to a message sent by the bot, the field message will be present. * If the button was attached to a message sent via the bot the field inline_message_id will be present * Exactly one of the field data or game_short_name will be present

Parameters

  • id_unique (str) – Unique identifier for this query

  • from_user (User) – Specifies the sender

  • message (Message) – Optional: Message with the callback button that originated the query

  • inline_message_id (str) – Optional: Identifier of the message sent via the bot in inline mode, that originated the query

  • chat_instance (str) – Optional: Global identifier, uniquely corresponding to the chat which the message with the callback button was sent

  • data (str) – Optional: Data associated with the callback button.

  • game_short_name (str) – Optional: Short name of a Game to be returned, serves as the unique identifier for the game

ForceReply

class ForceReply(*, force_reply, selective=None)

Upon receiving a message with this object, Telegram clients will display a reply interface to the user (act as if the user has selected the bot‘s message and tapped ’Reply’).

Parameters

  • force_reply (bool) – Returns True, if the reply was successfully

  • selective (bool) – Optional: Use this parameter if you want to force reply from specific users only