telebot_py.types

Telegram Bot API data types (frozen, snake_case, JSON round-trippable).

telebot_py.types.base

Shared serialization base for all Telegram API types.

class telebot_py.types.base.TelegramObject

Bases: object

Base class for immutable Telegram API data types.

Subclasses are frozen dataclasses whose attributes use Telegram’s snake_case field names. from_dict hydrates nested objects and ignores unknown fields; to_dict emits the Telegram wire shape again.

classmethod from_dict(data: Mapping[str, object]) → T

Build an instance from a raw Telegram JSON payload.

Parameters:

data – Decoded JSON object using Telegram’s field names. Unknown fields are ignored.

Returns:

A hydrated instance of this type.

Raises:

TypeParseError – If a required field is missing from data.

to_dict() → dict[str, object]

Serialize this object back to Telegram’s snake_case wire format.

Returns:

A plain dict suitable for JSON encoding. Fields set to None are omitted, matching Telegram’s own payloads.

exception telebot_py.types.base.TypeParseError

Bases: TypeError

Raised when a raw Telegram payload cannot be parsed into a type.

telebot_py.types.business

Telegram Business connection types and chat boost types.

class telebot_py.types.business.BusinessBotRights(can_reply: bool | None = None, can_read_messages: bool | None = None, can_delete_sent_messages: bool | None = None, can_delete_all_messages: bool | None = None, can_edit_name: bool | None = None, can_edit_bio: bool | None = None, can_edit_profile_photo: bool | None = None, can_edit_username: bool | None = None, can_change_gift_settings: bool | None = None, can_view_gifts_and_stars: bool | None = None, can_convert_gifts_to_stars: bool | None = None, can_transfer_and_upgrade_gifts: bool | None = None, can_transfer_stars: bool | None = None, can_manage_stories: bool | None = None)

Bases: TelegramObject

Represents the rights of a business bot.

Every field is optional and only present when Telegram grants it; the set of rights a bot actually holds is reported by the rights field of a BusinessConnection since Bot API 10.3.

Variables:

  • can_reply (bool | None) – True, if the bot can send and edit messages in the private chats that had incoming messages in the last 24 hours.

  • can_read_messages (bool | None) – True, if the bot can mark incoming private messages as read.

  • can_delete_sent_messages (bool | None) – True, if the bot can delete messages sent by the bot.

  • can_delete_all_messages (bool | None) – True, if the bot can delete all private messages in managed chats.

  • can_edit_name (bool | None) – True, if the bot can edit the first and last name of the business account.

  • can_edit_bio (bool | None) – True, if the bot can edit the bio of the business account.

  • can_edit_profile_photo (bool | None) – True, if the bot can edit the profile photo of the business account.

  • can_edit_username (bool | None) – True, if the bot can edit the username of the business account.

  • can_change_gift_settings (bool | None) – True, if the bot can change the privacy settings pertaining to gifts for the business account.

  • can_view_gifts_and_stars (bool | None) – True, if the bot can view gifts and the amount of Telegram Stars owned by the business account.

  • can_convert_gifts_to_stars (bool | None) – True, if the bot can convert regular gifts owned by the business account to Telegram Stars.

  • can_transfer_and_upgrade_gifts (bool | None) – True, if the bot can transfer and upgrade gifts owned by the business account.

  • can_transfer_stars (bool | None) – True, if the bot can transfer Telegram Stars received by the business account to its own account, or use them to upgrade and transfer gifts.

  • can_manage_stories (bool | None) – True, if the bot can post, edit and delete stories on behalf of the business account.

Telegram API: https://core.telegram.org/bots/api#businessbotrights

can_change_gift_settings: bool | None
can_convert_gifts_to_stars: bool | None
can_delete_all_messages: bool | None
can_delete_sent_messages: bool | None
can_edit_bio: bool | None
can_edit_name: bool | None
can_edit_profile_photo: bool | None
can_edit_username: bool | None
can_manage_stories: bool | None
can_read_messages: bool | None
can_reply: bool | None
can_transfer_and_upgrade_gifts: bool | None
can_transfer_stars: bool | None
can_view_gifts_and_stars: bool | None
class telebot_py.types.business.BusinessConnection(id: str, user: User, user_chat_id: int, date: int, is_enabled: bool, rights: BusinessBotRights | None = None)

Bases: TelegramObject

The bot’s connection to a Telegram Business account.

Variables:

  • id (str) – Unique identifier of the business connection.

  • user (telebot_py.types.user.User) – Business account user that created the business connection.

  • user_chat_id (int) – Identifier of a private chat with the user who created the business connection.

  • date (int) – Date the connection was established in Unix time.

  • rights (telebot_py.types.business.BusinessBotRights | None) – Rights of the business bot, if Telegram reported any.

  • is_enabled (bool) – Whether the connection is active.

Telegram API: https://core.telegram.org/bots/api#businessconnection

date: int
id: str
is_enabled: bool
rights: BusinessBotRights | None
user: User
user_chat_id: int
class telebot_py.types.business.BusinessMessagesDeleted(business_connection_id: str, chat: Chat, message_ids: list[int])

Bases: TelegramObject

Messages deleted from a connected business account.

Variables:

  • business_connection_id (str) – Unique identifier of the business connection.

  • chat (telebot_py.types.chat.Chat) – Information about a chat in the business account in which messages were deleted.

  • message_ids (list[int]) – The list of identifiers of deleted messages in the chat of the business account.

Telegram API: https://core.telegram.org/bots/api#businessmessagesdeleted

business_connection_id: str
chat: Chat
message_ids: list[int]
class telebot_py.types.business.ChatBoost(boost_id: str, add_date: int, expiration_date: int, source: ChatBoostSourcePremium | ChatBoostSourceGiftCode | ChatBoostSourceGiveaway)

Bases: TelegramObject

A boost added to a chat by a user.

Variables:

Telegram API: https://core.telegram.org/bots/api#chatboost

add_date: int
boost_id: str
expiration_date: int
source: ChatBoostSourcePremium | ChatBoostSourceGiftCode | ChatBoostSourceGiveaway
class telebot_py.types.business.ChatBoostAdded(boost_count: int)

Bases: TelegramObject

Service message: a user boosted the chat.

Variables:

boost_count (int) – Number of boosts added by the user.

Telegram API: https://core.telegram.org/bots/api#chatboostadded

boost_count: int
class telebot_py.types.business.ChatBoostRemoved(chat: Chat, boost_id: str, remove_date: int, source: ChatBoostSourcePremium | ChatBoostSourceGiftCode | ChatBoostSourceGiveaway)

Bases: TelegramObject

A boost was removed from a chat.

Variables:

Telegram API: https://core.telegram.org/bots/api#chatboostremoved

boost_id: str
chat: Chat
remove_date: int
source: ChatBoostSourcePremium | ChatBoostSourceGiftCode | ChatBoostSourceGiveaway
class telebot_py.types.business.ChatBoostSourceGiftCode(source: str, user: User)

Bases: TelegramObject

The boost was obtained by the creation of a gift code.

Variables:

  • source (str) – Source of the boost, always ‘gift_code’.

  • user (telebot_py.types.user.User) – User for which the gift code was created.

Telegram API: https://core.telegram.org/bots/api#chatboostsourcegiftcode

source: str
user: User
class telebot_py.types.business.ChatBoostSourceGiveaway(source: str, giveaway_message_id: int, user: User | None = None, prize_star_count: int | None = None, is_unclaimed: bool | None = None)

Bases: TelegramObject

The boost was obtained by the creation of a giveaway.

Variables:

  • source (str) – Source of the boost, always ‘giveaway’.

  • giveaway_message_id (int) – Identifier of a message in the chat with the giveaway; the message could have been deleted.

  • user (telebot_py.types.user.User | None) – User that won the prize in the giveaway, if any.

  • prize_star_count (int | None) – Number of Telegram Stars to be split among giveaway winners.

  • is_unclaimed (bool | None) – Whether the giveaway was completed but no user won.

Telegram API: https://core.telegram.org/bots/api#chatboostsourcegiveaway

giveaway_message_id: int
is_unclaimed: bool | None
prize_star_count: int | None
source: str
user: User | None
class telebot_py.types.business.ChatBoostSourcePremium(source: str, user: User)

Bases: TelegramObject

The boost was obtained by subscribing to Telegram Premium.

Variables:

Telegram API: https://core.telegram.org/bots/api#chatboostsourcepremium

source: str
user: User
class telebot_py.types.business.ChatBoostUpdated(chat: Chat, boost: ChatBoost)

Bases: TelegramObject

A chat boost was added or changed.

Variables:

Telegram API: https://core.telegram.org/bots/api#chatboostupdated

boost: ChatBoost
chat: Chat
class telebot_py.types.business.UserChatBoosts(boosts: list[ChatBoost])

Bases: TelegramObject

A list of boosts added to a chat by a user.

Returned by Bot.get_user_chat_boosts.

Variables:

boosts (list[telebot_py.types.business.ChatBoost]) – The list of boosts added to the chat by the user.

Telegram API: https://core.telegram.org/bots/api#userchatboosts

boosts: list[ChatBoost]

telebot_py.types.callback_query

Telegram CallbackQuery type.

class telebot_py.types.callback_query.CallbackQuery(id: str, from_user: User, chat_instance: str, message: Message | None = None, inline_message_id: str | None = None, data: str | None = None, game_short_name: str | None = None)

Bases: TelegramObject

An incoming callback query from an inline keyboard button.

Variables:

  • id (str) – Unique identifier for this query.

  • from_user (telebot_py.types.user.User) – Sender of the query.

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

  • message (telebot_py.types.message.Message | None) – Message sent by the bot with the callback button that originated the query, when it is not too old.

  • inline_message_id (str | None) – Identifier of the message sent via the bot in inline mode that originated the query.

  • data (str | None) – Data associated with the callback button.

  • game_short_name (str | None) – Short name of the Game to be returned, which serves as the unique identifier for the game.

Telegram API: https://core.telegram.org/bots/api#callbackquery

chat_instance: str
data: str | None
from_user: User
game_short_name: str | None
id: str
inline_message_id: str | None
message: Message | None

telebot_py.types.chat_members

Chat membership types: members, administrators, invites, join requests.

Bases: TelegramObject

An invite link for a chat.

Variables:

  • invite_link (str) – The invite link as a string.

  • creator (telebot_py.types.user.User) – Creator of the link.

  • creates_join_request (bool) – Whether users joining via the link need to be approved by chat administrators.

  • is_primary (bool) – Whether the link is primary.

  • is_revoked (bool) – Whether the link is revoked.

  • name (str | None) – Invite link name.

  • expire_date (int | None) – Unix time when the link will expire or has expired.

  • member_limit (int | None) – Maximum number of users that can be members via this link simultaneously; 1-99999.

  • pending_join_request_count (int | None) – Number of pending join requests created using this link.

  • subscription_period (int | None) – Seconds the subscription will be active for.

  • subscription_price (int | None) – Telegram Stars a user must pay initially and after each subscription period.

Telegram API: https://core.telegram.org/bots/api#chatinvitelink

creates_join_request: bool
creator: User
expire_date: int | None
is_primary: bool
is_revoked: bool
member_limit: int | None
name: str | None
pending_join_request_count: int | None
subscription_period: int | None
subscription_price: int | None
class telebot_py.types.chat_members.ChatJoinRequest(chat: Chat, from_user: User, user_chat_id: int, date: int, bio: str | None = None, invite_link: ChatInviteLink | None = None, query_id: str | None = None)

Bases: TelegramObject

A join request sent to a chat.

Variables:

  • chat (telebot_py.types.chat.Chat) – Chat to which the request was sent.

  • from_user (telebot_py.types.user.User) – User that sent the join request.

  • user_chat_id (int) – Identifier of a private chat with the user who sent the join request.

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

  • bio (str | None) – Bio of the user.

  • invite_link (telebot_py.types.chat_members.ChatInviteLink | None) – Chat invite link that was used by the user to send the join request.

  • query_id (str | None) – Identifier of the join request query; for bots assigned to process join requests only.

Telegram API: https://core.telegram.org/bots/api#chatjoinrequest

bio: str | None
chat: Chat
date: int
from_user: User
query_id: str | None
user_chat_id: int
class telebot_py.types.chat_members.ChatMember(status: str, user: User, custom_title: str | None = None, is_anonymous: bool | None = None, can_be_edited: bool | None = None, can_manage_chat: bool | None = None, can_delete_messages: bool | None = None, can_manage_video_chats: bool | None = None, can_restrict_members: bool | None = None, can_promote_members: bool | None = None, can_change_info: bool | None = None, can_invite_users: bool | None = None, can_post_stories: bool | None = None, can_edit_stories: bool | None = None, can_delete_stories: bool | None = None, can_post_messages: bool | None = None, can_edit_messages: bool | None = None, can_pin_messages: bool | None = None, can_manage_topics: bool | None = None, can_send_welcome_messages: bool | None = None, until_date: int | None = None)

Bases: TelegramObject

Information about one member of a chat.

The node reference models ChatMember as one generic interface covering all six statuses (creator, administrator, member, restricted, left, kicked) with status-specific fields optional; Python mirrors that shape exactly, plus ChatMemberAdministrator.

Variables:

  • status (str) – The member’s status in the chat.

  • user (telebot_py.types.user.User) – Information about the user.

  • custom_title (str | None) – Custom title for this user (administrators only).

  • is_anonymous (bool | None) – Whether the user’s presence in the chat is hidden (administrators only).

  • can_be_edited (bool | None) – Whether the bot is allowed to edit administrator privileges of that user.

  • can_manage_chat (bool | None) – Whether the administrator can access the chat event log, get the boost list, etc.

  • can_delete_messages (bool | None) – Whether the administrator can delete messages of other users.

  • can_manage_video_chats (bool | None) – Whether the administrator can manage video chats.

  • can_restrict_members (bool | None) – Whether the administrator can restrict, ban or unban chat members.

  • can_promote_members (bool | None) – Whether the administrator can add new administrators.

  • can_change_info (bool | None) – Whether the user may change the chat title, photo and other settings.

  • can_invite_users (bool | None) – Whether the user may invite new users to the chat.

  • can_post_stories (bool | None) – Whether the administrator can post stories.

  • can_edit_stories (bool | None) – Whether the administrator can edit stories posted by other users.

  • can_delete_stories (bool | None) – Whether the administrator can delete stories posted by other users.

  • can_post_messages (bool | None) – Whether the administrator can post messages in the channel.

  • can_edit_messages (bool | None) – Whether the administrator can edit messages of other users.

  • can_pin_messages (bool | None) – Whether the user may pin messages.

  • can_manage_topics (bool | None) – Whether the user may create, rename, close, and reopen forum topics.

  • can_send_welcome_messages (bool | None) – Whether the administrator can manage chat welcome messages (Bot API 10.3+).

  • until_date (int | None) – Unix time when restrictions will be lifted for this user.

Telegram API: https://core.telegram.org/bots/api#chatmember

can_be_edited: bool | None
can_change_info: bool | None
can_delete_messages: bool | None
can_delete_stories: bool | None
can_edit_messages: bool | None
can_edit_stories: bool | None
can_invite_users: bool | None
can_manage_chat: bool | None
can_manage_topics: bool | None
can_manage_video_chats: bool | None
can_pin_messages: bool | None
can_post_messages: bool | None
can_post_stories: bool | None
can_promote_members: bool | None
can_restrict_members: bool | None
can_send_welcome_messages: bool | None
custom_title: str | None
is_anonymous: bool | None
status: str
until_date: int | None
user: User
class telebot_py.types.chat_members.ChatMemberAdministrator(status: str, user: User, can_be_edited: bool, is_anonymous: bool, can_manage_chat: bool, can_delete_messages: bool, can_manage_video_chats: bool, can_restrict_members: bool, can_promote_members: bool, can_change_info: bool, can_invite_users: bool, can_post_stories: bool | None = None, can_edit_stories: bool | None = None, can_delete_stories: bool | None = None, can_post_messages: bool | None = None, can_edit_messages: bool | None = None, can_pin_messages: bool | None = None, can_manage_topics: bool | None = None, can_manage_direct_messages: bool | None = None, can_manage_tags: bool | None = None, can_send_welcome_messages: bool | None = None, custom_title: str | None = None)

Bases: TelegramObject

A chat member that has some additional privileges.

Variables:

  • status (str) – The member’s status in the chat, always ‘administrator’.

  • user (telebot_py.types.user.User) – Information about the user.

  • can_be_edited (bool) – Whether the bot is allowed to edit administrator privileges of that user.

  • is_anonymous (bool) – Whether the user’s presence in the chat is hidden.

  • can_manage_chat (bool) – Whether the administrator can access the chat event log, get the boost list, see hidden members, etc.

  • can_delete_messages (bool) – Whether the administrator can delete messages of other users.

  • can_manage_video_chats (bool) – Whether the administrator can manage video chats.

  • can_restrict_members (bool) – Whether the administrator can restrict, ban or unban chat members.

  • can_promote_members (bool) – Whether the administrator can add new administrators with a subset of their own privileges.

  • can_change_info (bool) – Whether the user may change the chat title, photo and other settings.

  • can_invite_users (bool) – Whether the user may invite new users to the chat.

  • can_post_stories (bool | None) – Whether the administrator can post stories.

  • can_edit_stories (bool | None) – Whether the administrator can edit stories posted by other users.

  • can_delete_stories (bool | None) – Whether the administrator can delete stories posted by other users.

  • can_post_messages (bool | None) – Whether the administrator can post messages in the channel.

  • can_edit_messages (bool | None) – Whether the administrator can edit messages of other users.

  • can_pin_messages (bool | None) – Whether the user may pin messages.

  • can_manage_topics (bool | None) – Whether the user may create, rename, close, and reopen forum topics.

  • can_manage_direct_messages (bool | None) – Whether the administrator can manage direct messages of the channel.

  • can_manage_tags (bool | None) – Whether the administrator can edit the tags of regular members.

  • can_send_welcome_messages (bool | None) – Whether the administrator can manage chat welcome messages (Bot API 10.3+).

  • custom_title (str | None) – Custom title for this user.

Telegram API: https://core.telegram.org/bots/api#chatmemberadministrator

can_be_edited: bool
can_change_info: bool
can_delete_messages: bool
can_delete_stories: bool | None
can_edit_messages: bool | None
can_edit_stories: bool | None
can_invite_users: bool
can_manage_chat: bool
can_manage_direct_messages: bool | None
can_manage_tags: bool | None
can_manage_topics: bool | None
can_manage_video_chats: bool
can_pin_messages: bool | None
can_post_messages: bool | None
can_post_stories: bool | None
can_promote_members: bool
can_restrict_members: bool
can_send_welcome_messages: bool | None
custom_title: str | None
is_anonymous: bool
status: str
user: User
class telebot_py.types.chat_members.ChatMemberUpdated(chat: Chat, from_user: User, date: int, old_chat_member: ChatMember, new_chat_member: ChatMember, invite_link: ChatInviteLink | None = None, via_join_request: bool | None = None, via_chat_folder_invite_link: bool | None = None)

Bases: TelegramObject

A change in the status of a chat member.

Variables:

Telegram API: https://core.telegram.org/bots/api#chatmemberupdated

chat: Chat
date: int
from_user: User
new_chat_member: ChatMember
old_chat_member: ChatMember
via_join_request: bool | None
class telebot_py.types.chat_members.Community(id: int, name: str)

Bases: TelegramObject

A community (a group of chats).

Variables:

  • id (int) – Unique identifier for this community.

  • name (str) – Name of the community.

Telegram API: https://core.telegram.org/bots/api#community

id: int
name: str
class telebot_py.types.chat_members.CommunityChatJoined(community: Community)

Bases: TelegramObject

Service message about a chat being joined by a user from a community.

Variables:

community (telebot_py.types.chat_members.Community) – The community from which the chat was joined.

Telegram API: https://core.telegram.org/bots/api#communitychatjoined

community: Community

telebot_py.types.chat

Telegram Chat type plus the nested objects only Chat references.

class telebot_py.types.chat.Birthdate(day: int, month: int, year: int | None = None)

Bases: TelegramObject

Describes the birthdate of a user.

Variables:

  • day (int) – Day of the user’s birth; 1-31.

  • month (int) – Month of the user’s birth; 1-12.

  • year (int | None) – Year of the user’s birth, when known.

Telegram API: https://core.telegram.org/bots/api#birthdate

day: int
month: int
year: int | None
class telebot_py.types.chat.BusinessIntro(title: str | None = None, message: str | None = None, sticker: Sticker | None = None)

Bases: TelegramObject

The intro of a Telegram Business account.

Variables:

  • title (str | None) – Title of the intro message.

  • message (str | None) – Text of the intro message.

  • sticker (telebot_py.types.stickers.Sticker | None) – Sticker of the intro message.

Telegram API: https://core.telegram.org/bots/api#businessintro

message: str | None
sticker: Sticker | None
title: str | None
class telebot_py.types.chat.BusinessLocation(address: str, location: Location | None = None)

Bases: TelegramObject

The location of a Telegram Business account.

Variables:

Telegram API: https://core.telegram.org/bots/api#businesslocation

address: str
location: Location | None
class telebot_py.types.chat.BusinessOpeningHours(time_zone_name: str, opening_hours: list[BusinessOpeningHoursInterval])

Bases: TelegramObject

The opening hours of a Telegram Business account.

Variables:

Telegram API: https://core.telegram.org/bots/api#businessopeninghours

opening_hours: list[BusinessOpeningHoursInterval]
time_zone_name: str
class telebot_py.types.chat.BusinessOpeningHoursInterval(opening_minute: int, closing_minute: int)

Bases: TelegramObject

One interval during which a business is open.

Variables:

  • opening_minute (int) – The minute’s sequence number in a week (0-10079) when the business opens in UTC+0.

  • closing_minute (int) – The minute’s sequence number in a week (1-10080) when the business closes in UTC+0.

Telegram API: https://core.telegram.org/bots/api#businessopeninghoursinterval

closing_minute: int
opening_minute: int
class telebot_py.types.chat.Chat(id: int | str, type: str, title: str | None = None, username: str | None = None, first_name: str | None = None, last_name: str | None = None, is_forum: bool | None = None, is_direct_messages: bool | None = None, photo: ChatPhoto | None = None, active_usernames: list[str] | None = None, birthdate: Birthdate | None = None, business_intro: BusinessIntro | None = None, business_location: BusinessLocation | None = None, business_opening_hours: BusinessOpeningHours | None = None, personal_chat: Chat | None = None, available_reactions: list[object] | None = None, accent_color_id: int | None = None, background_custom_emoji_id: str | None = None, profile_accent_color_id: int | None = None, profile_background_custom_emoji_id: str | None = None, emoji_status_custom_emoji_id: str | None = None, emoji_status_expiration_date: int | None = None, bio: str | None = None, has_private_forwards: bool | None = None, has_restricted_voice_and_video_messages: bool | None = None, join_to_send_messages: bool | None = None, join_by_request: bool | None = None, description: str | None = None, invite_link: str | None = None, pinned_message: Message | None = None, permissions: ChatPermissions | None = None, slow_mode_delay: int | None = None, unrestrict_boost_count: int | None = None, message_auto_delete_time: int | None = None, has_aggressive_anti_spam_enabled: bool | None = None, has_hidden_members: bool | None = None, has_protected_content: bool | None = None, has_visible_history: bool | None = None, sticker_set_name: str | None = None, can_set_sticker_set: bool | None = None, custom_emoji_sticker_set_name: str | None = None, linked_chat_id: int | None = None, location: ChatLocation | None = None)

Bases: TelegramObject

A Telegram chat.

Variables:

  • id (int | str) – Unique identifier for this chat (integer, or a channel username string where the Bot API allows it).

  • type (str) – Type of chat: one of private, group, supergroup, or channel.

  • title (str | None) – Title, for supergroups, channels and group chats.

  • username (str | None) – Username, for private chats, supergroups and channels.

  • first_name (str | None) – First name of the other party in a private chat.

  • last_name (str | None) – Last name of the other party in a private chat.

  • is_forum (bool | None) – Whether the supergroup chat is a forum (topics enabled).

  • is_direct_messages (bool | None) – Whether the chat is the direct messages chat of a channel.

  • photo (telebot_py.types.chat.ChatPhoto | None) – Chat photo.

  • active_usernames (list[str] | None) – If non-empty, the list of all active chat usernames.

  • birthdate (telebot_py.types.chat.Birthdate | None) – For private chats, the date of birth of the user.

  • business_intro (telebot_py.types.chat.BusinessIntro | None) – For private chats with business accounts, the intro.

  • business_location (telebot_py.types.chat.BusinessLocation | None) – For private chats with business accounts, the location of the business.

  • business_opening_hours (telebot_py.types.chat.BusinessOpeningHours | None) – For private chats with business accounts, the opening hours of the business.

  • personal_chat (telebot_py.types.chat.Chat | None) – For private chats, the personal channel of the user.

  • available_reactions (list[object] | None) – List of available reactions allowed in the chat (reaction payloads kept raw per node typing).

  • accent_color_id (int | None) – Identifier of the accent color for the chat name and backgrounds.

  • background_custom_emoji_id (str | None) – Custom emoji identifier chosen for the chat background.

  • profile_accent_color_id (int | None) – Identifier of the accent color for the chat’s profile.

  • profile_background_custom_emoji_id (str | None) – Custom emoji identifier chosen for the chat profile background.

  • emoji_status_custom_emoji_id (str | None) – Custom emoji identifier of the emoji status.

  • emoji_status_expiration_date (int | None) – Expiration date of the emoji status of the chat partner in Unix time.

  • bio (str | None) – Bio of the other party in a private chat.

  • has_private_forwards (bool | None) – Whether privacy settings of the other party in the private chat forbid forwarding messages.

  • has_restricted_voice_and_video_messages (bool | None) – Whether privacy settings of the other party restrict sending voice and video notes.

  • join_to_send_messages (bool | None) – Whether users need to join the supergroup before they can send messages.

  • join_by_request (bool | None) – Whether all new members must be approved by chat administrators.

  • description (str | None) – Description, for groups, supergroups and channel chats.

  • invite_link (str | None) – Primary invite link, for groups, supergroups and channel chats.

  • pinned_message (telebot_py.types.message.Message | None) – The most recent pinned message (by sending date).

  • permissions (telebot_py.types.chat.ChatPermissions | None) – Default chat member permissions, for groups and supergroups.

  • slow_mode_delay (int | None) – For supergroups, the minimum allowed interval between messages in seconds.

  • unrestrict_boost_count (int | None) – For supergroups, the minimum number of boosts needed to bypass slow mode.

  • message_auto_delete_time (int | None) – Seconds after which messages are automatically deleted in the chat.

  • has_aggressive_anti_spam_enabled (bool | None) – Whether aggressive anti-spam checks are enabled in the supergroup.

  • has_hidden_members (bool | None) – Whether non-administrators can only see the list of bot administrators in the chat.

  • has_protected_content (bool | None) – Whether messages from the chat cannot be forwarded to other chats.

  • has_visible_history (bool | None) – Whether new chat members will see historical messages.

  • sticker_set_name (str | None) – For supergroups, name of the group sticker set.

  • can_set_sticker_set (bool | None) – Whether the bot can change the group sticker set.

  • custom_emoji_sticker_set_name (str | None) – For supergroups, name of the custom emoji sticker set.

  • linked_chat_id (int | None) – Unique identifier of the linked discussion chat for channels.

  • location (telebot_py.types.chat.ChatLocation | None) – For supergroups, the location to which the supergroup is connected.

Telegram API: https://core.telegram.org/bots/api#chat

accent_color_id: int | None
active_usernames: list[str] | None
available_reactions: list[object] | None
background_custom_emoji_id: str | None
bio: str | None
birthdate: Birthdate | None
business_intro: BusinessIntro | None
business_location: BusinessLocation | None
business_opening_hours: BusinessOpeningHours | None
can_set_sticker_set: bool | None
custom_emoji_sticker_set_name: str | None
description: str | None
emoji_status_custom_emoji_id: str | None
emoji_status_expiration_date: int | None
first_name: str | None
has_aggressive_anti_spam_enabled: bool | None
has_hidden_members: bool | None
has_private_forwards: bool | None
has_protected_content: bool | None
has_restricted_voice_and_video_messages: bool | None
has_visible_history: bool | None
id: int | str
is_direct_messages: bool | None
is_forum: bool | None
join_by_request: bool | None
join_to_send_messages: bool | None
last_name: str | None
linked_chat_id: int | None
location: ChatLocation | None
message_auto_delete_time: int | None
permissions: ChatPermissions | None
personal_chat: Chat | None
photo: ChatPhoto | None
pinned_message: Message | None
profile_accent_color_id: int | None
profile_background_custom_emoji_id: str | None
slow_mode_delay: int | None
sticker_set_name: str | None
title: str | None
type: str
unrestrict_boost_count: int | None
username: str | None
class telebot_py.types.chat.ChatAdministratorRights(is_anonymous: bool, can_manage_chat: bool, can_delete_messages: bool = False, can_manage_video_chats: bool = False, can_restrict_members: bool = False, can_promote_members: bool = False, can_change_info: bool = False, can_invite_users: bool = False, can_post_stories: bool | None = None, can_edit_stories: bool | None = None, can_delete_stories: bool | None = None, can_post_messages: bool | None = None, can_edit_messages: bool | None = None, can_pin_messages: bool | None = None, can_manage_topics: bool | None = None, can_manage_direct_messages: bool | None = None, can_manage_tags: bool | None = None, can_send_welcome_messages: bool | None = None)

Bases: TelegramObject

The rights of an administrator in a chat.

Telegram may omit individual permission fields from the payload; omitted permissions default to False.

Variables:

  • is_anonymous (bool) – Whether the user’s presence in the chat is hidden.

  • can_manage_chat (bool) – Whether the administrator can access the chat event log, get the boost list, see hidden members, etc.

  • can_delete_messages (bool) – Whether the administrator can delete messages of other users.

  • can_manage_video_chats (bool) – Whether the administrator can manage video chats.

  • can_restrict_members (bool) – Whether the administrator can restrict, ban or unban chat members.

  • can_promote_members (bool) – Whether the administrator can add new administrators with a subset of their own privileges.

  • can_change_info (bool) – Whether the user is allowed to change the chat title, photo and other settings.

  • can_invite_users (bool) – Whether the user is allowed to invite new users to the chat.

  • can_post_stories (bool | None) – Whether the administrator can post stories to the chat.

  • can_edit_stories (bool | None) – Whether the administrator can edit stories posted by other users.

  • can_delete_stories (bool | None) – Whether the administrator can delete stories posted by other users.

  • can_post_messages (bool | None) – Whether the administrator can post messages in the channel, or access channel statistics.

  • can_edit_messages (bool | None) – Whether the administrator can edit messages of other users.

  • can_pin_messages (bool | None) – Whether the user is allowed to pin messages.

  • can_manage_topics (bool | None) – Whether the user is allowed to create, rename, close, and reopen forum topics.

  • can_manage_direct_messages (bool | None) – Whether the administrator can manage direct messages of the channel.

  • can_manage_tags (bool | None) – Whether the administrator can edit the tags of regular members.

  • can_send_welcome_messages (bool | None) – Whether the administrator can manage chat welcome messages (Bot API 10.3+).

Telegram API: https://core.telegram.org/bots/api#chatadministratorrights

can_change_info: bool
can_delete_messages: bool
can_delete_stories: bool | None
can_edit_messages: bool | None
can_edit_stories: bool | None
can_invite_users: bool
can_manage_chat: bool
can_manage_direct_messages: bool | None
can_manage_tags: bool | None
can_manage_topics: bool | None
can_manage_video_chats: bool
can_pin_messages: bool | None
can_post_messages: bool | None
can_post_stories: bool | None
can_promote_members: bool
can_restrict_members: bool
can_send_welcome_messages: bool | None
is_anonymous: bool
class telebot_py.types.chat.ChatLocation(location: Location, address: str)

Bases: TelegramObject

A physical location to which a supergroup is connected.

Variables:

  • location (telebot_py.types.common.Location) – The physical location to which the supergroup is connected.

  • address (str) – Location address; 1-64 characters, as defined by the chat owner.

Telegram API: https://core.telegram.org/bots/api#chatlocation

address: str
location: Location
class telebot_py.types.chat.ChatPermissions(can_send_messages: bool | None = None, can_send_audios: bool | None = None, can_send_documents: bool | None = None, can_send_photos: bool | None = None, can_send_videos: bool | None = None, can_send_video_notes: bool | None = None, can_send_voice_notes: bool | None = None, can_send_polls: bool | None = None, can_send_other_messages: bool | None = None, can_add_web_page_previews: bool | None = None, can_react_to_messages: bool | None = None, can_edit_tag: bool | None = None, can_change_info: bool | None = None, can_invite_users: bool | None = None, can_pin_messages: bool | None = None, can_manage_topics: bool | None = None)

Bases: TelegramObject

Actions a non-administrator user is allowed to take in a chat.

All fields are optional; an unset field means “server default”.

Variables:

  • can_send_messages (bool | None) – Whether the user may send text messages, contacts, locations and venues.

  • can_send_audios (bool | None) – Whether the user may send audios.

  • can_send_documents (bool | None) – Whether the user may send documents.

  • can_send_photos (bool | None) – Whether the user may send photos.

  • can_send_videos (bool | None) – Whether the user may send videos.

  • can_send_video_notes (bool | None) – Whether the user may send video notes.

  • can_send_voice_notes (bool | None) – Whether the user may send voice notes.

  • can_send_polls (bool | None) – Whether the user may send polls.

  • can_send_other_messages (bool | None) – Whether the user may send animations, games, stickers and use inline bots.

  • can_add_web_page_previews (bool | None) – Whether the user may add web page previews to their messages.

  • can_react_to_messages (bool | None) – Whether the user may react to messages. If omitted, defaults to the value of can_send_messages.

  • can_edit_tag (bool | None) – Whether the user may edit their own tag. If omitted, defaults to the value of can_change_info.

  • can_change_info (bool | None) – Whether the user may change the chat title, photo and other settings.

  • can_invite_users (bool | None) – Whether the user may invite new users to the chat.

  • can_pin_messages (bool | None) – Whether the user may pin messages.

  • can_manage_topics (bool | None) – Whether the user may create, rename, close, and reopen forum topics.

Telegram API: https://core.telegram.org/bots/api#chatpermissions

can_add_web_page_previews: bool | None
can_change_info: bool | None
can_edit_tag: bool | None
can_invite_users: bool | None
can_manage_topics: bool | None
can_pin_messages: bool | None
can_react_to_messages: bool | None
can_send_audios: bool | None
can_send_documents: bool | None
can_send_messages: bool | None
can_send_other_messages: bool | None
can_send_photos: bool | None
can_send_polls: bool | None
can_send_video_notes: bool | None
can_send_videos: bool | None
can_send_voice_notes: bool | None
class telebot_py.types.chat.ChatPhoto(small_file_id: str, small_file_unique_id: str, big_file_id: str, big_file_unique_id: str)

Bases: TelegramObject

A chat photo in two sizes.

Variables:

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

  • small_file_unique_id (str) – Unique file identifier of the small photo.

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

  • big_file_unique_id (str) – Unique file identifier of the big photo.

Telegram API: https://core.telegram.org/bots/api#chatphoto

big_file_id: str
big_file_unique_id: str
small_file_id: str
small_file_unique_id: str

telebot_py.types.chat_full_info

The ChatFullInfo object getChat returns, plus what only it uses.

Bot API 7.0 split the documented Chat object in two: Chat keeps the eight identity fields that travel inside every payload, and ChatFullInfo carries the 53 fields that only the getChat method (and the chat-management methods echoing it) returns. Python models both; a payload parsed as Chat silently drops the 45 fields that only exist on this type.

class telebot_py.types.chat_full_info.ChatFullInfo(id: int, type: str, accent_color_id: int, max_reaction_count: int, accepted_gift_types: AcceptedGiftTypes, title: str | None = None, username: str | None = None, first_name: str | None = None, last_name: str | None = None, is_forum: bool | None = None, is_direct_messages: bool | None = None, photo: ChatPhoto | None = None, active_usernames: list[str] | None = None, birthdate: Birthdate | None = None, business_intro: BusinessIntro | None = None, business_location: BusinessLocation | None = None, business_opening_hours: BusinessOpeningHours | None = None, personal_chat: Chat | None = None, parent_chat: Chat | None = None, available_reactions: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid] | None = None, background_custom_emoji_id: str | None = None, profile_accent_color_id: int | None = None, profile_background_custom_emoji_id: str | None = None, emoji_status_custom_emoji_id: str | None = None, emoji_status_expiration_date: int | None = None, bio: str | None = None, has_private_forwards: bool | None = None, has_restricted_voice_and_video_messages: bool | None = None, join_to_send_messages: bool | None = None, join_by_request: bool | None = None, description: str | None = None, invite_link: str | None = None, pinned_message: Message | None = None, permissions: ChatPermissions | None = None, can_send_paid_media: bool | None = None, slow_mode_delay: int | None = None, unrestrict_boost_count: int | None = None, message_auto_delete_time: int | None = None, has_aggressive_anti_spam_enabled: bool | None = None, has_hidden_members: bool | None = None, has_protected_content: bool | None = None, has_visible_history: bool | None = None, sticker_set_name: str | None = None, can_set_sticker_set: bool | None = None, custom_emoji_sticker_set_name: str | None = None, linked_chat_id: int | None = None, location: ChatLocation | None = None, rating: UserRating | None = None, first_profile_audio: Audio | None = None, unique_gift_colors: UniqueGiftColors | None = None, paid_message_star_count: int | None = None, guard_bot: User | None = None, community: Community | None = None)

Bases: TelegramObject

Full information about a chat, as returned by the getChat method.

Extends Chat with the fields that only the getChat response carries. The five fields the docs mark as required (id, type, accent_color_id, max_reaction_count and accepted_gift_types) are declared first because Python dataclasses cannot interleave defaulted fields with required ones; the remaining fields keep their documented order.

Variables:

  • id (int) – Unique identifier for this chat. This number may have more than 32 significant bits, but it has at most 52 significant bits, so a signed 64-bit integer type is safe for storing it.

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

  • accent_color_id (int) – Identifier of the accent color for the chat name and backgrounds of the chat photo, reply header, and link preview.

  • max_reaction_count (int) – The maximum number of reactions that can be set on a message in the chat.

  • accepted_gift_types (telebot_py.types.gifts.AcceptedGiftTypes) – Information about types of gifts that are accepted by the chat or by the corresponding user for private chats.

  • title (str | None) – Title, for supergroups, channels and group chats.

  • username (str | None) – Username, for private chats, supergroups and channels if available.

  • first_name (str | None) – First name of the other party in a private chat.

  • last_name (str | None) – Last name of the other party in a private chat.

  • is_forum (bool | None) – True, if the supergroup chat is a forum (has topics enabled).

  • is_direct_messages (bool | None) – True, if the chat is the direct messages chat of a channel.

  • photo (telebot_py.types.chat.ChatPhoto | None) – Chat photo.

  • active_usernames (list[str] | None) – If non-empty, the list of all active chat usernames; for private chats, supergroups and channels.

  • birthdate (telebot_py.types.chat.Birthdate | None) – For private chats, the date of birth of the user.

  • business_intro (telebot_py.types.chat.BusinessIntro | None) – For private chats with business accounts, the intro of the business.

  • business_location (telebot_py.types.chat.BusinessLocation | None) – For private chats with business accounts, the location of the business.

  • business_opening_hours (telebot_py.types.chat.BusinessOpeningHours | None) – For private chats with business accounts, the opening hours of the business.

  • personal_chat (telebot_py.types.chat.Chat | None) – For private chats, the personal channel of the user.

  • parent_chat (telebot_py.types.chat.Chat | None) – For direct messages chats only, information about the corresponding channel chat.

  • available_reactions (list[telebot_py.types.reactions.ReactionTypeEmoji | telebot_py.types.reactions.ReactionTypeCustomEmoji | telebot_py.types.reactions.ReactionTypePaid] | None) – List of available reactions allowed in the chat. If omitted, then all emoji reactions are allowed.

  • background_custom_emoji_id (str | None) – Custom emoji identifier of the emoji chosen by the chat for the reply header and link preview background.

  • profile_accent_color_id (int | None) – Identifier of the accent color for the chat’s profile background.

  • profile_background_custom_emoji_id (str | None) – Custom emoji identifier of the emoji chosen by the chat for its profile background.

  • emoji_status_custom_emoji_id (str | None) – Custom emoji identifier of the emoji status of the chat or the other party in a private chat.

  • emoji_status_expiration_date (int | None) – Expiration date of the emoji status of the chat or the other party in a private chat, in Unix time, if any.

  • bio (str | None) – Bio of the other party in a private chat.

  • has_private_forwards (bool | None) – True, if privacy settings of the other party in the private chat allows to use t.me/userid?id=<chat_id> links only in chats with the user.

  • has_restricted_voice_and_video_messages (bool | None) – True, if the privacy settings of the other party restrict sending voice and video note messages in the private chat.

  • join_to_send_messages (bool | None) – True, if users need to join the supergroup before they can send messages.

  • join_by_request (bool | None) – True, if all users directly joining the supergroup without using an invite link need to be approved by supergroup administrators.

  • description (str | None) – Description, for groups, supergroups and channel chats.

  • invite_link (str | None) – Primary invite link, for groups, supergroups and channel chats.

  • pinned_message (telebot_py.types.message.Message | None) – The most recent pinned message (by sending date).

  • permissions (telebot_py.types.chat.ChatPermissions | None) – Default chat member permissions, for groups and supergroups.

  • can_send_paid_media (bool | None) – True, if paid media messages can be sent or forwarded to the channel chat. The field is currently only applicable to direct messages chats.

  • slow_mode_delay (int | None) – For supergroups, the minimum allowed delay between consecutive messages sent by each unprivileged user, in seconds.

  • unrestrict_boost_count (int | None) – For supergroups, the minimum number of boosts that a non-administrator user needs to receive to be allowed to bypass slow mode.

  • message_auto_delete_time (int | None) – The time after which all messages sent to the chat will be automatically deleted, in seconds.

  • has_aggressive_anti_spam_enabled (bool | None) – True, if aggressive anti-spam checks are enabled in the supergroup.

  • has_hidden_members (bool | None) – True, if non-administrators can only get the list of bots and administrators in the chat.

  • has_protected_content (bool | None) – True, if messages from the chat can’t be forwarded to other chats.

  • has_visible_history (bool | None) – True, if new chat members will have access to old messages; available only to chat administrators.

  • sticker_set_name (str | None) – For supergroups, name of the group sticker set.

  • can_set_sticker_set (bool | None) – True, if the bot can change the group sticker set.

  • custom_emoji_sticker_set_name (str | None) – For supergroups, the name of the group’s custom emoji sticker set.

  • linked_chat_id (int | None) – Unique identifier for the linked chat, i.e. the discussion group identifier for a channel and vice versa; for supergroups and channel chats.

  • location (telebot_py.types.chat.ChatLocation | None) – For supergroups, the location to which the supergroup is connected.

  • rating (telebot_py.types.chat_full_info.UserRating | None) – For private chats, the rating of the user if any.

  • first_profile_audio (telebot_py.types.media.Audio | None) – For private chats, the first audio added to the profile of the user.

  • unique_gift_colors (telebot_py.types.gifts.UniqueGiftColors | None) – The color scheme based on a unique gift that must be used for the chat’s name, members, and messages.

  • paid_message_star_count (int | None) – The number of Telegram Stars a general user has to pay to send a message to the chat; for channels and direct messages chats only.

  • guard_bot (telebot_py.types.user.User | None) – The bot that processes join request queries in the chat.

  • community (telebot_py.types.chat_members.Community | None) – The Community to which the chat belongs.

Telegram API: https://core.telegram.org/bots/api#chatfullinfo

accent_color_id: int
accepted_gift_types: AcceptedGiftTypes
active_usernames: list[str] | None
available_reactions: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid] | None
background_custom_emoji_id: str | None
bio: str | None
birthdate: Birthdate | None
business_intro: BusinessIntro | None
business_location: BusinessLocation | None
business_opening_hours: BusinessOpeningHours | None
can_send_paid_media: bool | None
can_set_sticker_set: bool | None
community: Community | None
custom_emoji_sticker_set_name: str | None
description: str | None
emoji_status_custom_emoji_id: str | None
emoji_status_expiration_date: int | None
first_name: str | None
first_profile_audio: Audio | None
guard_bot: User | None
has_aggressive_anti_spam_enabled: bool | None
has_hidden_members: bool | None
has_private_forwards: bool | None
has_protected_content: bool | None
has_restricted_voice_and_video_messages: bool | None
has_visible_history: bool | None
id: int
is_direct_messages: bool | None
is_forum: bool | None
join_by_request: bool | None
join_to_send_messages: bool | None
last_name: str | None
linked_chat_id: int | None
location: ChatLocation | None
max_reaction_count: int
message_auto_delete_time: int | None
paid_message_star_count: int | None
parent_chat: Chat | None
permissions: ChatPermissions | None
personal_chat: Chat | None
photo: ChatPhoto | None
pinned_message: Message | None
profile_accent_color_id: int | None
profile_background_custom_emoji_id: str | None
rating: UserRating | None
slow_mode_delay: int | None
sticker_set_name: str | None
title: str | None
type: str
unique_gift_colors: UniqueGiftColors | None
unrestrict_boost_count: int | None
username: str | None
class telebot_py.types.chat_full_info.UserRating(level: int, rating: int, current_level_rating: int, next_level_rating: int | None = None)

Bases: TelegramObject

The rating of a user based on their Telegram Star spendings.

Variables:

  • level (int) – Current level of the user, indicating their reliability when purchasing digital goods and services. A higher level suggests a more trustworthy customer.

  • rating (int) – Numerical value of the user’s rating; the higher the rating, the better.

  • current_level_rating (int) – The rating value required to get the current level.

  • next_level_rating (int | None) – The rating value required to get to the next level; omitted if the maximum level was reached.

Telegram API: https://core.telegram.org/bots/api#userrating

current_level_rating: int
level: int
next_level_rating: int | None
rating: int

telebot_py.types.checklists

Checklist types for checklist messages (Bot API 10.2+).

Telegram documents Checklist, ChecklistTask, InputChecklist and InputChecklistTask; the node sibling passes checklist payloads through as untyped records, so these classes follow the Bot API field set exactly.

class telebot_py.types.checklists.Checklist(title: str, tasks: list[ChecklistTask], title_entities: list[MessageEntity] | None = None, others_can_add_tasks: bool | None = None, others_can_mark_tasks_as_done: bool | None = None)

Bases: TelegramObject

A checklist received in a message.

Variables:

  • title (str) – Title of the checklist.

  • tasks (list[telebot_py.types.checklists.ChecklistTask]) – List of tasks in the checklist.

  • title_entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the checklist title.

  • others_can_add_tasks (bool | None) – Whether users other than the creator can add tasks to the list.

  • others_can_mark_tasks_as_done (bool | None) – Whether users other than the creator can mark tasks as done or not done.

Telegram API: https://core.telegram.org/bots/api#checklist

others_can_add_tasks: bool | None
others_can_mark_tasks_as_done: bool | None
tasks: list[ChecklistTask]
title: str
title_entities: list[MessageEntity] | None
class telebot_py.types.checklists.ChecklistTask(id: int, text: str, text_entities: list[MessageEntity] | None = None, completed_by_user: User | None = None, completed_by_chat: Chat | None = None, completion_date: int | None = None)

Bases: TelegramObject

A task in a received checklist.

Variables:

  • id (int) – Unique identifier of the task.

  • text (str) – Text of the task.

  • text_entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the task text.

  • completed_by_user (telebot_py.types.user.User | None) – User that completed the task; absent when the task wasn’t completed by a user.

  • completed_by_chat (telebot_py.types.chat.Chat | None) – Chat that completed the task; absent when the task wasn’t completed by a chat.

  • completion_date (int | None) – Point in time (Unix timestamp) when the task was completed; 0 if the task wasn’t completed.

Telegram API: https://core.telegram.org/bots/api#checklisttask

completed_by_chat: Chat | None
completed_by_user: User | None
completion_date: int | None
id: int
text: str
text_entities: list[MessageEntity] | None
class telebot_py.types.checklists.InputChecklist(title: str, tasks: list[InputChecklistTask], parse_mode: str | None = None, title_entities: list[MessageEntity] | None = None, others_can_add_tasks: bool | None = None, others_can_mark_tasks_as_done: bool | None = None)

Bases: TelegramObject

A checklist to send or edit.

Variables:

  • title (str) – Title of the checklist; 1-255 characters after entities parsing.

  • tasks (list[telebot_py.types.checklists.InputChecklistTask]) – List of 1-30 tasks in the checklist.

  • parse_mode (str | None) – Mode for parsing entities in the title.

  • title_entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the title, which can be specified instead of parse_mode.

  • others_can_add_tasks (bool | None) – Whether other users can add tasks to the checklist.

  • others_can_mark_tasks_as_done (bool | None) – Whether other users can mark tasks as done or not done in the checklist.

Telegram API: https://core.telegram.org/bots/api#inputchecklist

others_can_add_tasks: bool | None
others_can_mark_tasks_as_done: bool | None
parse_mode: str | None
tasks: list[InputChecklistTask]
title: str
title_entities: list[MessageEntity] | None
class telebot_py.types.checklists.InputChecklistTask(id: int, text: str, parse_mode: str | None = None, text_entities: list[MessageEntity] | None = None)

Bases: TelegramObject

A task to add to a checklist.

Variables:

  • id (int) – Unique identifier of the task; must be positive and unique among all task identifiers currently present in the checklist.

  • text (str) – Text of the task; 1-100 characters after entities parsing.

  • parse_mode (str | None) – Mode for parsing entities in the text.

  • text_entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the text, which can be specified instead of parse_mode.

Telegram API: https://core.telegram.org/bots/api#inputchecklisttask

id: int
parse_mode: str | None
text: str
text_entities: list[MessageEntity] | None

telebot_py.types.common

Shared small Telegram API types used across the core types.

class telebot_py.types.common.ChosenInlineResult(result_id: str, from_user: User, query: str, location: Location | None = None, inline_message_id: str | None = None)

Bases: TelegramObject

The result of an inline query chosen by a user and sent to a partner.

Variables:

  • result_id (str) – Unique identifier for the result that was chosen.

  • from_user (telebot_py.types.user.User) – The user that chose the result.

  • query (str) – The query that was used to obtain the result.

  • location (telebot_py.types.common.Location | None) – Sender location, only for bots that require user location.

  • inline_message_id (str | None) – Identifier of the sent inline message, available only if there is an inline keyboard attached to the message.

Telegram API: https://core.telegram.org/bots/api#choseninlineresult

from_user: User
inline_message_id: str | None
location: Location | None
query: str
result_id: str
class telebot_py.types.common.Contact(phone_number: str, first_name: str, last_name: str | None = None, user_id: int | None = None, vcard: str | None = None)

Bases: TelegramObject

A shared phone contact.

Variables:

  • phone_number (str) – Contact’s phone number.

  • first_name (str) – Contact’s first name.

  • last_name (str | None) – Contact’s last name, when present.

  • user_id (int | None) – Contact’s user identifier in Telegram, when present.

  • vcard (str | None) – Additional data about the contact in the form of a vCard.

Telegram API: https://core.telegram.org/bots/api#contact

first_name: str
last_name: str | None
phone_number: str
user_id: int | None
vcard: str | None
class telebot_py.types.common.Dice(emoji: str, value: int)

Bases: TelegramObject

An animated emoji with a random value.

Variables:

  • emoji (str) – Emoji on which the dice throw animation is based.

  • value (int) – Value of the dice (e.g. 1-6 for dice/darts, 1-5 for basketball/football, 1-64 for the slot machine).

Telegram API: https://core.telegram.org/bots/api#dice

emoji: str
value: int
class telebot_py.types.common.InlineQuery(id: str, from_user: User, query: str, offset: str, chat_type: str | None = None, location: Location | None = None)

Bases: TelegramObject

An incoming inline query.

Variables:

  • id (str) – Unique identifier for this query.

  • from_user (telebot_py.types.user.User) – Sender of the inline query.

  • query (str) – Text of the query (up to 256 characters).

  • offset (str) – Offset of the results to be returned.

  • chat_type (str | None) – Type of the chat from which the inline query was sent (‘sender’, ‘private’, ‘group’, ‘supergroup’, or ‘channel’).

  • location (telebot_py.types.common.Location | None) – Sender location, only for bots that request user location.

Telegram API: https://core.telegram.org/bots/api#inlinequery

chat_type: str | None
from_user: User
id: str
location: Location | None
offset: str
query: str
class telebot_py.types.common.LinkPreviewOptions(url: str | None = None, is_disabled: bool | None = None, prefer_small_media: bool | None = None, prefer_large_media: bool | None = None, show_above_text: bool | None = None)

Bases: TelegramObject

Controls link preview generation for a message.

Every field is optional, so an empty instance means “use the defaults” rather than “no preview” — pass is_disabled=True to suppress the preview entirely.

Variables:

  • url (str | None) – URL used for the link preview. If empty, then the first URL found in the message text is used.

  • is_disabled (bool | None) – Pass True to disable link preview generation for the message, regardless of the value in url.

  • prefer_small_media (bool | None) – Pass True if the link preview should show a smaller media content.

  • prefer_large_media (bool | None) – Pass True if the link preview should show a media content larger than a small one.

  • show_above_text (bool | None) – Pass True if the link preview should be shown above the message text.

Telegram API: https://core.telegram.org/bots/api#linkpreviewoptions

is_disabled: bool | None
prefer_large_media: bool | None
prefer_small_media: bool | None
show_above_text: bool | None
url: str | None
class telebot_py.types.common.Location(latitude: float, longitude: float, horizontal_accuracy: float | None = None, live_period: int | None = None, heading: int | None = None, proximity_alert_radius: int | None = None)

Bases: TelegramObject

A point on the map.

Variables:

  • latitude (float) – Latitude as defined by sender.

  • longitude (float) – Longitude as defined by sender.

  • horizontal_accuracy (float | None) – Radius of uncertainty in meters; 0-1500.

  • live_period (int | None) – Seconds relative to the message sending date during which the location can be updated.

  • heading (int | None) – Direction in which the user is moving, in degrees; 1-360.

  • proximity_alert_radius (int | None) – Maximum distance in meters for proximity alerts about approaching another chat member.

Telegram API: https://core.telegram.org/bots/api#location

heading: int | None
horizontal_accuracy: float | None
latitude: float
live_period: int | None
longitude: float
proximity_alert_radius: int | None
class telebot_py.types.common.MessageEntity(type: str, offset: int, length: int, url: str | None = None, user: User | None = None, language: str | None = None, custom_emoji_id: str | None = None, unix_time: int | None = None, date_time_format: str | None = None)

Bases: TelegramObject

A special entity in a text message (bot command, mention, link, …).

Variables:

  • type (str) – Type of the entity (e.g. bot_command, mention, url).

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

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

  • url (str | None) – For text_link only, URL that will be opened after tapping.

  • user (telebot_py.types.user.User | None) – For text_mention only, the mentioned user.

  • language (str | None) – For pre only, the programming language of the entity.

  • custom_emoji_id (str | None) – For custom_emoji only, unique identifier of the custom emoji.

  • unix_time (int | None) – For date_time only, the Unix time associated with the entity.

  • date_time_format (str | None) – For date_time only, the string that defines the formatting of the date and time.

Telegram API: https://core.telegram.org/bots/api#messageentity

custom_emoji_id: str | None
date_time_format: str | None
language: str | None
length: int
offset: int
type: str
unix_time: int | None
url: str | None
user: User | None
class telebot_py.types.common.MessageId(message_id: int)

Bases: TelegramObject

A unique identifier of a message, e.g. after a copy.

Variables:

message_id (int) – Unique message identifier.

Telegram API: https://core.telegram.org/bots/api#messageid

message_id: int
class telebot_py.types.common.ResponseParameters(migrate_to_chat_id: int | None = None, retry_after: int | None = None)

Bases: TelegramObject

Why a request was unsuccessful.

Telegram puts this object in the parameters field of a failed response; Bot already reads retry_after out of the error payload for its retry schedule, and the type lets callers inspect the same data.

Variables:

  • migrate_to_chat_id (int | None) – The group has been migrated to a supergroup with the specified identifier.

  • retry_after (int | None) – In case of exceeding flood control, the number of seconds left to wait before the request can be repeated.

Telegram API: https://core.telegram.org/bots/api#responseparameters

migrate_to_chat_id: int | None
retry_after: int | None
class telebot_py.types.common.Venue(location: Location, title: str, address: str, foursquare_id: str | None = None, foursquare_type: str | None = None, google_place_id: str | None = None, google_place_type: str | None = None)

Bases: TelegramObject

A venue with a location and provider identifiers.

Variables:

  • location (telebot_py.types.common.Location) – Venue location.

  • title (str) – Name of the venue.

  • address (str) – Address of the venue.

  • foursquare_id (str | None) – Foursquare identifier of the venue.

  • foursquare_type (str | None) – Foursquare type of the venue.

  • google_place_id (str | None) – Google Places identifier of the venue.

  • google_place_type (str | None) – Google Places type of the venue.

Telegram API: https://core.telegram.org/bots/api#venue

address: str
foursquare_id: str | None
foursquare_type: str | None
google_place_id: str | None
google_place_type: str | None
location: Location
title: str
class telebot_py.types.common.WebhookInfo(url: str, has_custom_certificate: bool, pending_update_count: int, ip_address: str | None = None, last_error_date: int | None = None, last_error_message: str | None = None, last_synchronization_error_date: int | None = None, max_connections: int | None = None, allowed_updates: list[str] | None = None)

Bases: TelegramObject

Current status of a webhook.

Variables:

  • url (str) – Webhook URL, empty if the webhook is not set.

  • has_custom_certificate (bool) – Whether a custom certificate was provided.

  • pending_update_count (int) – Number of updates awaiting delivery.

  • ip_address (str | None) – Currently used webhook IP address.

  • last_error_date (int | None) – Unix time of the most recent failed delivery.

  • last_error_message (str | None) – Error message of the most recent failed delivery.

  • last_synchronization_error_date (int | None) – Unix time of the most recent automatic synchronization error.

  • max_connections (int | None) – Maximum allowed simultaneous connections, when set.

  • allowed_updates (list[str] | None) – Update types the bot subscribed to, when restricted.

Telegram API: https://core.telegram.org/bots/api#webhookinfo

allowed_updates: list[str] | None
has_custom_certificate: bool
ip_address: str | None
last_error_date: int | None
last_error_message: str | None
last_synchronization_error_date: int | None
max_connections: int | None
pending_update_count: int
url: str

telebot_py.types.files

Telegram file-download and profile-photo types.

class telebot_py.types.files.File(file_id: str, file_unique_id: str, file_size: int | None = None, file_path: str | None = None)

Bases: TelegramObject

A file ready to be downloaded.

Variables:

  • file_id (str) – Identifier for this file, which can be used to download or reuse the file.

  • file_unique_id (str) – Unique identifier for this file, which is supposed to be the same over time and for different bots.

  • file_size (int | None) – File size in bytes.

  • file_path (str | None) – File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file.

Telegram API: https://core.telegram.org/bots/api#file

file_id: str
file_path: str | None
file_size: int | None
file_unique_id: str
class telebot_py.types.files.UserProfileAudios(total_count: int, audios: list[Audio])

Bases: TelegramObject

The audios displayed on a user’s profile.

Variables:

  • total_count (int) – Total number of profile audios for the target user.

  • audios (list[telebot_py.types.media.Audio]) – Requested profile audios.

Telegram API: https://core.telegram.org/bots/api#userprofileaudios

audios: list[Audio]
total_count: int
class telebot_py.types.files.UserProfilePhotos(total_count: int, photos: list[list[PhotoSize]])

Bases: TelegramObject

A user’s profile pictures.

Variables:

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

  • photos (list[list[telebot_py.types.media.PhotoSize]]) – Requested profile pictures (in up to 4 sizes each).

Telegram API: https://core.telegram.org/bots/api#userprofilephotos

photos: list[list[PhotoSize]]
total_count: int

telebot_py.types.games

Telegram game types: CallbackGame, Game and GameHighScore.

class telebot_py.types.games.CallbackGame

Bases: TelegramObject

A placeholder, empty response sent when a game button is pressed.

Telegram API: https://core.telegram.org/bots/api#callbackgame

class telebot_py.types.games.Game(title: str, description: str, photo: list[PhotoSize], text: str | None = None, text_entities: list[MessageEntity] | None = None, animation: Animation | None = None)

Bases: TelegramObject

A game offered by a bot.

Variables:

Telegram API: https://core.telegram.org/bots/api#game

animation: Animation | None
description: str
photo: list[PhotoSize]
text: str | None
text_entities: list[MessageEntity] | None
title: str
class telebot_py.types.games.GameHighScore(position: int, user: User, score: int)

Bases: TelegramObject

One row of the high scores table for a game.

Variables:

  • position (int) – Position in the high score table for the game.

  • user (telebot_py.types.user.User) – User who scored the points.

  • score (int) – Score value.

Telegram API: https://core.telegram.org/bots/api#gamehighscore

position: int
score: int
user: User

telebot_py.types.gifts

Telegram gift, collectible-gift, and owned-gift types.

Field sets mirror the authoritative TypeScript sources packages/node/src/client/types/payments/models.ts (Gift, Gifts, UniqueGift*) extended with the owned-gift containers and AcceptedGiftTypes that the gifts Bot API methods return and accept.

class telebot_py.types.gifts.AcceptedGiftTypes(unlimited_gifts: bool, limited_gifts: bool, unique_gifts: bool, premium_subscription: bool, gifts_from_channels: bool)

Bases: TelegramObject

Information about types of gifts accepted by a user or business account.

Variables:

  • unlimited_gifts (bool) – True, if unlimited regular gifts are accepted.

  • limited_gifts (bool) – True, if limited regular gifts are accepted.

  • unique_gifts (bool) – True, if unique gifts or gifts that can be upgraded to unique for free are accepted.

  • premium_subscription (bool) – True, if a Telegram Premium subscription is accepted.

  • gifts_from_channels (bool) – True, if gifts from channels are accepted.

Telegram API: https://core.telegram.org/bots/api#acceptedgifttypes

gifts_from_channels: bool
limited_gifts: bool
premium_subscription: bool
unique_gifts: bool
unlimited_gifts: bool
class telebot_py.types.gifts.Gift(id: str, sticker: Sticker, star_count: int, upgrade_star_count: int | None = None, is_premium: bool | None = None, has_colors: bool | None = None, total_count: int | None = None, remaining_count: int | None = None, personal_total_count: int | None = None, personal_remaining_count: int | None = None, background: GiftBackground | None = None, unique_gift_variant_count: int | None = None, publisher_chat: Chat | None = None)

Bases: TelegramObject

This object represents a gift that can be sent by the bot.

Variables:

  • id (str) – Unique identifier of the gift.

  • sticker (telebot_py.types.stickers.Sticker) – The sticker that represents the gift.

  • star_count (int) – Number of Telegram Stars that must be paid to send the sticker.

  • upgrade_star_count (int | None) – Number of Telegram Stars that must be paid to upgrade the gift to a unique one.

  • is_premium (bool | None) – True, if the gift can only be purchased by Telegram Premium subscribers.

  • has_colors (bool | None) – True, if the gift can be used (after being upgraded) to customize a user’s appearance.

  • total_count (int | None) – The total number of the gifts of this type that can be sent; for limited gifts only.

  • remaining_count (int | None) – The number of remaining gifts of this type that can be sent; for limited gifts only.

  • personal_total_count (int | None) – The total number of gifts of this type that can be sent by the bot; for limited gifts only.

  • personal_remaining_count (int | None) – The number of remaining gifts of this type that can be sent by the bot; for limited gifts only.

  • background (telebot_py.types.gifts.GiftBackground | None) – Background of the gift.

  • unique_gift_variant_count (int | None) – The total number of different unique gifts that can be obtained by upgrading the gift.

  • publisher_chat (telebot_py.types.chat.Chat | None) – Information about the chat that published the gift.

Telegram API: https://core.telegram.org/bots/api#gift

background: GiftBackground | None
has_colors: bool | None
id: str
is_premium: bool | None
personal_remaining_count: int | None
personal_total_count: int | None
publisher_chat: Chat | None
remaining_count: int | None
star_count: int
sticker: Sticker
total_count: int | None
unique_gift_variant_count: int | None
upgrade_star_count: int | None
class telebot_py.types.gifts.GiftBackground(center_color: int, edge_color: int, text_color: int)

Bases: TelegramObject

This object describes the background of a gift.

Variables:

  • center_color (int) – Center color of the background in RGB format.

  • edge_color (int) – Edge color of the background in RGB format.

  • text_color (int) – Text color of the background in RGB format.

Telegram API: https://core.telegram.org/bots/api#giftbackground

center_color: int
edge_color: int
text_color: int
class telebot_py.types.gifts.GiftInfo(gift: Gift, owned_gift_id: str | None = None, convert_star_count: int | None = None, prepaid_upgrade_star_count: int | None = None, is_upgrade_separate: bool | None = None, can_be_upgraded: bool | None = None, text: str | None = None, entities: list[MessageEntity] | None = None, is_private: bool | None = None, unique_gift_number: int | None = None)

Bases: TelegramObject

Information about a regular gift that was sent or received.

Carried by the Message fields gift and gift_upgrade_sent.

Variables:

  • gift (telebot_py.types.gifts.Gift) – Information about the gift.

  • owned_gift_id (str | None) – Unique identifier of the received gift for the bot; only present for gifts received on behalf of business accounts.

  • convert_star_count (int | None) – Number of Telegram Stars that can be claimed by the receiver by converting the gift; omitted if the gift cannot be converted to stars.

  • prepaid_upgrade_star_count (int | None) – Number of Telegram Stars that were prepaid for the ability to upgrade the gift.

  • is_upgrade_separate (bool | None) – Whether the gift’s upgrade was purchased after the gift was sent.

  • can_be_upgraded (bool | None) – Whether the gift can be upgraded to a unique gift.

  • text (str | None) – Text of the message that was added to the gift.

  • entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in text.

  • is_private (bool | None) – Whether the sender and the gift text are shown only to the gift receiver.

  • unique_gift_number (int | None) – Unique number reserved for this gift when upgraded.

Telegram API: https://core.telegram.org/bots/api#giftinfo

can_be_upgraded: bool | None
convert_star_count: int | None
entities: list[MessageEntity] | None
gift: Gift
is_private: bool | None
is_upgrade_separate: bool | None
owned_gift_id: str | None
prepaid_upgrade_star_count: int | None
text: str | None
unique_gift_number: int | None
class telebot_py.types.gifts.Gifts(gifts: list[Gift])

Bases: TelegramObject

A list of gifts.

Returned by Bot.get_available_gifts.

Variables:

gifts (list[telebot_py.types.gifts.Gift]) – The list of gifts.

Telegram API: https://core.telegram.org/bots/api#gifts

gifts: list[Gift]
telebot_py.types.gifts.OwnedGift = telebot_py.types.gifts.OwnedGiftRegular | telebot_py.types.gifts.OwnedGiftUnique

A single entry of an OwnedGifts list — regular or unique.

class telebot_py.types.gifts.OwnedGiftRegular(type: str, gift: Gift, send_date: int, owned_gift_id: str | None = None, sender_user: User | None = None, text: str | None = None, entities: list[MessageEntity] | None = None, is_private: bool | None = None, is_saved: bool | None = None, can_be_upgraded: bool | None = None, was_refunded: bool | None = None, convert_star_count: int | None = None, prepaid_upgrade_star_count: int | None = None, is_upgrade_separate: bool | None = None, unique_gift_number: int | None = None)

Bases: TelegramObject

A regular (non-unique) gift owned by a user or chat.

Variables:

  • type (str) – Type of the owned gift, always regular.

  • gift (telebot_py.types.gifts.Gift) – Information about the gift.

  • send_date (int) – Point in time (Unix timestamp) when the gift was sent.

  • owned_gift_id (str | None) – Unique identifier of the received gift for the bot; only present if the bot has a relationship with the sender.

  • sender_user (telebot_py.types.user.User | None) – Identifier of the user that sent the gift, if any.

  • text (str | None) – Text of the message that was added to the gift.

  • entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the text.

  • is_private (bool | None) – True, if the sender and gift text are shown only to the gift receiver.

  • is_saved (bool | None) – True, if the gift is saved by the recipient.

  • can_be_upgraded (bool | None) – True, if the gift can be upgraded to a unique gift.

  • was_refunded (bool | None) – True, if the gift was refunded and isn’t available anymore.

  • convert_star_count (int | None) – Number of Telegram Stars that can be claimed by the receiver instead of sending the gift.

  • prepaid_upgrade_star_count (int | None) – Number of Telegram Stars that were paid by the sender from the bot’s balance to make the upgrade free for the receiver.

  • is_upgrade_separate (bool | None) – True, if the gift can be upgraded to a unique gift only after it is converted to stars.

  • unique_gift_number (int | None) – Unique number of the upgraded gift the regular gift was converted from.

Telegram API: https://core.telegram.org/bots/api#ownedgiftregular

can_be_upgraded: bool | None
convert_star_count: int | None
entities: list[MessageEntity] | None
gift: Gift
is_private: bool | None
is_saved: bool | None
is_upgrade_separate: bool | None
owned_gift_id: str | None
prepaid_upgrade_star_count: int | None
send_date: int
sender_user: User | None
text: str | None
type: str
unique_gift_number: int | None
was_refunded: bool | None
class telebot_py.types.gifts.OwnedGiftUnique(type: str, gift: UniqueGift, send_date: int, owned_gift_id: str | None = None, sender_user: User | None = None, is_saved: bool | None = None, can_be_transferred: bool | None = None, transfer_star_count: int | None = None, next_transfer_date: int | None = None)

Bases: TelegramObject

A unique collectible gift owned by a user or chat.

Variables:

  • type (str) – Type of the owned gift, always unique.

  • gift (telebot_py.types.gifts.UniqueGift) – Information about the gift.

  • send_date (int) – Point in time (Unix timestamp) when the gift was sent.

  • owned_gift_id (str | None) – Unique identifier of the received gift for the bot; only present if the bot has a relationship with the sender.

  • sender_user (telebot_py.types.user.User | None) – Identifier of the user that sent the gift, if any.

  • is_saved (bool | None) – True, if the gift is saved by the recipient.

  • can_be_transferred (bool | None) – True, if the gift can be transferred to another owner.

  • transfer_star_count (int | None) – Number of Telegram Stars that must be paid to transfer the gift; omitted if the bot cannot transfer the gift.

  • next_transfer_date (int | None) – Point in time (Unix timestamp) when the gift can be transferred.

Telegram API: https://core.telegram.org/bots/api#ownedgiftunique

can_be_transferred: bool | None
gift: UniqueGift
is_saved: bool | None
next_transfer_date: int | None
owned_gift_id: str | None
send_date: int
sender_user: User | None
transfer_star_count: int | None
type: str
class telebot_py.types.gifts.OwnedGifts(total_count: int, gifts: list[OwnedGiftRegular | OwnedGiftUnique], next_offset: str | None = None)

Bases: TelegramObject

A list of gifts owned by a user, a chat, or a business account.

Returned by Bot.get_user_gifts, Bot.get_chat_gifts and Bot.get_business_account_gifts.

Variables:

Telegram API: https://core.telegram.org/bots/api#ownedgifts

gifts: list[OwnedGiftRegular | OwnedGiftUnique]
next_offset: str | None
total_count: int
class telebot_py.types.gifts.UniqueGift(gift_id: str, base_name: str, name: str, number: int, model: UniqueGiftModel, symbol: UniqueGiftSymbol, backdrop: UniqueGiftBackdrop, is_premium: bool | None = None, is_burned: bool | None = None, is_from_blockchain: bool | None = None, colors: UniqueGiftColors | None = None, publisher_chat: Chat | None = None)

Bases: TelegramObject

This object represents a unique gift.

Variables:

  • gift_id (str) – Identifier of the regular gift from which this unique gift was upgraded.

  • base_name (str) – Human-readable name of the regular gift; may be empty if the gift was not upgraded.

  • name (str) – Unique name of the gift.

  • number (int) – Unique number of the upgraded gift.

  • model (telebot_py.types.gifts.UniqueGiftModel) – The model of the gift.

  • symbol (telebot_py.types.gifts.UniqueGiftSymbol) – The symbol of the gift.

  • backdrop (telebot_py.types.gifts.UniqueGiftBackdrop) – The backdrop of the gift.

  • is_premium (bool | None) – True, if the original regular gift was exclusively purchaseable by Telegram Premium subscribers.

  • is_burned (bool | None) – True, if the gift was used to craft another gift and isn’t available anymore.

  • is_from_blockchain (bool | None) – True, if the gift is assigned from the TON blockchain.

  • colors (telebot_py.types.gifts.UniqueGiftColors | None) – The color scheme for user’s name, replies, etc.

  • publisher_chat (telebot_py.types.chat.Chat | None) – Information about the chat that published the gift.

Telegram API: https://core.telegram.org/bots/api#uniquegift

backdrop: UniqueGiftBackdrop
base_name: str
colors: UniqueGiftColors | None
gift_id: str
is_burned: bool | None
is_from_blockchain: bool | None
is_premium: bool | None
model: UniqueGiftModel
name: str
number: int
publisher_chat: Chat | None
symbol: UniqueGiftSymbol
class telebot_py.types.gifts.UniqueGiftBackdrop(name: str, colors: UniqueGiftBackdropColors, rarity_per_mille: int)

Bases: TelegramObject

The backdrop of a unique gift.

Variables:

  • name (str) – The name of the backdrop.

  • colors (telebot_py.types.gifts.UniqueGiftBackdropColors) – The colors of the backdrop.

  • rarity_per_mille (int) – The number of unique gifts that receive this backdrop for every 1000 gifts upgraded.

Telegram API: https://core.telegram.org/bots/api#uniquegiftbackdrop

colors: UniqueGiftBackdropColors
name: str
rarity_per_mille: int
class telebot_py.types.gifts.UniqueGiftBackdropColors(center_color: int, edge_color: int, symbol_color: int, text_color: int)

Bases: TelegramObject

Colors of a unique gift backdrop.

Variables:

  • center_color (int) – The color in the center of the backdrop in RGB format.

  • edge_color (int) – The color on the edges of the backdrop in RGB format.

  • symbol_color (int) – The color to be applied to the symbol in RGB format.

  • text_color (int) – The color for the text on the backdrop in RGB format.

Telegram API: https://core.telegram.org/bots/api#uniquegiftbackdropcolors

center_color: int
edge_color: int
symbol_color: int
text_color: int
class telebot_py.types.gifts.UniqueGiftColors(model_custom_emoji_id: str, symbol_custom_emoji_id: str, light_theme_main_color: int, light_theme_other_colors: list[int], dark_theme_main_color: int, dark_theme_other_colors: list[int])

Bases: TelegramObject

Colors representing a unique gift in the interface.

Variables:

  • model_custom_emoji_id (str) – Custom emoji identifier of the unique gift’s model.

  • symbol_custom_emoji_id (str) – Custom emoji identifier of the unique gift’s symbol.

  • light_theme_main_color (int) – Main color used in light themes, in RGB format.

  • light_theme_other_colors (list[int]) – List of 1-3 additional colors used in light themes, in RGB format.

  • dark_theme_main_color (int) – Main color used in dark themes, in RGB format.

  • dark_theme_other_colors (list[int]) – List of 1-3 additional colors used in dark themes, in RGB format.

Telegram API: https://core.telegram.org/bots/api#uniquegiftcolors

dark_theme_main_color: int
dark_theme_other_colors: list[int]
light_theme_main_color: int
light_theme_other_colors: list[int]
model_custom_emoji_id: str
symbol_custom_emoji_id: str
class telebot_py.types.gifts.UniqueGiftInfo(gift: UniqueGift, origin: str, text: str | None = None, entities: list[MessageEntity] | None = None, is_private: bool | None = None, last_resale_currency: str | None = None, last_resale_amount: int | None = None, owned_gift_id: str | None = None, transfer_star_count: int | None = None, next_transfer_date: int | None = None)

Bases: TelegramObject

Information about a unique gift attached to an owned gift.

Variables:

  • gift (telebot_py.types.gifts.UniqueGift) – Information about the gift.

  • origin (str) – Origin of the gift, one of upgrade, transfer, resale, gifted_upgrade or offer.

  • text (str | None) – Text of the message that was added to the gift.

  • entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the text.

  • is_private (bool | None) – True, if the sender and gift text are shown only to the gift receiver.

  • last_resale_currency (str | None) – Currency in which the payment for the gift was done, XTR or TON.

  • last_resale_amount (int | None) – Price paid for the gift in either Telegram Stars or nanograms.

  • owned_gift_id (str | None) – Unique identifier of the received gift for the bot; only present if the bot has a relationship with the gift.

  • transfer_star_count (int | None) – Number of Telegram Stars that must be paid to transfer the gift; omitted if the bot cannot transfer the gift.

  • next_transfer_date (int | None) – Point in time (Unix timestamp) when the gift can be transferred.

Telegram API: https://core.telegram.org/bots/api#uniquegiftinfo

entities: list[MessageEntity] | None
gift: UniqueGift
is_private: bool | None
last_resale_amount: int | None
last_resale_currency: str | None
next_transfer_date: int | None
origin: str
owned_gift_id: str | None
text: str | None
transfer_star_count: int | None
class telebot_py.types.gifts.UniqueGiftModel(name: str, sticker: Sticker, rarity_per_mille: int, rarity: str | None = None)

Bases: TelegramObject

The model of a unique gift.

Variables:

  • name (str) – The name of the model.

  • sticker (telebot_py.types.stickers.Sticker) – The sticker that represents the unique gift.

  • rarity_per_mille (int) – The number of unique gifts that receive this model for every 1000 gifts upgraded.

  • rarity (str | None) – Rarity of the model if it is a crafted model, one of uncommon, rare, epic or legendary.

Telegram API: https://core.telegram.org/bots/api#uniquegiftmodel

name: str
rarity: str | None
rarity_per_mille: int
sticker: Sticker
class telebot_py.types.gifts.UniqueGiftSymbol(name: str, sticker: Sticker, rarity_per_mille: int)

Bases: TelegramObject

The symbol displayed on a unique gift backdrop.

Variables:

  • name (str) – The name of the symbol.

  • sticker (telebot_py.types.stickers.Sticker) – The sticker that represents the unique gift.

  • rarity_per_mille (int) – The number of unique gifts that receive this model for every 1000 gifts upgraded.

Telegram API: https://core.telegram.org/bots/api#uniquegiftsymbol

name: str
rarity_per_mille: int
sticker: Sticker

telebot_py.types.keyboards

Telegram keyboard and reply markup types.

class telebot_py.types.keyboards.CopyTextButton(text: str)

Bases: TelegramObject

An inline keyboard button copying specified text to the clipboard.

Variables:

text (str) – The text to be copied to the clipboard; 1-256 characters.

Telegram API: https://core.telegram.org/bots/api#copytextbutton

text: str
class telebot_py.types.keyboards.DisabledButton

Bases: TelegramObject

An empty object marking an inline keyboard button as disabled.

Telegram API: https://core.telegram.org/bots/api#disabledbutton

class telebot_py.types.keyboards.ForceReply(force_reply: bool = True, input_field_placeholder: str | None = None, selective: bool | None = None)

Bases: TelegramObject

Shows reply interface to the user, as if they tapped ‘Reply’.

Variables:

  • force_reply (bool) – Shows the reply interface; always True on the wire.

  • input_field_placeholder (str | None) – Placeholder shown in the input field when the reply is active; 1-64 characters.

  • selective (bool | None) – Whether to force reply from specific users only.

Telegram API: https://core.telegram.org/bots/api#forcereply

force_reply: bool
input_field_placeholder: str | None
selective: bool | None
class telebot_py.types.keyboards.InlineKeyboardButton(text: str, icon_custom_emoji_id: str | None = None, style: str | None = None, url: str | None = None, callback_data: str | None = None, web_app: WebAppInfo | None = None, login_url: LoginUrl | None = None, switch_inline_query: str | None = None, switch_inline_query_current_chat: str | None = None, switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat | None = None, copy_text: CopyTextButton | None = None, callback_game: CallbackGame | None = None, pay: bool | None = None, disabled: DisabledButton | None = None)

Bases: TelegramObject

One button of an inline keyboard.

Variables:

  • text (str) – Label text on the button.

  • icon_custom_emoji_id (str | None) – Unique identifier of the custom emoji shown before the text of the button.

  • style (str | None) – Style of the button (‘danger’, ‘success’, ‘primary’).

  • url (str | None) – HTTP or tg:// URL opened when the button is pressed.

  • callback_data (str | None) – Data sent in a callback query when pressed (1-64 bytes).

  • web_app (telebot_py.types.keyboards.WebAppInfo | None) – Description of the Web App launched when pressed.

  • login_url (telebot_py.types.keyboards.LoginUrl | None) – An HTTPS URL used to automatically authorize the user.

  • switch_inline_query (str | None) – If set, prompts chat selection and inserts the bot’s username and this inline query.

  • switch_inline_query_current_chat (str | None) – If set, inserts the bot’s username and this inline query in the current chat’s input field.

  • switch_inline_query_chosen_chat (telebot_py.types.keyboards.SwitchInlineQueryChosenChat | None) – If set, prompts chat selection of the specified types.

  • copy_text (telebot_py.types.keyboards.CopyTextButton | None) – Description of the button copying text to the clipboard.

  • callback_game (telebot_py.types.games.CallbackGame | None) – Description of the game launched when pressed.

  • pay (bool | None) – Whether to send a Pay button.

  • disabled (telebot_py.types.keyboards.DisabledButton | None) – If set, the button is disabled and does nothing (Bot API 10.3+).

Telegram API: https://core.telegram.org/bots/api#inlinekeyboardbutton

callback_data: str | None
callback_game: CallbackGame | None
copy_text: CopyTextButton | None
disabled: DisabledButton | None
icon_custom_emoji_id: str | None
login_url: LoginUrl | None
pay: bool | None
style: str | None
switch_inline_query: str | None
switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat | None
switch_inline_query_current_chat: str | None
text: str
url: str | None
web_app: WebAppInfo | None
class telebot_py.types.keyboards.InlineKeyboardMarkup(inline_keyboard: list[list[InlineKeyboardButton]], force_reply: bool | None = None)

Bases: TelegramObject

An inline keyboard appearing right next to the message it belongs to.

Variables:

  • inline_keyboard (list[list[telebot_py.types.keyboards.InlineKeyboardButton]]) – Array of button rows, each an array of InlineKeyboardButton objects.

  • force_reply (bool | None) – Whether the reply interface must be shown to the user (Bot API 10.3+).

Telegram API: https://core.telegram.org/bots/api#inlinekeyboardmarkup

force_reply: bool | None
inline_keyboard: list[list[InlineKeyboardButton]]
class telebot_py.types.keyboards.KeyboardButton(text: str, icon_custom_emoji_id: str | None = None, style: str | None = None, request_users: KeyboardButtonRequestUsers | None = None, request_chat: KeyboardButtonRequestChat | None = None, request_managed_bot: KeyboardButtonRequestManagedBot | None = None, request_contact: bool | None = None, request_location: bool | None = None, request_poll: KeyboardButtonPollType | None = None, web_app: WebAppInfo | None = None)

Bases: TelegramObject

One button of the reply keyboard.

Variables:

  • text (str) – Text of the button; sent as a message when pressed if only the text, icon_custom_emoji_id and style fields are used.

  • icon_custom_emoji_id (str | None) – Unique identifier of the custom emoji shown before the text of the button.

  • style (str | None) – Style of the button (‘danger’, ‘success’, ‘primary’).

  • request_users (telebot_py.types.keyboards.KeyboardButtonRequestUsers | None) – If specified, opens a list of suitable users.

  • request_chat (telebot_py.types.keyboards.KeyboardButtonRequestChat | None) – If specified, opens a list of suitable chats.

  • request_managed_bot (telebot_py.types.keyboards.KeyboardButtonRequestManagedBot | None) – If specified, asks the user to create and share a bot managed by this bot.

  • request_contact (bool | None) – If True, the user’s phone number will be sent as a contact when pressed. Available in private chats only.

  • request_location (bool | None) – If True, the user’s current location will be sent when pressed. Available in private chats only.

  • request_poll (telebot_py.types.keyboards.KeyboardButtonPollType | None) – If specified, the user is asked to create a poll. Available in private chats only.

  • web_app (telebot_py.types.keyboards.WebAppInfo | None) – If specified, the described Web App launches when pressed.

Telegram API: https://core.telegram.org/bots/api#keyboardbutton

icon_custom_emoji_id: str | None
request_chat: KeyboardButtonRequestChat | None
request_contact: bool | None
request_location: bool | None
request_managed_bot: KeyboardButtonRequestManagedBot | None
request_poll: KeyboardButtonPollType | None
request_users: KeyboardButtonRequestUsers | None
style: str | None
text: str
web_app: WebAppInfo | None
class telebot_py.types.keyboards.KeyboardButtonPollType(type: str | None = None)

Bases: TelegramObject

Type of poll that can be created with a keyboard button.

Variables:

type (str | None) – If ‘quiz’, the user can only create a poll in quiz mode.

Telegram API: https://core.telegram.org/bots/api#keyboardbuttonpolltype

type: str | None
class telebot_py.types.keyboards.KeyboardButtonRequestChat(request_id: int, chat_is_channel: bool, chat_is_forum: bool | None = None, chat_has_username: bool | None = None, chat_is_created: bool | None = None, user_administrator_rights: object | None = None, bot_administrator_rights: object | None = None, bot_is_member: bool | None = None, request_title: bool | None = None, request_username: bool | None = None, request_photo: bool | None = None)

Bases: TelegramObject

Defines the criteria used to request a suitable chat.

Variables:

  • request_id (int) – Signed 32-bit identifier of the request, received back in the ChatShared object.

  • chat_is_channel (bool) – True to request a channel chat, False for a group or supergroup chat.

  • chat_is_forum (bool | None) – True to request a forum supergroup.

  • chat_has_username (bool | None) – True to request a chat with a username.

  • chat_is_created (bool | None) – True to request a chat owned by the user.

  • user_administrator_rights (object | None) – JSON-serialized required administrator rights of the user in the chat (kept raw per node typing).

  • bot_administrator_rights (object | None) – JSON-serialized required administrator rights of the bot in the chat (kept raw per node typing).

  • bot_is_member (bool | None) – True to request a chat with the bot as a member.

  • request_title (bool | None) – Whether to request the chat’s title.

  • request_username (bool | None) – Whether to request the chat’s username.

  • request_photo (bool | None) – Whether to request the chat’s photo.

Telegram API: https://core.telegram.org/bots/api#keyboardbuttonrequestchat

bot_administrator_rights: object | None
bot_is_member: bool | None
chat_has_username: bool | None
chat_is_channel: bool
chat_is_created: bool | None
chat_is_forum: bool | None
request_id: int
request_photo: bool | None
request_title: bool | None
request_username: bool | None
user_administrator_rights: object | None
class telebot_py.types.keyboards.KeyboardButtonRequestManagedBot(request_id: int, suggested_name: str | None = None, suggested_username: str | None = None)

Bases: TelegramObject

Defines criteria used to ask a user to create a bot managed by this bot.

Variables:

  • request_id (int) – Signed 32-bit identifier of the request; must be unique within the message.

  • suggested_name (str | None) – Suggested name for the bot.

  • suggested_username (str | None) – Suggested username for the bot.

Telegram API: https://core.telegram.org/bots/api#keyboardbuttonrequestmanagedbot

request_id: int
suggested_name: str | None
suggested_username: str | None
class telebot_py.types.keyboards.KeyboardButtonRequestUsers(request_id: int, user_is_bot: bool | None = None, user_is_premium: bool | None = None, max_quantity: int | None = None, request_name: bool | None = None, request_username: bool | None = None, request_photo: bool | None = None)

Bases: TelegramObject

Defines the criteria used to request suitable users.

Variables:

  • request_id (int) – Signed 32-bit identifier of the request, received back in the UsersShared object.

  • user_is_bot (bool | None) – Pass True to request bots, False for regular users.

  • user_is_premium (bool | None) – Pass True to request premium users, False otherwise.

  • max_quantity (int | None) – Maximum number of users to be selected; 1-10.

  • request_name (bool | None) – Whether to request the users’ first and last name.

  • request_username (bool | None) – Whether to request the users’ username.

  • request_photo (bool | None) – Whether to request the users’ photo.

Telegram API: https://core.telegram.org/bots/api#keyboardbuttonrequestusers

max_quantity: int | None
request_id: int
request_name: bool | None
request_photo: bool | None
request_username: bool | None
user_is_bot: bool | None
user_is_premium: bool | None
class telebot_py.types.keyboards.LoginUrl(url: str, forward_text: str | None = None, bot_username: str | None = None, request_write_access: bool | None = None)

Bases: TelegramObject

Parameter of the inline keyboard button used to authorize a user.

Variables:

  • url (str) – An HTTPS URL used to automatically authorize the user.

  • forward_text (str | None) – New text of the button in forwarded messages.

  • bot_username (str | None) – Username of a bot which will be used for authorization.

  • request_write_access (bool | None) – Whether to request permission for the bot to send messages to the user.

Telegram API: https://core.telegram.org/bots/api#loginurl

bot_username: str | None
forward_text: str | None
request_write_access: bool | None
url: str
class telebot_py.types.keyboards.PreparedKeyboardButton(id: str)

Bases: TelegramObject

A keyboard button prepared for use by a user of a Mini App.

Variables:

id (str) – Unique identifier of the keyboard button.

Telegram API: https://core.telegram.org/bots/api#preparedkeyboardbutton

id: str
class telebot_py.types.keyboards.ReplyKeyboardMarkup(keyboard: list[list[KeyboardButton]], is_persistent: bool | None = None, resize_keyboard: bool | None = None, one_time_keyboard: bool | None = None, input_field_placeholder: str | None = None, selective: bool | None = None, force_reply: bool | None = None)

Bases: TelegramObject

A custom keyboard with reply options.

Variables:

  • keyboard (list[list[telebot_py.types.keyboards.KeyboardButton]]) – Array of button rows, each an array of KeyboardButton objects.

  • is_persistent (bool | None) – Whether to always show the keyboard when the regular keyboard is hidden.

  • resize_keyboard (bool | None) – Whether to resize the keyboard vertically for optimal fit.

  • one_time_keyboard (bool | None) – Whether to hide the keyboard as soon as it has been used.

  • input_field_placeholder (str | None) – Placeholder shown in the input field when the keyboard is active; 1-64 characters.

  • selective (bool | None) – Whether to show the keyboard to specific users only.

  • force_reply (bool | None) – Whether the reply interface must be shown to the user (Bot API 10.3+).

Telegram API: https://core.telegram.org/bots/api#replykeyboardmarkup

force_reply: bool | None
input_field_placeholder: str | None
is_persistent: bool | None
keyboard: list[list[KeyboardButton]]
one_time_keyboard: bool | None
resize_keyboard: bool | None
selective: bool | None
class telebot_py.types.keyboards.ReplyKeyboardRemove(remove_keyboard: bool = True, selective: bool | None = None)

Bases: TelegramObject

Requests clients to remove the custom keyboard.

Variables:

  • remove_keyboard (bool) – Requests clients to remove the custom keyboard; always True on the wire.

  • selective (bool | None) – Whether to remove the keyboard for specific users only.

Telegram API: https://core.telegram.org/bots/api#replykeyboardremove

remove_keyboard: bool
selective: bool | None
class telebot_py.types.keyboards.SwitchInlineQueryChosenChat(query: str | None = None, allow_user_chats: bool | None = None, allow_bot_chats: bool | None = None, allow_group_chats: bool | None = None, allow_channel_chats: bool | None = None)

Bases: TelegramObject

An inline button switching the user to inline mode in a chosen chat.

Variables:

  • query (str | None) – The default inline query inserted in the input field.

  • allow_user_chats (bool | None) – Whether private chats with users can be chosen.

  • allow_bot_chats (bool | None) – Whether private chats with bots can be chosen.

  • allow_group_chats (bool | None) – Whether group and supergroup chats can be chosen.

  • allow_channel_chats (bool | None) – Whether channel chats can be chosen.

Telegram API: https://core.telegram.org/bots/api#switchinlinequerychosenchat

allow_bot_chats: bool | None
allow_channel_chats: bool | None
allow_group_chats: bool | None
allow_user_chats: bool | None
query: str | None
class telebot_py.types.keyboards.WebAppInfo(url: str)

Bases: TelegramObject

Describes a Web App that can be launched from a button.

Variables:

url (str) – An HTTPS URL of a Web App to be opened.

Telegram API: https://core.telegram.org/bots/api#webappinfo

url: str

telebot_py.types.media

Telegram media file types (photos, audio, video, documents).

class telebot_py.types.media.Animation(file_id: str, file_unique_id: str, width: int, height: int, duration: int, thumbnail: PhotoSize | None = None, file_name: str | None = None, mime_type: str | None = None, file_size: int | None = None)

Bases: TelegramObject

An animation file (GIF or H.264/MPEG-4 AVC video without sound).

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • width (int) – Video width as defined by sender.

  • height (int) – Video height as defined by sender.

  • duration (int) – Duration of the video in seconds as defined by sender.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Animation thumbnail.

  • file_name (str | None) – Original animation filename as defined by sender.

  • mime_type (str | None) – MIME type of the file as defined by sender.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#animation

duration: int
file_id: str
file_name: str | None
file_size: int | None
file_unique_id: str
height: int
mime_type: str | None
thumbnail: PhotoSize | None
width: int
class telebot_py.types.media.Audio(file_id: str, file_unique_id: str, duration: int, performer: str | None = None, title: str | None = None, file_name: str | None = None, mime_type: str | None = None, file_size: int | None = None, thumbnail: PhotoSize | None = None)

Bases: TelegramObject

An audio file to be treated as music by the Telegram clients.

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • duration (int) – Duration of the audio in seconds as defined by sender.

  • performer (str | None) – Performer of the audio as defined by sender or tags.

  • title (str | None) – Title of the audio as defined by sender or tags.

  • file_name (str | None) – Original filename as defined by sender.

  • mime_type (str | None) – MIME type of the file as defined by sender.

  • file_size (int | None) – File size in bytes, when known.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Thumbnail of the album cover the music file belongs to.

Telegram API: https://core.telegram.org/bots/api#audio

duration: int
file_id: str
file_name: str | None
file_size: int | None
file_unique_id: str
mime_type: str | None
performer: str | None
thumbnail: PhotoSize | None
title: str | None
class telebot_py.types.media.Document(file_id: str, file_unique_id: str, thumbnail: PhotoSize | None = None, file_name: str | None = None, mime_type: str | None = None, file_size: int | None = None)

Bases: TelegramObject

A general file (as opposed to photos, audio or video files).

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Document thumbnail as defined by sender.

  • file_name (str | None) – Original filename as defined by sender.

  • mime_type (str | None) – MIME type of the file as defined by sender.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#document

file_id: str
file_name: str | None
file_size: int | None
file_unique_id: str
mime_type: str | None
thumbnail: PhotoSize | None
class telebot_py.types.media.LivePhoto(file_id: str, file_unique_id: str, width: int, height: int, duration: int, photo: list[PhotoSize] | None = None, mime_type: str | None = None, file_size: int | None = None)

Bases: TelegramObject

A live photo: a still photo paired with the video it animates into.

Variables:

  • file_id (str) – Identifier for the video file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of the video file.

  • width (int) – Video width as defined by sender.

  • height (int) – Video height as defined by sender.

  • duration (int) – Duration of the video in seconds as defined by sender.

  • photo (list[telebot_py.types.media.PhotoSize] | None) – Available sizes of the corresponding static photo.

  • mime_type (str | None) – MIME type of the video file as defined by sender.

  • file_size (int | None) – File size of the video in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#livephoto

duration: int
file_id: str
file_size: int | None
file_unique_id: str
height: int
mime_type: str | None
photo: list[PhotoSize] | None
width: int
class telebot_py.types.media.PhotoSize(file_id: str, file_unique_id: str, width: int, height: int, file_size: int | None = None)

Bases: TelegramObject

One size of a photo or a file / sticker thumbnail.

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • width (int) – Photo width.

  • height (int) – Photo height.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#photosize

file_id: str
file_size: int | None
file_unique_id: str
height: int
width: int
class telebot_py.types.media.Video(file_id: str, file_unique_id: str, width: int, height: int, duration: int, thumbnail: PhotoSize | None = None, cover: list[PhotoSize] | None = None, start_timestamp: int | None = None, qualities: list[VideoQuality] | None = None, file_name: str | None = None, mime_type: str | None = None, file_size: int | None = None)

Bases: TelegramObject

A video file.

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • width (int) – Video width as defined by sender.

  • height (int) – Video height as defined by sender.

  • duration (int) – Duration of the video in seconds as defined by sender.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Video thumbnail.

  • cover (list[telebot_py.types.media.PhotoSize] | None) – Available sizes of the cover of the video.

  • start_timestamp (int | None) – Timestamp in seconds from which the video plays in the message.

  • qualities (list[telebot_py.types.media.VideoQuality] | None) – List of available qualities of the video.

  • file_name (str | None) – Original filename as defined by sender.

  • mime_type (str | None) – MIME type of the file as defined by sender.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#video

cover: list[PhotoSize] | None
duration: int
file_id: str
file_name: str | None
file_size: int | None
file_unique_id: str
height: int
mime_type: str | None
qualities: list[VideoQuality] | None
start_timestamp: int | None
thumbnail: PhotoSize | None
width: int
class telebot_py.types.media.VideoNote(file_id: str, file_unique_id: str, length: int, duration: int, thumbnail: PhotoSize | None = None, file_size: int | None = None)

Bases: TelegramObject

A video message (round video).

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • length (int) – Video width and height (diameter) as defined by sender.

  • duration (int) – Duration of the video in seconds as defined by sender.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Video thumbnail.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#videonote

duration: int
file_id: str
file_size: int | None
file_unique_id: str
length: int
thumbnail: PhotoSize | None
class telebot_py.types.media.VideoQuality(file_id: str, file_unique_id: str, width: int, height: int, codec: str, file_size: int | None = None)

Bases: TelegramObject

A video file of one specific quality.

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • width (int) – Video width.

  • height (int) – Video height.

  • codec (str) – Codec used to encode the video, e.g. “h264”, “h265” or “av01”.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#videoquality

codec: str
file_id: str
file_size: int | None
file_unique_id: str
height: int
width: int
class telebot_py.types.media.Voice(file_id: str, file_unique_id: str, duration: int, mime_type: str | None = None, file_size: int | None = None)

Bases: TelegramObject

A voice note.

Variables:

  • file_id (str) – Identifier for this file, usable for downloading or reuse.

  • file_unique_id (str) – Unique, persistent identifier of this file.

  • duration (int) – Duration of the audio in seconds as defined by sender.

  • mime_type (str | None) – MIME type of the audio as defined by sender.

  • file_size (int | None) – File size in bytes, when known.

Telegram API: https://core.telegram.org/bots/api#voice

duration: int
file_id: str
file_size: int | None
file_unique_id: str
mime_type: str | None

telebot_py.types.message_extras

Auxiliary message types: forward origins, quotes, external replies.

class telebot_py.types.message_extras.EphemeralMessageParameters(receiver_user_id: int, callback_query_id: str | None = None, replace_callback_query_message: bool | None = None)

Bases: TelegramObject

Parameters for sending an ephemeral message to a specific user.

Accepted by the ephemeral_message_parameters argument of the Bot API send* methods, which take any to_dict object. The message is visible to the receiver only and disappears automatically after 1 hour by default.

Variables:

  • receiver_user_id (int) – Identifier of the user who will receive the message. It is not guaranteed that the user will receive the message, especially if they are offline.

  • callback_query_id (str | None) – Identifier of the callback query which triggered the message, if any.

  • replace_callback_query_message (bool | None) – Pass True if the ephemeral message must be shown in place of the original message. Must be False for callback queries from ephemeral messages.

Telegram API: https://core.telegram.org/bots/api#ephemeralmessageparameters

callback_query_id: str | None
receiver_user_id: int
replace_callback_query_message: bool | None
class telebot_py.types.message_extras.ExternalReplyInfo(origin: MessageOriginUser | MessageOriginHiddenUser | MessageOriginChat | MessageOriginChannel, chat: Chat | None = None, message_id: int | None = None, link_preview_options: LinkPreviewOptions | None = None, animation: Animation | None = None, audio: Audio | None = None, document: Document | None = None, live_photo: LivePhoto | None = None, paid_media: PaidMediaInfo | None = None, photo: list[PhotoSize] | None = None, sticker: Sticker | None = None, story: Story | None = None, video: Video | None = None, video_note: VideoNote | None = None, voice: Voice | None = None, has_media_spoiler: bool | None = None, checklist: Checklist | None = None, contact: Contact | None = None, dice: Dice | None = None, game: Game | None = None, giveaway: Giveaway | None = None, giveaway_winners: GiveawayWinners | None = None, invoice: Invoice | None = None, location: Location | None = None, poll: Poll | None = None, venue: Venue | None = None)

Bases: TelegramObject

Information about a message that is being replied to from another chat.

Variables:

Telegram API: https://core.telegram.org/bots/api#externalreplyinfo

animation: Animation | None
audio: Audio | None
chat: Chat | None
checklist: Checklist | None
contact: Contact | None
dice: Dice | None
document: Document | None
game: Game | None
giveaway: Giveaway | None
giveaway_winners: GiveawayWinners | None
has_media_spoiler: bool | None
invoice: Invoice | None
live_photo: LivePhoto | None
location: Location | None
message_id: int | None
origin: MessageOriginUser | MessageOriginHiddenUser | MessageOriginChat | MessageOriginChannel
paid_media: PaidMediaInfo | None
photo: list[PhotoSize] | None
poll: Poll | None
sticker: Sticker | None
story: Story | None
venue: Venue | None
video: Video | None
video_note: VideoNote | None
voice: Voice | None
class telebot_py.types.message_extras.MessageOriginChannel(type: str, date: int, chat: Chat, message_id: int, author_signature: str | None = None)

Bases: TelegramObject

The message was originally sent to a channel chat.

Variables:

  • type (str) – Type of the message origin, always ‘channel’.

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

  • chat (telebot_py.types.chat.Chat) – Channel chat to which the message was originally sent.

  • message_id (int) – Identifier of the original message in the channel.

  • author_signature (str | None) – Signature of the original post author, if present.

Telegram API: https://core.telegram.org/bots/api#messageoriginchannel

author_signature: str | None
chat: Chat
date: int
message_id: int
type: str
class telebot_py.types.message_extras.MessageOriginChat(type: str, date: int, sender_chat: Chat, author_signature: str | None = None)

Bases: TelegramObject

The message was originally sent on behalf of a chat.

Variables:

  • type (str) – Type of the message origin, always ‘chat’.

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

  • sender_chat (telebot_py.types.chat.Chat) – Chat that sent the message originally.

  • author_signature (str | None) – For messages originally sent by an anonymous chat administrator, the original message author signature.

Telegram API: https://core.telegram.org/bots/api#messageoriginchat

author_signature: str | None
date: int
sender_chat: Chat
type: str
class telebot_py.types.message_extras.MessageOriginHiddenUser(type: str, date: int, sender_user_name: str)

Bases: TelegramObject

The message was originally sent by an unknown user.

Variables:

  • type (str) – Type of the message origin, always ‘hidden_user’.

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

  • sender_user_name (str) – Name of the user that sent the message originally.

Telegram API: https://core.telegram.org/bots/api#messageoriginhiddenuser

date: int
sender_user_name: str
type: str
class telebot_py.types.message_extras.MessageOriginUser(type: str, date: int, sender_user: User)

Bases: TelegramObject

The message was originally sent by a known user.

Variables:

  • type (str) – Type of the message origin, always ‘user’.

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

  • sender_user (telebot_py.types.user.User) – User that sent the message originally.

Telegram API: https://core.telegram.org/bots/api#messageoriginuser

date: int
sender_user: User
type: str
class telebot_py.types.message_extras.PollAnswer(poll_id: str, option_ids: list[int], option_persistent_ids: list[str], voter_chat: Chat | None = None, user: User | None = None)

Bases: TelegramObject

A user changed their answer in a non-anonymous poll.

Variables:

  • poll_id (str) – Unique poll identifier.

  • option_ids (list[int]) – 0-based identifiers of chosen answer options; may be empty if the user retracted their vote.

  • option_persistent_ids (list[str]) – Persistent identifiers of chosen answer options; may be empty if the user retracted their vote.

  • voter_chat (telebot_py.types.chat.Chat | None) – The chat that changed the answer to the poll, if the voter is anonymous.

  • user (telebot_py.types.user.User | None) – The user who changed the answer to the poll, if not anonymous.

Telegram API: https://core.telegram.org/bots/api#pollanswer

option_ids: list[int]
option_persistent_ids: list[str]
poll_id: str
user: User | None
voter_chat: Chat | None
class telebot_py.types.message_extras.PreparedInlineMessage(id: str, expiration_date: int)

Bases: TelegramObject

A message prepared to be sent by a user of a Mini App.

Variables:

  • id (str) – Unique identifier of the prepared message.

  • expiration_date (int) – Expiration date of the prepared message, in Unix time. Expired prepared messages can no longer be used.

Telegram API: https://core.telegram.org/bots/api#preparedinlinemessage

expiration_date: int
id: str
class telebot_py.types.message_extras.ReplyParameters(chat_id: int | str | None = None, message_id: int | None = None, allow_sending_without_reply: bool | None = None, quote: str | None = None, quote_parse_mode: str | None = None, quote_entities: list[MessageEntity] | None = None, quote_position: int | None = None, checklist_task_id: int | None = None, poll_option_id: str | None = None, ephemeral_message_id: int | None = None)

Bases: TelegramObject

Describes a message reply to apply.

Every field is optional on the wire; unset fields are omitted by to_dict, so ReplyParameters(message_id=5) serializes to exactly {"message_id": 5}.

Variables:

  • chat_id (int | str | None) – Unique identifier of the chat the message to reply to belongs to; omit when the message to reply to is in the current chat.

  • message_id (int | None) – Identifier of the message that will be replied to in the current chat, or in chat_id if it is specified.

  • allow_sending_without_reply (bool | None) – Whether the message should be sent even if the specified replied-to message is not found.

  • quote (str | None) – Quoted part of the message to be replied to, 0-1024 characters after entities parsing.

  • quote_parse_mode (str | None) – Parse mode for the entities in the quote.

  • quote_entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the quote, which can be specified instead of quote_parse_mode.

  • quote_position (int | None) – Position of the quote in the original message in UTF-16 code units.

  • checklist_task_id (int | None) – Identifier of the specific checklist item that the message is replying to, relative to the first item in the checklist in the replied message.

  • poll_option_id (str | None) – Identifier of the specific answer option in the poll that the message is replying to.

  • ephemeral_message_id (int | None) – Identifier of the ephemeral message that will be replied to, with an expiration date of at least 1 hour from now and no more than 366 days from now. Ignored for messages having chat_id.

Telegram API: https://core.telegram.org/bots/api#replyparameters

allow_sending_without_reply: bool | None
chat_id: int | str | None
checklist_task_id: int | None
ephemeral_message_id: int | None
message_id: int | None
poll_option_id: str | None
quote: str | None
quote_entities: list[MessageEntity] | None
quote_parse_mode: str | None
quote_position: int | None
class telebot_py.types.message_extras.SentGuestMessage(inline_message_id: str | None = None)

Bases: TelegramObject

An inline message sent by a guest bot in reply to a guest query.

Variables:

inline_message_id (str | None) – Identifier of the sent inline message, available only if there is an inline message attached to the guest query.

Telegram API: https://core.telegram.org/bots/api#sentguestmessage

inline_message_id: str | None
class telebot_py.types.message_extras.SentWebAppMessage(inline_message_id: str | None = None)

Bases: TelegramObject

The result of an interaction with a Web App sent on behalf of a user.

Variables:

inline_message_id (str | None) – Identifier of the sent inline message, available only if there is an inline message attached to the Web App.

Telegram API: https://core.telegram.org/bots/api#sentwebappmessage

inline_message_id: str | None
class telebot_py.types.message_extras.Story(chat: Chat, id: int)

Bases: TelegramObject

A forwarded story.

Variables:

Telegram API: https://core.telegram.org/bots/api#story

chat: Chat
id: int
class telebot_py.types.message_extras.TextQuote(text: str, position: int, entities: list[MessageEntity] | None = None, is_manual: bool | None = None)

Bases: TelegramObject

The quoted part of a message that is replied to.

Variables:

  • text (str) – Text of the quoted part of a message that is replied to.

  • position (int) – Approximate quote position in the original message in UTF-16 code units.

  • entities (list[telebot_py.types.common.MessageEntity] | None) – Special entities that appear in the quote.

  • is_manual (bool | None) – Whether the quote was chosen manually by the sender.

Telegram API: https://core.telegram.org/bots/api#textquote

entities: list[MessageEntity] | None
is_manual: bool | None
position: int
text: str
class telebot_py.types.message_extras.WebAppData(data: str, button_text: str)

Bases: TelegramObject

Data sent from a Web App to the bot.

Variables:

  • data (str) – The data. Be aware that a bad client can send arbitrary data.

  • button_text (str) – Text of the web_app keyboard button from which the Web App was opened.

Telegram API: https://core.telegram.org/bots/api#webappdata

button_text: str
data: str

telebot_py.types.message

Telegram Message type with the full Bot API 10.3 field set.

class telebot_py.types.message.InaccessibleMessage(chat: Chat, message_id: int, date: int)

Bases: TelegramObject

A message that was deleted or is otherwise inaccessible to the bot.

The docs reach this shape through MaybeInaccessibleMessage fields such as Message.reply_to_message; date is always 0, which is how clients tell an inaccessible message from a regular one.

Variables:

  • chat (telebot_py.types.chat.Chat) – Chat the message belonged to.

  • message_id (int) – Unique message identifier inside the chat.

  • date (int) – Always 0. The field can be used to differentiate regular and inaccessible messages.

Telegram API: https://core.telegram.org/bots/api#inaccessiblemessage

chat: Chat
date: int
message_id: int
class telebot_py.types.message.Message(message_id: int, date: int, chat: Chat, message_thread_id: int | None = None, direct_messages_topic: DirectMessagesTopic | None = None, from_user: User | None = None, sender_chat: Chat | None = None, sender_boost_count: int | None = None, sender_business_bot: User | None = None, sender_tag: str | None = None, receiver_user: User | None = None, ephemeral_message_id: int | None = None, guest_query_id: str | None = None, business_connection_id: str | None = None, forward_origin: MessageOriginUser | MessageOriginHiddenUser | MessageOriginChat | MessageOriginChannel | None = None, is_topic_message: bool | None = None, is_automatic_forward: bool | None = None, reply_to_message: Message | None = None, external_reply: ExternalReplyInfo | None = None, quote: TextQuote | None = None, reply_to_story: Story | None = None, reply_to_checklist_task_id: int | None = None, reply_to_poll_option_id: str | None = None, via_bot: User | None = None, guest_bot_caller_user: User | None = None, guest_bot_caller_chat: Chat | None = None, edit_date: int | None = None, has_protected_content: bool | None = None, is_from_offline: bool | None = None, is_paid_post: bool | None = None, media_group_id: str | None = None, author_signature: str | None = None, paid_star_count: int | None = None, text: str | None = None, entities: list[MessageEntity] | None = None, link_preview_options: LinkPreviewOptions | None = None, suggested_post_info: SuggestedPostInfo | None = None, effect_id: str | None = None, rich_message: RichMessage | None = None, animation: Animation | None = None, audio: Audio | None = None, document: Document | None = None, live_photo: LivePhoto | None = None, paid_media: PaidMediaInfo | None = None, photo: list[PhotoSize] | None = None, sticker: Sticker | None = None, story: Story | None = None, video: Video | None = None, video_note: VideoNote | None = None, voice: Voice | None = None, caption: str | None = None, caption_entities: list[MessageEntity] | None = None, show_caption_above_media: bool | None = None, has_media_spoiler: bool | None = None, checklist: Checklist | None = None, contact: Contact | None = None, dice: Dice | None = None, game: Game | None = None, poll: Poll | None = None, venue: Venue | None = None, location: Location | None = None, new_chat_members: list[User] | None = None, left_chat_member: User | None = None, chat_owner_left: ChatOwnerLeft | None = None, chat_owner_changed: ChatOwnerChanged | None = None, new_chat_title: str | None = None, new_chat_photo: list[PhotoSize] | None = None, delete_chat_photo: bool | None = None, group_chat_created: bool | None = None, supergroup_chat_created: bool | None = None, channel_chat_created: bool | None = None, message_auto_delete_timer_changed: MessageAutoDeleteTimerChanged | None = None, migrate_to_chat_id: int | None = None, migrate_from_chat_id: int | None = None, pinned_message: Message | None = None, invoice: Invoice | None = None, successful_payment: SuccessfulPayment | None = None, refunded_payment: RefundedPayment | None = None, users_shared: UsersShared | None = None, chat_shared: ChatShared | None = None, gift: GiftInfo | None = None, unique_gift: UniqueGiftInfo | None = None, gift_upgrade_sent: GiftInfo | None = None, connected_website: str | None = None, write_access_allowed: WriteAccessAllowed | None = None, passport_data: PassportData | None = None, proximity_alert_triggered: ProximityAlertTriggered | None = None, boost_added: ChatBoostAdded | None = None, chat_background_set: ChatBackground | None = None, checklist_tasks_done: ChecklistTasksDone | None = None, checklist_tasks_added: ChecklistTasksAdded | None = None, community_chat_added: CommunityChatAdded | None = None, community_chat_joined: CommunityChatJoined | None = None, community_chat_removed: CommunityChatRemoved | None = None, direct_message_price_changed: DirectMessagePriceChanged | None = None, forum_topic_created: ForumTopicCreated | None = None, forum_topic_edited: ForumTopicEdited | None = None, forum_topic_closed: ForumTopicClosed | None = None, forum_topic_reopened: ForumTopicReopened | None = None, general_forum_topic_hidden: GeneralForumTopicHidden | None = None, general_forum_topic_unhidden: GeneralForumTopicUnhidden | None = None, giveaway_created: GiveawayCreated | None = None, giveaway: Giveaway | None = None, giveaway_winners: GiveawayWinners | None = None, giveaway_completed: GiveawayCompleted | None = None, managed_bot_created: ManagedBotCreated | None = None, paid_message_price_changed: PaidMessagePriceChanged | None = None, poll_option_added: PollOptionAdded | None = None, poll_option_deleted: PollOptionDeleted | None = None, suggested_post_approved: SuggestedPostApproved | None = None, suggested_post_approval_failed: SuggestedPostApprovalFailed | None = None, suggested_post_declined: SuggestedPostDeclined | None = None, suggested_post_paid: SuggestedPostPaid | None = None, suggested_post_refunded: SuggestedPostRefunded | None = None, video_chat_scheduled: VideoChatScheduled | None = None, video_chat_started: VideoChatStarted | None = None, video_chat_ended: VideoChatEnded | None = None, video_chat_participants_invited: VideoChatParticipantsInvited | None = None, web_app_data: WebAppData | None = None, reply_markup: InlineKeyboardMarkup | None = None)

Bases: TelegramObject

A Telegram message, field-complete against Bot API 10.3.

Every field documented on Message is modelled with a real dataclass, so decoding an incoming update never drops data.

Variables:

  • message_id (int) – Unique message identifier inside this chat.

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

  • chat (telebot_py.types.chat.Chat) – Chat the message belongs to.

  • message_thread_id (int | None) – Unique identifier of the message thread the message belongs to; for supergroups only.

  • direct_messages_topic (telebot_py.types.message_community.DirectMessagesTopic | None) – Topic that contains message history shared with the sender of the message by direct messages.

  • from_user (telebot_py.types.user.User | None) – Sender of the message; empty for channel posts.

  • sender_chat (telebot_py.types.chat.Chat | None) – Sender of the message, sent on behalf of a chat.

  • sender_boost_count (int | None) – If the sender boosted the chat, the number of boosts added.

  • sender_business_bot (telebot_py.types.user.User | None) – The bot that actually sent the message on behalf of the business account.

  • sender_tag (str | None) – Sender tag of the message sender.

  • receiver_user (telebot_py.types.user.User | None) – Receiver user of an ephemeral message.

  • ephemeral_message_id (int | None) – Identifier of the ephemeral message.

  • guest_query_id (str | None) – Unique identifier of the guest query the message is a response to.

  • business_connection_id (str | None) – Unique identifier of the business connection from which the message was received.

  • forward_origin (telebot_py.types.message_extras.MessageOriginUser | telebot_py.types.message_extras.MessageOriginHiddenUser | telebot_py.types.message_extras.MessageOriginChat | telebot_py.types.message_extras.MessageOriginChannel | None) – Information about the original message for forwarded messages.

  • is_topic_message (bool | None) – Whether the message is sent to a forum topic.

  • is_automatic_forward (bool | None) – Whether the message is a channel post that was automatically forwarded to the connected discussion group.

  • reply_to_message (telebot_py.types.message.Message | None) – For replies in the same chat and message thread, the original message.

  • external_reply (telebot_py.types.message_extras.ExternalReplyInfo | None) – Information about the message that is being replied to, which may come from another chat or forum topic.

  • quote (telebot_py.types.message_extras.TextQuote | None) – For replies that quote part of the original message, the quoted part of the message.

  • reply_to_story (telebot_py.types.message_extras.Story | None) – For replies to a story, the original story.

  • reply_to_checklist_task_id (int | None) – Identifier of the specific checklist item that the message is replying to.

  • reply_to_poll_option_id (str | None) – Persistent identifier of the specific poll answer option that the message is replying to.

  • via_bot (telebot_py.types.user.User | None) – Bot through which the message was sent.

  • guest_bot_caller_user (telebot_py.types.user.User | None) – The user that called the bot in a chat where the bot isn’t a member.

  • guest_bot_caller_chat (telebot_py.types.chat.Chat | None) – The chat whose administrator called the bot.

  • edit_date (int | None) – Date the message was last edited in Unix time.

  • has_protected_content (bool | None) – Whether the message cannot be forwarded.

  • is_from_offline (bool | None) – Whether the message was sent by an implicit action, e.g. as an away or a greeting business message.

  • is_paid_post (bool | None) – Whether the message is a paid post and must be paid for before it is visible to the recipient.

  • media_group_id (str | None) – The unique identifier of the media message group this message belongs to.

  • author_signature (str | None) – Signature of the post author for messages in channels, or the custom title of an anonymous group administrator.

  • paid_star_count (int | None) – Number of Telegram Stars paid for this message.

  • text (str | None) – For text messages, the actual UTF-8 text of the message.

  • entities (list[telebot_py.types.common.MessageEntity] | None) – For text messages, special entities like substrings that appear in the text.

  • link_preview_options (telebot_py.types.common.LinkPreviewOptions | None) – Options used for link preview generation for the message, if it is a text message and includes entity links.

  • suggested_post_info (telebot_py.types.suggested_post_types.SuggestedPostInfo | None) – Information about the suggested post; for channel posts only.

  • effect_id (str | None) – Unique identifier of the message effect added to the message.

  • rich_message (telebot_py.types.rich_blocks.RichMessage | None) – Rich formatted message content.

  • animation (telebot_py.types.media.Animation | None) – Message is an animation, information about the animation.

  • audio (telebot_py.types.media.Audio | None) – Message is an audio file, information about the file.

  • document (telebot_py.types.media.Document | None) – Message is a general file, information about the file.

  • live_photo (telebot_py.types.media.LivePhoto | None) – Message is a live photo, information about it.

  • paid_media (telebot_py.types.paid_media.PaidMediaInfo | None) – Message contains paid media, information about it.

  • photo (list[telebot_py.types.media.PhotoSize] | None) – Message is a photo, available sizes of the photo.

  • sticker (telebot_py.types.stickers.Sticker | None) – Message is a sticker, information about it.

  • story (telebot_py.types.message_extras.Story | None) – Message is a forwarded story, information about the story.

  • video (telebot_py.types.media.Video | None) – Message is a video, information about the video.

  • video_note (telebot_py.types.media.VideoNote | None) – Message is a video note, information about the message.

  • voice (telebot_py.types.media.Voice | None) – Message is a voice message, information about the file.

  • caption (str | None) – Caption for the animation, audio, document, live photo, paid media, photo, video or voice.

  • caption_entities (list[telebot_py.types.common.MessageEntity] | None) – For messages with a caption, special entities that appear in the caption.

  • show_caption_above_media (bool | None) – Whether the caption must be shown above the message media.

  • has_media_spoiler (bool | None) – Whether the message media is covered by a spoiler animation.

  • checklist (telebot_py.types.checklists.Checklist | None) – Message is a checklist, information about it.

  • contact (telebot_py.types.common.Contact | None) – Message is a shared contact, information about the contact.

  • dice (telebot_py.types.common.Dice | None) – Message is a dice with random value.

  • game (telebot_py.types.games.Game | None) – Message is a game, information about it.

  • poll (telebot_py.types.poll_types.Poll | None) – Message is a native poll, information about the poll.

  • venue (telebot_py.types.common.Venue | None) – Message is a venue, information about the venue.

  • location (telebot_py.types.common.Location | None) – Message is a shared location, information about it.

  • new_chat_members (list[telebot_py.types.user.User] | None) – New members added to the group or supergroup.

  • left_chat_member (telebot_py.types.user.User | None) – A member removed from the group.

  • chat_owner_left (telebot_py.types.message_community.ChatOwnerLeft | None) – Service message: a user who owned the chat has left it or was demoted.

  • chat_owner_changed (telebot_py.types.message_community.ChatOwnerChanged | None) – Service message: the chat owner has changed.

  • new_chat_title (str | None) – A chat title was changed to this value.

  • new_chat_photo (list[telebot_py.types.media.PhotoSize] | None) – A chat photo was changed to this value.

  • delete_chat_photo (bool | None) – Service message: the chat photo was deleted.

  • group_chat_created (bool | None) – Service message: the group has been created.

  • supergroup_chat_created (bool | None) – Service message: the supergroup has been created.

  • channel_chat_created (bool | None) – Service message: the channel has been created.

  • message_auto_delete_timer_changed (telebot_py.types.message_service.MessageAutoDeleteTimerChanged | None) – Service message: auto-delete timer settings changed in the chat.

  • migrate_to_chat_id (int | None) – The group has been migrated to a supergroup with the specified identifier.

  • migrate_from_chat_id (int | None) – The supergroup has been migrated from a group with the specified identifier.

  • pinned_message (telebot_py.types.message.Message | None) – Specified message was pinned.

  • invoice (telebot_py.types.payments.Invoice | None) – Message is an invoice for a payment.

  • successful_payment (telebot_py.types.payments.SuccessfulPayment | None) – Message is a service message about a successful payment.

  • refunded_payment (telebot_py.types.payments.RefundedPayment | None) – Service message: a payment was refunded.

  • users_shared (telebot_py.types.message_service.UsersShared | None) – Service message: users were shared with the bot.

  • chat_shared (telebot_py.types.message_service.ChatShared | None) – Service message: a chat was shared with the bot.

  • gift (telebot_py.types.gifts.GiftInfo | None) – The message describes a gift received by a user or a chat.

  • unique_gift (telebot_py.types.gifts.UniqueGiftInfo | None) – The message describes a unique gift received by a user or a chat.

  • gift_upgrade_sent (telebot_py.types.gifts.GiftInfo | None) – Service message: a gift was upgraded by a user.

  • connected_website (str | None) – The domain name of the website on which the user has logged in.

  • write_access_allowed (telebot_py.types.message_service.WriteAccessAllowed | None) – Service message: the user allowed the bot to write messages after adding it to the attachment menu, launching a Web App or joining a Telegram Mini App.

  • passport_data (telebot_py.types.passport.PassportData | None) – Telegram Passport data provided by the user.

  • proximity_alert_triggered (telebot_py.types.message_service.ProximityAlertTriggered | None) – Service message: proximity alert triggered while sharing Live Location.

  • boost_added (telebot_py.types.business.ChatBoostAdded | None) – Service message: user boosted the chat.

  • chat_background_set (telebot_py.types.background.ChatBackground | None) – Service message: the chat background was set.

  • checklist_tasks_done (telebot_py.types.message_community.ChecklistTasksDone | None) – Service message: some tasks in a checklist were marked as done or not done.

  • checklist_tasks_added (telebot_py.types.message_community.ChecklistTasksAdded | None) – Service message: tasks were added to a checklist.

  • community_chat_added (telebot_py.types.message_community.CommunityChatAdded | None) – Service message: a community chat was added to the business chat.

  • community_chat_joined (telebot_py.types.chat_members.CommunityChatJoined | None) – Service message: a user joined the chat from a community.

  • community_chat_removed (telebot_py.types.message_community.CommunityChatRemoved | None) – Service message: a community chat was removed from the business chat.

  • direct_message_price_changed (telebot_py.types.message_community.DirectMessagePriceChanged | None) – Service message: the price for direct messages in the chat was changed.

  • forum_topic_created (telebot_py.types.message_service.ForumTopicCreated | None) – Service message: forum topic created.

  • forum_topic_edited (telebot_py.types.message_service.ForumTopicEdited | None) – Service message: forum topic edited.

  • forum_topic_closed (telebot_py.types.message_service.ForumTopicClosed | None) – Service message: forum topic closed.

  • forum_topic_reopened (telebot_py.types.message_service.ForumTopicReopened | None) – Service message: forum topic reopened.

  • general_forum_topic_hidden (telebot_py.types.message_service.GeneralForumTopicHidden | None) – Service message: the ‘General’ forum topic hidden.

  • general_forum_topic_unhidden (telebot_py.types.message_service.GeneralForumTopicUnhidden | None) – Service message: the ‘General’ forum topic unhidden.

  • giveaway_created (telebot_py.types.giveaway_types.GiveawayCreated | None) – Service message: a scheduled giveaway was created.

  • giveaway (telebot_py.types.giveaway_types.Giveaway | None) – The message is a scheduled giveaway message.

  • giveaway_winners (telebot_py.types.giveaway_types.GiveawayWinners | None) – A giveaway with public winners was completed.

  • giveaway_completed (telebot_py.types.giveaway_types.GiveawayCompleted | None) – Service message: a giveaway without public winners was completed.

  • managed_bot_created (telebot_py.types.message_community.ManagedBotCreated | None) – Service message: the creation of a bot managed by the business account was initiated.

  • paid_message_price_changed (telebot_py.types.message_community.PaidMessagePriceChanged | None) – Service message: the price for paid messages in the chat was changed.

  • poll_option_added (telebot_py.types.message_community.PollOptionAdded | None) – Service message: an option was added to a poll.

  • poll_option_deleted (telebot_py.types.message_community.PollOptionDeleted | None) – Service message: an option was deleted from a poll.

  • suggested_post_approved (telebot_py.types.suggested_post_types.SuggestedPostApproved | None) – Service message: a suggested post was approved for publication.

  • suggested_post_approval_failed (telebot_py.types.suggested_post_types.SuggestedPostApprovalFailed | None) – Service message: approval of a suggested post has failed.

  • suggested_post_declined (telebot_py.types.suggested_post_types.SuggestedPostDeclined | None) – Service message: a suggested post was declined.

  • suggested_post_paid (telebot_py.types.suggested_post_types.SuggestedPostPaid | None) – Service message: payment for a suggested post was received.

  • suggested_post_refunded (telebot_py.types.suggested_post_types.SuggestedPostRefunded | None) – Service message: payment for a suggested post was refunded.

  • video_chat_scheduled (telebot_py.types.message_service.VideoChatScheduled | None) – Service message: video chat scheduled.

  • video_chat_started (telebot_py.types.message_service.VideoChatStarted | None) – Service message: video chat started.

  • video_chat_ended (telebot_py.types.message_service.VideoChatEnded | None) – Service message: video chat ended.

  • video_chat_participants_invited (telebot_py.types.message_service.VideoChatParticipantsInvited | None) – Service message: new participants invited to a video chat.

  • web_app_data (telebot_py.types.message_extras.WebAppData | None) – Service message: data sent by a Web App to the bot.

  • reply_markup (telebot_py.types.keyboards.InlineKeyboardMarkup | None) – Inline keyboard attached to the message.

Telegram API: https://core.telegram.org/bots/api#message

animation: Animation | None
audio: Audio | None
author_signature: str | None
boost_added: ChatBoostAdded | None
business_connection_id: str | None
caption: str | None
caption_entities: list[MessageEntity] | None
channel_chat_created: bool | None
chat: Chat
chat_background_set: ChatBackground | None
chat_owner_changed: ChatOwnerChanged | None
chat_owner_left: ChatOwnerLeft | None
chat_shared: ChatShared | None
checklist: Checklist | None
checklist_tasks_added: ChecklistTasksAdded | None
checklist_tasks_done: ChecklistTasksDone | None
community_chat_added: CommunityChatAdded | None
community_chat_joined: CommunityChatJoined | None
community_chat_removed: CommunityChatRemoved | None
connected_website: str | None
contact: Contact | None
date: int
delete_chat_photo: bool | None
dice: Dice | None
direct_message_price_changed: DirectMessagePriceChanged | None
direct_messages_topic: DirectMessagesTopic | None
document: Document | None
edit_date: int | None
effect_id: str | None
entities: list[MessageEntity] | None
ephemeral_message_id: int | None
external_reply: ExternalReplyInfo | None
forum_topic_closed: ForumTopicClosed | None
forum_topic_created: ForumTopicCreated | None
forum_topic_edited: ForumTopicEdited | None
forum_topic_reopened: ForumTopicReopened | None
forward_origin: MessageOriginUser | MessageOriginHiddenUser | MessageOriginChat | MessageOriginChannel | None
from_user: User | None
game: Game | None
general_forum_topic_hidden: GeneralForumTopicHidden | None
general_forum_topic_unhidden: GeneralForumTopicUnhidden | None
gift: GiftInfo | None
gift_upgrade_sent: GiftInfo | None
giveaway: Giveaway | None
giveaway_completed: GiveawayCompleted | None
giveaway_created: GiveawayCreated | None
giveaway_winners: GiveawayWinners | None
group_chat_created: bool | None
guest_bot_caller_chat: Chat | None
guest_bot_caller_user: User | None
guest_query_id: str | None
has_media_spoiler: bool | None
has_protected_content: bool | None
invoice: Invoice | None
is_automatic_forward: bool | None
is_from_offline: bool | None
is_paid_post: bool | None
is_topic_message: bool | None
left_chat_member: User | None
live_photo: LivePhoto | None
location: Location | None
managed_bot_created: ManagedBotCreated | None
media_group_id: str | None
message_auto_delete_timer_changed: MessageAutoDeleteTimerChanged | None
message_id: int
message_thread_id: int | None
migrate_from_chat_id: int | None
migrate_to_chat_id: int | None
new_chat_members: list[User] | None
new_chat_photo: list[PhotoSize] | None
new_chat_title: str | None
paid_media: PaidMediaInfo | None
paid_message_price_changed: PaidMessagePriceChanged | None
paid_star_count: int | None
passport_data: PassportData | None
photo: list[PhotoSize] | None
pinned_message: Message | None
poll: Poll | None
poll_option_added: PollOptionAdded | None
poll_option_deleted: PollOptionDeleted | None
proximity_alert_triggered: ProximityAlertTriggered | None
quote: TextQuote | None
receiver_user: User | None
refunded_payment: RefundedPayment | None
reply_markup: InlineKeyboardMarkup | None
reply_to_checklist_task_id: int | None
reply_to_message: Message | None
reply_to_poll_option_id: str | None
reply_to_story: Story | None
rich_message: RichMessage | None
sender_boost_count: int | None
sender_business_bot: User | None
sender_chat: Chat | None
sender_tag: str | None
show_caption_above_media: bool | None
sticker: Sticker | None
story: Story | None
successful_payment: SuccessfulPayment | None
suggested_post_approval_failed: SuggestedPostApprovalFailed | None
suggested_post_approved: SuggestedPostApproved | None
suggested_post_declined: SuggestedPostDeclined | None
suggested_post_info: SuggestedPostInfo | None
suggested_post_paid: SuggestedPostPaid | None
suggested_post_refunded: SuggestedPostRefunded | None
supergroup_chat_created: bool | None
text: str | None
unique_gift: UniqueGiftInfo | None
users_shared: UsersShared | None
venue: Venue | None
via_bot: User | None
video: Video | None
video_chat_ended: VideoChatEnded | None
video_chat_participants_invited: VideoChatParticipantsInvited | None
video_chat_scheduled: VideoChatScheduled | None
video_chat_started: VideoChatStarted | None
video_note: VideoNote | None
voice: Voice | None
web_app_data: WebAppData | None
write_access_allowed: WriteAccessAllowed | None

telebot_py.types.passport

Telegram Passport types: encrypted payloads and error reporting.

class telebot_py.types.passport.EncryptedCredentials(data: str, hash: str, secret: str)

Bases: TelegramObject

Credentials required to decrypt submitted Telegram Passport data.

Variables:

  • data (str) – Base64-encoded encrypted JSON-serialized data with unique user’s payload, data hashes and secrets required for EncryptedPassportElement decryption and authentication.

  • hash (str) – Base64-encoded data hash for authentication.

  • secret (str) – Base64-encoded secret, encrypted with the bot’s public RSA key, required for data decryption.

Telegram API: https://core.telegram.org/bots/api#encryptedcredentials

data: str
hash: str
secret: str
class telebot_py.types.passport.EncryptedPassportElement(type: str, hash: str, data: str | None = None, phone_number: str | None = None, email: str | None = None, files: list[PassportFile] | None = None, front_side: PassportFile | None = None, reverse_side: PassportFile | None = None, selfie: PassportFile | None = None, translation: list[PassportFile] | None = None)

Bases: TelegramObject

One encrypted element submitted through Telegram Passport.

Variables:

  • type (str) – Element type, one of personal_details, passport, driver_license, identity_card, internal_passport, address, utility_bill, bank_statement, rental_agreement, passport_registration, temporary_registration, phone_number or email.

  • hash (str) – Base64-encoded element hash, used for authentication on Telegram’s side.

  • data (str | None) – Base64-encoded encrypted element data, when the element is a data field rather than a file.

  • phone_number (str | None) – User’s verified phone number; present only for phone_number type elements.

  • email (str | None) – User’s verified email address; present only for email type elements.

  • files (list[telebot_py.types.passport.PassportFile] | None) – Files with documents provided by the user, when applicable.

  • front_side (telebot_py.types.passport.PassportFile | None) – File with the front side of the document, when applicable.

  • reverse_side (telebot_py.types.passport.PassportFile | None) – File with the reverse side of the document, when applicable.

  • selfie (telebot_py.types.passport.PassportFile | None) – File with the selfie of a user with a document presented by the user, when applicable.

  • translation (list[telebot_py.types.passport.PassportFile] | None) – Array of encrypted files with translated versions of the documents provided by the user, when applicable.

Telegram API: https://core.telegram.org/bots/api#encryptedpassportelement

data: str | None
email: str | None
files: list[PassportFile] | None
front_side: PassportFile | None
hash: str
phone_number: str | None
reverse_side: PassportFile | None
selfie: PassportFile | None
translation: list[PassportFile] | None
type: str
class telebot_py.types.passport.PassportData(data: list[EncryptedPassportElement], credentials: EncryptedCredentials)

Bases: TelegramObject

Telegram Passport data attached to a message by a user.

Variables:

Telegram API: https://core.telegram.org/bots/api#passportdata

credentials: EncryptedCredentials
data: list[EncryptedPassportElement]
class telebot_py.types.passport.PassportElementError(source: str, type: str, message: str)

Bases: TelegramObject

An error in one of the Telegram Passport elements a user provided.

Sent by telebot_py.bot.games.GamesMixin.set_passport_data_errors() to inform a user that the data they submitted could not be accepted.

This mirrors the node reference model, which carries only the keys shared by every error source. Variant-specific keys (field_name, file_hash, file_hashes, element_hash) are not modeled; pass a plain dict for those errors instead, since the method accepts both shapes.

Variables:

  • source (str) – Source of the error, one of data_field, front_side, reverse_side, selfie, file, files, translation_file, translation_files, or unspecified.

  • type (str) – Element type of the user’s Telegram Passport which has the issue, one of personal_details, passport, driver_license, identity_card, internal_passport, address, utility_bill, bank_statement, rental_agreement, passport_registration, temporary_registration.

  • message (str) – Human-readable error message.

Telegram API: https://core.telegram.org/bots/api#passportelementerror

message: str
source: str
type: str
class telebot_py.types.passport.PassportFile(file_id: str, file_unique_id: str, file_size: int, file_date: int)

Bases: TelegramObject

A file uploaded to Telegram Passport.

All files uploaded to Telegram Passport are currently encrypted by the same EncryptedCredentials that accompanies a PassportData payload.

Variables:

  • file_id (str) – Identifier for this file, which can be used to download or reuse it.

  • file_unique_id (str) – Unique identifier for this file.

  • file_size (int) – File size in bytes.

  • file_date (int) – Unix time when the file was uploaded to Telegram Passport.

Telegram API: https://core.telegram.org/bots/api#passportfile

file_date: int
file_id: str
file_size: int
file_unique_id: str

telebot_py.types.paid_media

Paid media types for star-purchased media messages.

Mirrors Telegram’s PaidMedia* and InputPaidMedia* classes for the Bot API field set the node sibling targets (10.3); the newer live-photo paid media variants are deliberately out of scope until node models them.

telebot_py.types.paid_media.InputPaidMedia = telebot_py.types.paid_media.InputPaidMediaPhoto | telebot_py.types.paid_media.InputPaidMediaVideo

A media item accepted by Bot.send_paid_media.

class telebot_py.types.paid_media.InputPaidMediaPhoto(type: str, media: str)

Bases: TelegramObject

A photo to send as paid media.

Variables:

  • type (str) – Type of the media, always ‘photo’.

  • media (str) – File to send: a file_id, an HTTP URL, or an attach://<file_attach_name> reference.

Telegram API: https://core.telegram.org/bots/api#inputpaidmediaphoto

media: str
type: str
class telebot_py.types.paid_media.InputPaidMediaVideo(type: str, media: str, thumbnail: str | None = None, cover: str | None = None, start_timestamp: int | None = None, width: int | None = None, height: int | None = None, duration: int | None = None, supports_streaming: bool | None = None)

Bases: TelegramObject

A video to send as paid media.

Variables:

  • type (str) – Type of the media, always ‘video’.

  • media (str) – File to send: a file_id, an HTTP URL, or an attach://<file_attach_name> reference.

  • thumbnail (str | None) – Thumbnail of the file sent.

  • cover (str | None) – Cover for the video in the message.

  • start_timestamp (int | None) – Start timestamp for the video in the message.

  • width (int | None) – Video width.

  • height (int | None) – Video height.

  • duration (int | None) – Video duration in seconds.

  • supports_streaming (bool | None) – Whether the uploaded video is suitable for streaming.

Telegram API: https://core.telegram.org/bots/api#inputpaidmediavideo

cover: str | None
duration: int | None
height: int | None
media: str
start_timestamp: int | None
supports_streaming: bool | None
thumbnail: str | None
type: str
width: int | None
telebot_py.types.paid_media.PaidMedia = telebot_py.types.paid_media.PaidMediaPreview | telebot_py.types.paid_media.PaidMediaPhoto | telebot_py.types.paid_media.PaidMediaVideo

A paid media attachment carried by a message.

class telebot_py.types.paid_media.PaidMediaInfo(star_count: int, paid_media: list[PaidMediaPreview | PaidMediaPhoto | PaidMediaVideo])

Bases: TelegramObject

The paid media added to a message.

Variables:

Telegram API: https://core.telegram.org/bots/api#paidmediainfo

paid_media: list[PaidMediaPreview | PaidMediaPhoto | PaidMediaVideo]
star_count: int
class telebot_py.types.paid_media.PaidMediaPhoto(type: str, photo: list[PhotoSize])

Bases: TelegramObject

Paid media that is a photo.

Variables:

Telegram API: https://core.telegram.org/bots/api#paidmediaphoto

photo: list[PhotoSize]
type: str
class telebot_py.types.paid_media.PaidMediaPreview(type: str, width: int | None = None, height: int | None = None, duration: int | None = None)

Bases: TelegramObject

Paid media that isn’t available before the payment.

Variables:

  • type (str) – Type of the paid media, always ‘preview’.

  • width (int | None) – Media width as defined by the sender.

  • height (int | None) – Media height as defined by the sender.

  • duration (int | None) – Duration of the media in seconds as defined by the sender.

Telegram API: https://core.telegram.org/bots/api#paidmediapreview

duration: int | None
height: int | None
type: str
width: int | None
class telebot_py.types.paid_media.PaidMediaVideo(type: str, video: Video)

Bases: TelegramObject

Paid media that is a video.

Variables:

Telegram API: https://core.telegram.org/bots/api#paidmediavideo

type: str
video: Video

telebot_py.types.payments

Telegram payment types used by updates and queries.

class telebot_py.types.payments.AffiliateInfo(commission_per_mille: int, amount: int, affiliate_user: User | None = None, affiliate_chat: Chat | None = None, nanostar_amount: int | None = None)

Bases: TelegramObject

The affiliate that received a commission via a transaction.

Reached through the affiliate_info field of the docs’ TransactionPartnerUser object.

Variables:

  • commission_per_mille (int) – The number of Telegram Stars received by the affiliate for each 1000 Telegram Stars received by the bot from referred users.

  • amount (int) – Integer amount of Telegram Stars received by the affiliate from the transaction, rounded to 0; can be negative for refunds.

  • affiliate_user (telebot_py.types.user.User | None) – The bot or the user that received an affiliate commission if it was received by a bot or a user.

  • affiliate_chat (telebot_py.types.chat.Chat | None) – The chat that received an affiliate commission if it was received by a chat.

  • nanostar_amount (int | None) – The number of 1/1000000000 shares of Telegram Stars received by the affiliate; from -999999999 to 999999999; can be negative for refunds.

Telegram API: https://core.telegram.org/bots/api#affiliateinfo

affiliate_chat: Chat | None
affiliate_user: User | None
amount: int
commission_per_mille: int
nanostar_amount: int | None
class telebot_py.types.payments.BotSubscriptionUpdated(user: User, invoice_payload: str, state: str)

Bases: TelegramObject

A user changed the state of a subscription to the bot’s payments.

Variables:

  • user (telebot_py.types.user.User) – User who subscribed for payments toward the bot.

  • invoice_payload (str) – Bot-specified invoice payload.

  • state (str) – New state of the subscription; ‘canceled’ if the user canceled the subscription, ‘active’ if the user re-enabled a previously canceled subscription.

Telegram API: https://core.telegram.org/bots/api#botsubscriptionupdated

invoice_payload: str
state: str
user: User
class telebot_py.types.payments.Invoice(title: str, description: str, start_parameter: str, currency: str, total_amount: int)

Bases: TelegramObject

Basic information about an invoice.

Variables:

  • title (str) – Product name.

  • description (str) – Product description.

  • start_parameter (str) – Unique deep-linking parameter that can be used to generate this invoice when used as a start parameter.

  • currency (str) – Three-letter ISO 4217 currency code, or XTR for payments in Telegram Stars.

  • total_amount (int) – Total price in the smallest units of the currency (e.g. cents for USD, or Telegram Stars for XTR).

Telegram API: https://core.telegram.org/bots/api#invoice

currency: str
description: str
start_parameter: str
title: str
total_amount: int
class telebot_py.types.payments.LabeledPrice(label: str, amount: int)

Bases: TelegramObject

A portion of a price.

Variables:

  • label (str) – Portion label.

  • amount (int) – Price of the product in the smallest units of the currency.

Telegram API: https://core.telegram.org/bots/api#labeledprice

amount: int
label: str
class telebot_py.types.payments.OrderInfo(name: str | None = None, phone_number: str | None = None, email: str | None = None, shipping_address: ShippingAddress | None = None)

Bases: TelegramObject

Information about an order provided by the user.

Variables:

  • name (str | None) – User name.

  • phone_number (str | None) – User’s phone number.

  • email (str | None) – User’s email.

  • shipping_address (telebot_py.types.payments.ShippingAddress | None) – User’s shipping address.

Telegram API: https://core.telegram.org/bots/api#orderinfo

email: str | None
name: str | None
phone_number: str | None
shipping_address: ShippingAddress | None
class telebot_py.types.payments.PaidMediaPurchased(from_user: User, paid_media_payload: str)

Bases: TelegramObject

A user purchased paid media with Telegram Stars.

Variables:

  • from_user (telebot_py.types.user.User) – User who purchased the media.

  • paid_media_payload (str) – Bot-specified paid media payload.

Telegram API: https://core.telegram.org/bots/api#paidmediapurchased

from_user: User
paid_media_payload: str
class telebot_py.types.payments.PreCheckoutQuery(id: str, from_user: User, currency: str, total_amount: int, invoice_payload: str, shipping_option_id: str | None = None, order_info: OrderInfo | None = None)

Bases: TelegramObject

An incoming pre-checkout query containing full checkout information.

Variables:

  • id (str) – Unique query identifier.

  • from_user (telebot_py.types.user.User) – User who sent the query.

  • currency (str) – Three-letter ISO 4217 currency code or ‘XTR’.

  • total_amount (int) – Total price in the smallest units of the currency.

  • invoice_payload (str) – Bot-specified invoice payload.

  • shipping_option_id (str | None) – Identifier of the shipping option chosen by the user, when applicable.

  • order_info (telebot_py.types.payments.OrderInfo | None) – Order info provided by the user, when applicable.

Telegram API: https://core.telegram.org/bots/api#precheckoutquery

currency: str
from_user: User
id: str
invoice_payload: str
order_info: OrderInfo | None
shipping_option_id: str | None
total_amount: int
class telebot_py.types.payments.RefundedPayment(currency: str, total_amount: int, invoice_payload: str, telegram_payment_charge_id: str, provider_payment_charge_id: str | None = None)

Bases: TelegramObject

A service message about a refunded payment.

Variables:

  • currency (str) – Three-letter ISO 4217 currency code, or XTR for payments in Telegram Stars.

  • total_amount (int) – Total refunded price in the smallest units of the currency.

  • invoice_payload (str) – Bot-specified invoice payload.

  • telegram_payment_charge_id (str) – Telegram payment identifier.

  • provider_payment_charge_id (str | None) – Provider payment identifier.

Telegram API: https://core.telegram.org/bots/api#refundedpayment

currency: str
invoice_payload: str
provider_payment_charge_id: str | None
telegram_payment_charge_id: str
total_amount: int
class telebot_py.types.payments.ShippingAddress(country_code: str, city: str, street_line1: str, post_code: str, state: str | None = None, street_line2: str | None = None)

Bases: TelegramObject

A shipping address provided by the user.

Variables:

  • country_code (str) – Two-letter ISO 3166-1 alpha-2 country code.

  • city (str) – City.

  • street_line1 (str) – First line for the address.

  • post_code (str) – Address post code.

  • state (str | None) – State, if applicable.

  • street_line2 (str | None) – Second line for the address.

Telegram API: https://core.telegram.org/bots/api#shippingaddress

city: str
country_code: str
post_code: str
state: str | None
street_line1: str
street_line2: str | None
class telebot_py.types.payments.ShippingOption(id: str, title: str, prices: list[LabeledPrice])

Bases: TelegramObject

One shipping option offered by the bot.

Variables:

Telegram API: https://core.telegram.org/bots/api#shippingoption

id: str
prices: list[LabeledPrice]
title: str
class telebot_py.types.payments.ShippingQuery(id: str, from_user: User, invoice_payload: str, shipping_address: ShippingAddress)

Bases: TelegramObject

An incoming shipping query (only for invoices with flexible prices).

Variables:

Telegram API: https://core.telegram.org/bots/api#shippingquery

from_user: User
id: str
invoice_payload: str
shipping_address: ShippingAddress
class telebot_py.types.payments.StarAmount(amount: int, nanostar_amount: int | None = None)

Bases: TelegramObject

An amount of Telegram Stars.

Returned by Bot.get_my_star_balance.

Variables:

  • amount (int) – The integer number of Telegram Stars.

  • nanostar_amount (int | None) – The number of 1/1000000000 shares of Telegram Stars.

Telegram API: https://core.telegram.org/bots/api#staramount

amount: int
nanostar_amount: int | None
class telebot_py.types.payments.StarTransaction(id: str, amount: int, date: int, nanostar_amount: int | None = None, source: Mapping[str, object] | None = None, receiver: Mapping[str, object] | None = None)

Bases: TelegramObject

A single Telegram Stars transaction.

Variables:

  • id (str) – Unique identifier of the transaction.

  • amount (int) – Number of Telegram Stars transferred.

  • nanostar_amount (int | None) – The number of 1/1000000000 shares of Telegram Stars transferred.

  • date (int) – Date the transaction took place, in Unix time.

  • source (Mapping[str, object] | None) – Source of the transaction; shape depends on the partner type.

  • receiver (Mapping[str, object] | None) – Receiver of the transaction; shape depends on the partner type.

Telegram API: https://core.telegram.org/bots/api#startransaction

amount: int
date: int
id: str
nanostar_amount: int | None
receiver: Mapping[str, object] | None
source: Mapping[str, object] | None
class telebot_py.types.payments.StarTransactions(transactions: list[StarTransaction])

Bases: TelegramObject

The list of Telegram Stars transactions of a bot.

Variables:

transactions (list[telebot_py.types.payments.StarTransaction]) – List of transactions.

Telegram API: https://core.telegram.org/bots/api#startransactions

transactions: list[StarTransaction]
class telebot_py.types.payments.SuccessfulPayment(currency: str, total_amount: int, invoice_payload: str, telegram_payment_charge_id: str, provider_payment_charge_id: str, shipping_option_id: str | None = None, order_info: OrderInfo | None = None, is_recurring: bool | None = None, is_first_recurring: bool | None = None, subscription_expiration_date: int | None = None)

Bases: TelegramObject

Service message describing a successful payment.

Variables:

  • currency (str) – Three-letter ISO 4217 currency code, or XTR for payments in Telegram Stars.

  • total_amount (int) – Total price in the smallest units of the currency.

  • invoice_payload (str) – Bot-specified invoice payload.

  • telegram_payment_charge_id (str) – Telegram payment identifier.

  • provider_payment_charge_id (str) – Provider payment identifier.

  • shipping_option_id (str | None) – Identifier of the shipping option chosen by the user, when applicable.

  • order_info (telebot_py.types.payments.OrderInfo | None) – Order info provided by the user, when applicable.

  • is_recurring (bool | None) – True if the payment is a recurring subscription one.

  • is_first_recurring (bool | None) – True if the payment is the first recurring one for a subscription created by the bot.

  • subscription_expiration_date (int | None) – For subscription payments, the Unix time when the subscription ends.

Telegram API: https://core.telegram.org/bots/api#successfulpayment

currency: str
invoice_payload: str
is_first_recurring: bool | None
is_recurring: bool | None
order_info: OrderInfo | None
provider_payment_charge_id: str
shipping_option_id: str | None
subscription_expiration_date: int | None
telegram_payment_charge_id: str
total_amount: int

telebot_py.types.reactions

Telegram reaction types.

class telebot_py.types.reactions.MessageReactionCountUpdated(chat: Chat, message_id: int, date: int, reactions: list[ReactionCount])

Bases: TelegramObject

Reaction changes on a message with anonymous reactions.

Variables:

Telegram API: https://core.telegram.org/bots/api#messagereactioncountupdated

chat: Chat
date: int
message_id: int
reactions: list[ReactionCount]
class telebot_py.types.reactions.MessageReactionUpdated(chat: Chat, message_id: int, date: int, old_reaction: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid], new_reaction: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid], user: User | None = None, actor_chat: Chat | None = None)

Bases: TelegramObject

A change of a reaction on a message performed by a user.

Variables:

Telegram API: https://core.telegram.org/bots/api#messagereactionupdated

actor_chat: Chat | None
chat: Chat
date: int
message_id: int
new_reaction: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid]
old_reaction: list[ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid]
user: User | None
class telebot_py.types.reactions.ReactionCount(type: ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid, total_count: int)

Bases: TelegramObject

A reaction type and its total count on a message.

Variables:

Telegram API: https://core.telegram.org/bots/api#reactioncount

total_count: int
type: ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid
class telebot_py.types.reactions.ReactionTypeCustomEmoji(type: str, custom_emoji_id: str)

Bases: TelegramObject

A reaction that uses a custom emoji.

Variables:

  • type (str) – Type of the reaction, always ‘custom_emoji’.

  • custom_emoji_id (str) – Custom emoji identifier.

Telegram API: https://core.telegram.org/bots/api#reactiontypecustomemoji

custom_emoji_id: str
type: str
class telebot_py.types.reactions.ReactionTypeEmoji(type: str, emoji: str)

Bases: TelegramObject

A reaction that uses a regular emoji.

Variables:

  • type (str) – Type of the reaction, always ‘emoji’.

  • emoji (str) – Reaction emoji.

Telegram API: https://core.telegram.org/bots/api#reactiontypeemoji

emoji: str
type: str
class telebot_py.types.reactions.ReactionTypePaid(type: str)

Bases: TelegramObject

A paid reaction.

Variables:

type (str) – Type of the reaction, always ‘paid’.

Telegram API: https://core.telegram.org/bots/api#reactiontypepaid

type: str

telebot_py.types.stickers

Telegram sticker types: Sticker, StickerSet, MaskPosition, InputSticker.

class telebot_py.types.stickers.InputSticker(sticker: str | Mapping[str, object], format: str, emoji_list: list[str], mask_position: MaskPosition | None = None, keywords: list[str] | None = None)

Bases: TelegramObject

A sticker to be added to a sticker set.

Example

>>> sticker = InputSticker(sticker="file-id", format="static", emoji_list=["😀"])
Variables:

  • sticker (str | Mapping[str, object]) – The added sticker; a file_id string or a file reference mapping.

  • format (str) – Format of the sticker, one of static, animated, video.

  • emoji_list (list[str]) – List of 1-20 emoji associated with the sticker.

  • mask_position (telebot_py.types.stickers.MaskPosition | None) – Position where the mask should be placed on faces; for mask stickers only.

  • keywords (list[str] | None) – List of 0-20 search keywords for the sticker with total length up to 64 characters; for regular and custom_emoji stickers only.

Telegram API: https://core.telegram.org/bots/api#inputsticker

emoji_list: list[str]
format: str
keywords: list[str] | None
mask_position: MaskPosition | None
sticker: str | Mapping[str, object]
class telebot_py.types.stickers.MaskPosition(point: str, x_shift: float, y_shift: float, scale: float)

Bases: TelegramObject

The position where a mask sticker should be placed.

Variables:

  • point (str) – The part of the face relative to which the mask should be placed. One of forehead, eyes, mouth, or chin.

  • x_shift (float) – Shift by X-axis measured in widths of the mask scaled to the face size, from left to right.

  • y_shift (float) – Shift by Y-axis measured in heights of the mask scaled to the face size, from top to bottom.

  • scale (float) – Mask scaling coefficient.

Telegram API: https://core.telegram.org/bots/api#maskposition

point: str
scale: float
x_shift: float
y_shift: float
class telebot_py.types.stickers.Sticker(file_id: str, file_unique_id: str, type: str, width: int, height: int, is_animated: bool, is_video: bool, thumbnail: PhotoSize | None = None, emoji: str | None = None, set_name: str | None = None, premium_animation: File | None = None, mask_position: MaskPosition | None = None, custom_emoji_id: str | None = None, needs_repainting: bool | None = None, file_size: int | None = None)

Bases: TelegramObject

A sticker in a message or sticker set.

Variables:

  • file_id (str) – Identifier for this file, which can be used to download or reuse the file.

  • file_unique_id (str) – Unique identifier for this file, which is supposed to be the same over time and for different bots.

  • type (str) – Type of the sticker, currently one of regular, mask, custom_emoji.

  • width (int) – Sticker width in pixels.

  • height (int) – Sticker height in pixels.

  • is_animated (bool) – Whether the sticker is animated.

  • is_video (bool) – Whether the sticker is a video sticker.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Sticker thumbnail in the .WEBP or .JPG format.

  • emoji (str | None) – Emoji associated with the sticker.

  • set_name (str | None) – Name of the sticker set to which the sticker belongs.

  • premium_animation (telebot_py.types.files.File | None) – For premium regular stickers, premium animation for the sticker.

  • mask_position (telebot_py.types.stickers.MaskPosition | None) – For mask stickers, the position where the mask should be placed.

  • custom_emoji_id (str | None) – For custom emoji stickers, unique identifier of the custom emoji.

  • needs_repainting (bool | None) – Whether the sticker must be repainted to a text color in messages.

  • file_size (int | None) – File size in bytes.

Telegram API: https://core.telegram.org/bots/api#sticker

custom_emoji_id: str | None
emoji: str | None
file_id: str
file_size: int | None
file_unique_id: str
height: int
is_animated: bool
is_video: bool
mask_position: MaskPosition | None
needs_repainting: bool | None
premium_animation: File | None
set_name: str | None
thumbnail: PhotoSize | None
type: str
width: int
class telebot_py.types.stickers.StickerSet(name: str, title: str, sticker_type: str, stickers: list[Sticker], thumbnail: PhotoSize | None = None)

Bases: TelegramObject

A sticker set.

Variables:

  • name (str) – Sticker set name.

  • title (str) – Sticker set title.

  • sticker_type (str) – Type of stickers in the set, currently one of regular, mask, custom_emoji.

  • stickers (list[telebot_py.types.stickers.Sticker]) – List of all stickers in the set.

  • thumbnail (telebot_py.types.media.PhotoSize | None) – Sticker set thumbnail in the .WEBP, .TGS, or .WEBM format.

Telegram API: https://core.telegram.org/bots/api#stickerset

name: str
sticker_type: str
stickers: list[Sticker]
thumbnail: PhotoSize | None
title: str

telebot_py.types.stories

Story posting types: content inputs and clickable story areas.

Modelled on the Telegram Bot API story classes and the node sibling’s client/types/business/models.ts declarations (StoryArea, StoryAreaPosition, InputStoryContentPhoto, InputStoryContentVideo).

telebot_py.types.stories.InputStoryContent = telebot_py.types.stories.InputStoryContentPhoto | telebot_py.types.stories.InputStoryContentVideo

Content of a story to post or edit.

class telebot_py.types.stories.InputStoryContentPhoto(type: str, photo: str)

Bases: TelegramObject

A photo to post as a story.

Variables:

  • type (str) – Type of the content, always ‘photo’.

  • photo (str) – Photo to post; 1080x1920 and at most 10 MB. Accepts an attach://<file_attach_name> reference for multipart uploads.

Telegram API: https://core.telegram.org/bots/api#inputstorycontentphoto

photo: str
type: str
class telebot_py.types.stories.InputStoryContentVideo(type: str, video: str, duration: float | None = None, cover: str | None = None, cover_frame_timestamp: float | None = None, is_animation: bool | None = None)

Bases: TelegramObject

A video to post as a story.

Remarks:

Node’s InputStoryContentVideo names the cover fields cover and timestamp; Telegram’s wire fields are cover and cover_frame_timestamp. This class keeps Telegram’s spelling so posted stories parse server-side.

Variables:

  • type (str) – Type of the content, always ‘video’.

  • video (str) – Video to post; 720x1280, H.265, at most 30 MB.

  • duration (float | None) – Precise duration of the video in seconds; 0-60.

  • cover (str | None) – Cover for the video in the story.

  • cover_frame_timestamp (float | None) – Timestamp in seconds of the frame used as the static cover; defaults to 0.

  • is_animation (bool | None) – Whether the video has no sound.

Telegram API: https://core.telegram.org/bots/api#inputstorycontentvideo

cover: str | None
cover_frame_timestamp: float | None
duration: float | None
is_animation: bool | None
type: str
video: str
class telebot_py.types.stories.LocationAddress(country_code: str, state: str | None = None, city: str | None = None, street: str | None = None)

Bases: TelegramObject

The physical address of a location.

Variables:

  • country_code (str) – The two-letter ISO 3166-1 alpha-2 country code of the country where the location is located.

  • state (str | None) – State of the location.

  • city (str | None) – City of the location.

  • street (str | None) – Street address of the location.

Telegram API: https://core.telegram.org/bots/api#locationaddress

city: str | None
country_code: str
state: str | None
street: str | None
class telebot_py.types.stories.StoryArea(position: StoryAreaPosition, type: StoryAreaTypeLocation | StoryAreaTypeSuggestedReaction | StoryAreaTypeLink | StoryAreaTypeWeather | StoryAreaTypeUniqueGift)

Bases: TelegramObject

A clickable area on a story media.

Variables:

Telegram API: https://core.telegram.org/bots/api#storyarea

position: StoryAreaPosition
type: StoryAreaTypeLocation | StoryAreaTypeSuggestedReaction | StoryAreaTypeLink | StoryAreaTypeWeather | StoryAreaTypeUniqueGift
class telebot_py.types.stories.StoryAreaPosition(x_percentage: float, y_percentage: float, width_percentage: float, height_percentage: float, rotation_angle: float, corner_radius_percentage: float)

Bases: TelegramObject

The position of a clickable area within a story.

Variables:

  • x_percentage (float) – The abscissa of the area’s center, as a percentage of the media width.

  • y_percentage (float) – The ordinate of the area’s center, as a percentage of the media height.

  • width_percentage (float) – The width of the area’s rectangle, as a percentage of the media width.

  • height_percentage (float) – The height of the area’s rectangle, as a percentage of the media height.

  • rotation_angle (float) – The clockwise rotation angle of the rectangle, in degrees; 0-360.

  • corner_radius_percentage (float) – The radius of the rectangle corner rounding, as a percentage of the media width.

Telegram API: https://core.telegram.org/bots/api#storyareaposition

corner_radius_percentage: float
height_percentage: float
rotation_angle: float
width_percentage: float
x_percentage: float
y_percentage: float
telebot_py.types.stories.StoryAreaType = telebot_py.types.stories.StoryAreaTypeLocation | telebot_py.types.stories.StoryAreaTypeSuggestedReaction | telebot_py.types.stories.StoryAreaTypeLink | telebot_py.types.stories.StoryAreaTypeWeather | telebot_py.types.stories.StoryAreaTypeUniqueGift

The type of a clickable area on a story.

Bases: TelegramObject

A story area pointing to an HTTP or tg:// link; up to 3 per story.

Variables:

  • type (str) – Type of the area, always ‘link’.

  • url (str) – HTTP or tg:// URL opened when the area is clicked.

Telegram API: https://core.telegram.org/bots/api#storyareatypelink

type: str
url: str
class telebot_py.types.stories.StoryAreaTypeLocation(type: str, latitude: float, longitude: float, address: LocationAddress | None = None)

Bases: TelegramObject

A story area pointing to a location; up to 10 per story.

Variables:

  • type (str) – Type of the area, always ‘location’.

  • latitude (float) – Location latitude in degrees.

  • longitude (float) – Location longitude in degrees.

  • address (telebot_py.types.stories.LocationAddress | None) – Address of the location, decoded into a LocationAddress.

Telegram API: https://core.telegram.org/bots/api#storyareatypelocation

address: LocationAddress | None
latitude: float
longitude: float
type: str
class telebot_py.types.stories.StoryAreaTypeSuggestedReaction(type: str, reaction_type: ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid, is_dark: bool | None = None, is_flipped: bool | None = None)

Bases: TelegramObject

A story area pointing to a suggested reaction; up to 5 per story.

Variables:

Telegram API: https://core.telegram.org/bots/api#storyareatypesuggestedreaction

is_dark: bool | None
is_flipped: bool | None
reaction_type: ReactionTypeEmoji | ReactionTypeCustomEmoji | ReactionTypePaid
type: str
class telebot_py.types.stories.StoryAreaTypeUniqueGift(type: str, name: str)

Bases: TelegramObject

A story area pointing to a unique gift; at most 1 per story.

Variables:

  • type (str) – Type of the area, always ‘unique_gift’.

  • name (str) – Unique name of the gift.

Telegram API: https://core.telegram.org/bots/api#storyareatypeuniquegift

name: str
type: str
class telebot_py.types.stories.StoryAreaTypeWeather(type: str, temperature: float, emoji: str, background_color: int)

Bases: TelegramObject

A story area containing weather information; up to 3 per story.

Remarks:

Telegram names the temperature field temperature; the node sibling’s inline type calls it temperature_c, which is why node never round-trips weather areas. This class follows Telegram’s wire name so payloads parse.

Variables:

  • type (str) – Type of the area, always ‘weather’.

  • temperature (float) – Temperature, in degrees Celsius.

  • emoji (str) – Emoji representing the weather.

  • background_color (int) – A color of the area background in the ARGB format.

Telegram API: https://core.telegram.org/bots/api#storyareatypeweather

background_color: int
emoji: str
temperature: float
type: str

telebot_py.types.topics

Bot profile and forum-topic types: names, commands, topics, menu buttons, access settings.

class telebot_py.types.topics.BotAccessSettings(is_access_restricted: bool, added_users: list[User] | None = None)

Bases: TelegramObject

The access settings of a managed bot.

Variables:

  • is_access_restricted (bool) – True if only selected users can access the bot. The bot’s owner can always access it.

  • added_users (list[telebot_py.types.user.User] | None) – The list of other users who have access to the bot if the access is restricted.

Telegram API: https://core.telegram.org/bots/api#botaccesssettings

added_users: list[User] | None
is_access_restricted: bool
class telebot_py.types.topics.BotCommand(command: str, description: str, is_ephemeral: bool | None = None)

Bases: TelegramObject

A bot command shown in the menu.

Variables:

  • command (str) – Text of the command; 1-32 characters, lowercase English letters, digits and underscores only.

  • description (str) – Description of the command; 1-256 characters.

  • is_ephemeral (bool | None) – Whether the command sends an ephemeral message, visible only to the user who sent it.

Telegram API: https://core.telegram.org/bots/api#botcommand

command: str
description: str
is_ephemeral: bool | None
class telebot_py.types.topics.BotDescription(description: str)

Bases: TelegramObject

The bot’s description shown on its profile page.

Variables:

description (str) – The bot’s description.

Telegram API: https://core.telegram.org/bots/api#botdescription

description: str
class telebot_py.types.topics.BotName(name: str)

Bases: TelegramObject

The bot’s name.

Variables:

name (str) – The bot’s name.

Telegram API: https://core.telegram.org/bots/api#botname

name: str
class telebot_py.types.topics.BotShortDescription(short_description: str)

Bases: TelegramObject

The bot’s short description shown in chats.

Variables:

short_description (str) – The bot’s short description.

Telegram API: https://core.telegram.org/bots/api#botshortdescription

short_description: str
class telebot_py.types.topics.ForumTopic(message_thread_id: int, name: str, icon_color: int, icon_custom_emoji_id: str | None = None, is_name_implicit: bool | None = None)

Bases: TelegramObject

A forum topic.

Variables:

  • message_thread_id (int) – Unique identifier of the forum topic.

  • name (str) – Name of the topic.

  • icon_color (int) – Color of the topic icon in RGB format.

  • icon_custom_emoji_id (str | None) – Unique identifier of the custom emoji shown as the topic icon.

  • is_name_implicit (bool | None) – Whether the name of the topic wasn’t specified explicitly by its creator and likely needs editing.

Telegram API: https://core.telegram.org/bots/api#forumtopic

icon_color: int
icon_custom_emoji_id: str | None
is_name_implicit: bool | None
message_thread_id: int
name: str
telebot_py.types.topics.MenuButton = telebot_py.types.topics.MenuButtonDefault | telebot_py.types.topics.MenuButtonCommands | telebot_py.types.topics.MenuButtonWebApp

Union of the menu button variants returned by getChatMenuButton.

class telebot_py.types.topics.MenuButtonCommands(type: str)

Bases: TelegramObject

A menu button that opens the bot’s list of commands.

Variables:

type (str) – Type of the menu button, always commands.

Telegram API: https://core.telegram.org/bots/api#menubuttoncommands

type: str
class telebot_py.types.topics.MenuButtonDefault(type: str)

Bases: TelegramObject

Describes that no specific value for the menu button was set.

Variables:

type (str) – Type of the menu button, always default.

Telegram API: https://core.telegram.org/bots/api#menubuttondefault

type: str
class telebot_py.types.topics.MenuButtonWebApp(type: str, text: str, web_app: WebAppInfo)

Bases: TelegramObject

A menu button that launches a Web App.

Variables:

  • type (str) – Type of the menu button, always web_app.

  • text (str) – Text on the button.

  • web_app (telebot_py.types.keyboards.WebAppInfo) – Description of the Web App that will be launched when the user presses the button.

Telegram API: https://core.telegram.org/bots/api#menubuttonwebapp

text: str
type: str
web_app: WebAppInfo

telebot_py.types.update

Telegram Update type with the full node (Bot API 10.3) payload set.

class telebot_py.types.update.MessageGenerationStopped(chat: Chat, draft_id: int, message_thread_id: int | None = None)

Bases: TelegramObject

A user asked the bot to stop generating a message (Bot API 10.3+).

Variables:

  • chat (telebot_py.types.chat.Chat) – Chat in which the message is generated.

  • draft_id (int) – Unique identifier of the message draft which was stopped.

  • message_thread_id (int | None) – Unique identifier of the message thread in which the message is generated.

Telegram API: https://core.telegram.org/bots/api#messagegenerationstopped

chat: Chat
draft_id: int
message_thread_id: int | None
class telebot_py.types.update.Update(update_id: int, message: Message | None = None, edited_message: Message | None = None, channel_post: Message | None = None, edited_channel_post: Message | None = None, business_connection: BusinessConnection | None = None, business_message: Message | None = None, edited_business_message: Message | None = None, deleted_business_messages: BusinessMessagesDeleted | None = None, guest_message: Message | None = None, message_reaction: MessageReactionUpdated | None = None, message_reaction_count: MessageReactionCountUpdated | None = None, inline_query: InlineQuery | None = None, chosen_inline_result: ChosenInlineResult | None = None, callback_query: CallbackQuery | None = None, shipping_query: ShippingQuery | None = None, pre_checkout_query: PreCheckoutQuery | None = None, purchased_paid_media: PaidMediaPurchased | None = None, poll: Poll | None = None, poll_answer: PollAnswer | None = None, my_chat_member: ChatMemberUpdated | None = None, chat_member: ChatMemberUpdated | None = None, chat_join_request: ChatJoinRequest | None = None, chat_boost: ChatBoostUpdated | None = None, removed_chat_boost: ChatBoostRemoved | None = None, managed_bot: ManagedBotUpdated | None = None, subscription: BotSubscriptionUpdated | None = None, stopped_message_generation: MessageGenerationStopped | None = None)

Bases: TelegramObject

An incoming update from Telegram.

Exactly one payload field must be set; constructing an update with zero or more than one payload raises ValueError.

Variables:

Telegram API: https://core.telegram.org/bots/api#update

business_connection: BusinessConnection | None
business_message: Message | None
callback_query: CallbackQuery | None
channel_post: Message | None
chat_boost: ChatBoostUpdated | None
chat_join_request: ChatJoinRequest | None
chat_member: ChatMemberUpdated | None
chosen_inline_result: ChosenInlineResult | None
deleted_business_messages: BusinessMessagesDeleted | None
edited_business_message: Message | None
edited_channel_post: Message | None
edited_message: Message | None
property effective_chat: Chat | None

The chat this update happened in, when known.

property effective_message: Message | None

The message carried by this update, regardless of payload type.

property effective_user: User | None

The user who triggered this update, when known.

guest_message: Message | None
inline_query: InlineQuery | None
managed_bot: ManagedBotUpdated | None
message: Message | None
message_reaction: MessageReactionUpdated | None
message_reaction_count: MessageReactionCountUpdated | None
my_chat_member: ChatMemberUpdated | None
poll: Poll | None
poll_answer: PollAnswer | None
pre_checkout_query: PreCheckoutQuery | None
purchased_paid_media: PaidMediaPurchased | None
removed_chat_boost: ChatBoostRemoved | None
shipping_query: ShippingQuery | None
stopped_message_generation: MessageGenerationStopped | None
subscription: BotSubscriptionUpdated | None
update_id: int

telebot_py.types.user

Telegram User type.

class telebot_py.types.user.User(id: int, is_bot: bool, first_name: str, last_name: str | None = None, username: str | None = None, language_code: str | None = None, is_premium: bool | None = None, added_to_attachment_menu: bool | None = None, can_join_groups: bool | None = None, can_read_all_group_messages: bool | None = None, supports_guest_queries: bool | None = None, supports_inline_queries: bool | None = None, can_connect_to_business: bool | None = None, has_main_web_app: bool | None = None, has_topics_enabled: bool | None = None, allows_users_to_create_topics: bool | None = None, can_manage_bots: bool | None = None, supports_join_request_queries: bool | None = None)

Bases: TelegramObject

A Telegram user or bot.

Variables:

  • id (int) – Unique identifier for this user or bot.

  • is_bot (bool) – Whether this user is a bot.

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

  • last_name (str | None) – User’s or bot’s last name, when present.

  • username (str | None) – User’s or bot’s username without leading ‘@’, when present.

  • language_code (str | None) – IETF language tag of the user’s language, when present.

  • is_premium (bool | None) – Whether this user is a Telegram Premium user.

  • added_to_attachment_menu (bool | None) – Whether this user added the bot to the attachment menu.

  • can_join_groups (bool | None) – Whether the bot can be invited to groups (getMe only).

  • can_read_all_group_messages (bool | None) – Whether privacy mode is disabled for the bot in groups (getMe only).

  • supports_guest_queries (bool | None) – Whether the bot supports guest queries from chats it is not a member of (getMe only).

  • supports_inline_queries (bool | None) – Whether the bot supports inline queries (getMe only).

  • can_connect_to_business (bool | None) – Whether the bot can be connected to a Telegram Business account (getMe only).

  • has_main_web_app (bool | None) – Whether the bot has a main Web App (getMe only).

  • has_topics_enabled (bool | None) – Whether the bot has forum topic mode enabled in private chats (getMe only).

  • allows_users_to_create_topics (bool | None) – Whether the bot allows users to create and delete topics in private chats (getMe only).

  • can_manage_bots (bool | None) – Whether other bots can be created to be controlled by this bot (getMe only).

  • supports_join_request_queries (bool | None) – Whether the bot supports join request queries and can be assigned to process them (getMe only).

Telegram API: https://core.telegram.org/bots/api#user

added_to_attachment_menu: bool | None
allows_users_to_create_topics: bool | None
can_connect_to_business: bool | None
can_join_groups: bool | None
can_manage_bots: bool | None
can_read_all_group_messages: bool | None
first_name: str
has_main_web_app: bool | None
has_topics_enabled: bool | None
id: int
is_bot: bool
is_premium: bool | None
language_code: str | None
last_name: str | None
supports_guest_queries: bool | None
supports_inline_queries: bool | None
supports_join_request_queries: bool | None
username: str | None