telebot_py.bot¶

Bot API client: HTTP core, retry policy, typed errors, and method mixins.

telebot_py.bot.base¶

Shared seam and helpers for the Bot method mixins.

telebot_py.bot.base.MarkupLike¶

Markup-shaped parameters accept plain dicts or typed objects with to_dict.

alias of Mapping[str, object] | SupportsToDict

class telebot_py.bot.base.Requester¶

Bases: ABC

Abstract request seam every Bot method mixin builds on.

abstractmethod async request(method: str, payload: Mapping[str, object] | None = None) → object¶

Call a Bot API method and return the unwrapped result.

Parameters:

method – The Bot API method name (e.g. sendMessage).
payload – Method parameters keyed by Telegram field names.

Returns:

The result field of Telegram’s response envelope.

class telebot_py.bot.base.SupportsToDict(*args, **kwargs)¶

Bases: Protocol

Any typed object serializable to Telegram’s wire shape.

to_dict() → dict[str, object]¶: Serialize this object to a plain snake_case dict.

telebot_py.bot.base.UNSET: Final[_Unset] = UNSET¶: Sentinel marking “parameter omitted”, used where an empty value is meaningful.

telebot_py.bot.base.Unset¶: Annotation alias for parameters that are omitted, or set to an explicit value which may itself be empty ("", [], …).

telebot_py.bot.base.clean_payload(**fields: object) → dict[str, object]¶: Build a wire payload, omitting parameters the caller left unset.

telebot_py.bot.base.omit_unset(value: _Val | _Unset) → _Val | None¶

Translate the UNSET sentinel to None for clean_payload().

Parameters:: value – The parameter as received, either a real value or UNSET.
Returns:: None when the caller left the parameter unset, else the value.

telebot_py.bot.base.optional_list(value: Sequence[_Val] | _Unset) → list[_Val] | None¶

Convert an omittable sequence parameter to its JSON list wire shape.

Parameters:: value – The parameter as received: a sequence, or UNSET when the caller omitted it.
Returns:: None when unset so the field is omitted; otherwise a plain list, which is empty exactly when the caller passed an empty sequence.

telebot_py.bot.base.parse_count(result: object) → int¶: Coerce an integer Bot API result, rejecting unexpected shapes.

telebot_py.bot.base.parse_flag(result: object) → bool¶: Coerce a boolean Bot API result, rejecting unexpected shapes.

telebot_py.bot.base.parse_list_result(cls: builtins.type[TObj], result: object) → list[TObj]¶: Hydrate a JSON array result into a list of typed Telegram objects.

telebot_py.bot.base.parse_message_or_true(result: object) → Message | bool¶: Coerce edit-method results: the edited Message, or True for inline edits.

telebot_py.bot.base.parse_result(cls: builtins.type[TObj], result: object) → TObj¶: Hydrate a single JSON object result into a typed Telegram object.

telebot_py.bot.base.parse_string(result: object) → str¶: Coerce a string Bot API result, rejecting unexpected shapes.

telebot_py.bot.base.to_wire(value: Mapping[str, object] | SupportsToDict | None) → dict[str, object] | None¶: Serialize a markup-shaped parameter for the wire, None passing through.

telebot_py.bot.bulk¶

Bulk message Bot API methods (parity with packages/go/pkg/bot/bulk.go).

class telebot_py.bot.bulk.BulkMixin¶

Bases: Requester

Bot methods for forwarding, copying, and deleting many messages at once.

Copy multiple messages without linking to the originals.

Example

>>> ids = await bot.copy_messages("@target", 456, [1, 2])

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
from_chat_id – Unique identifier of the source chat or username of the source channel.
message_ids – Identifiers of the messages to copy, 1-100.
message_thread_id – Target message thread identifier.
direct_messages_topic_id – Unique identifier of the direct messages topic to which the messages are copied, for a direct messages chat.
disable_notification – Send silently.
protect_content – Protect the copied content from saving.
remove_caption – Pass True to copy messages without their captions.

Returns:

The MessageId list of the copied messages.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_messages(chat_id: int | str, message_ids: Sequence[int]) → bool¶

Delete multiple messages from a chat at once.

Example

>>> ok = await bot.delete_messages(789, [5, 6])

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
message_ids – Identifiers of the messages to delete, 1-100.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Forward multiple messages of any kind to a target chat.

Example

>>> ids = await bot.forward_messages(123, "@source", [11, 12])

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
from_chat_id – Unique identifier of the source chat or username of the source channel.
message_ids – Identifiers of the messages to forward, 1-100.
message_thread_id – Target message thread identifier.
direct_messages_topic_id – Unique identifier of the direct messages topic to which the messages are forwarded, for a direct messages chat.
disable_notification – Send silently.
protect_content – Protect the forwarded content from saving.

Returns:

The MessageId list of the forwarded messages.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.business_account¶

Connected business account Bot API methods.

Ported from node client/methods/business/stories-boosts.ts (getBusinessConnection, readBusinessMessage, deleteBusinessMessages) and client/methods/business/gifts.ts (the *BusinessAccount* methods).

class telebot_py.bot.business_account.BusinessAccountMixin¶

Bases: Requester

Bot methods for acting on behalf of a connected business account.

async delete_business_messages(business_connection_id: str, message_ids: Sequence[int]) → bool¶

Delete messages on behalf of a connected business account.

Example

>>> ok = await bot.delete_business_messages("bc1", [100, 101])

Parameters:

business_connection_id – Unique identifier of the business connection.
message_ids – Identifiers of the messages to delete, 1-100 items.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_business_account_star_balance(business_connection_id: str) → StarAmount¶

Get the current amount of Telegram Stars owned by a business account.

Example

>>> balance = await bot.get_business_account_star_balance("bc1")
>>> print(balance.amount)

Parameters:

business_connection_id – Unique identifier of the business connection.

Returns:

The StarAmount held by the business account.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_business_connection(business_connection_id: str) → BusinessConnection¶

Get information about the connection of the bot with a business account.

Example

>>> connection = await bot.get_business_connection("bc1")

Parameters:

business_connection_id – Unique identifier of the business connection.

Returns:

The BusinessConnection object.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async read_business_message(business_connection_id: str, chat_id: int, message_id: int) → bool¶

Mark an incoming message in a business account as read.

Example

>>> ok = await bot.read_business_message("bc1", 42, 100)

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which to read the message.
chat_id – Unique identifier of the chat in which the message was received. The chat must have been active in the last 24 hours.
message_id – Identifier of the message to mark as read.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async remove_business_account_profile_photo(business_connection_id: str, *, is_public: bool | None = None) → bool¶

Remove the current profile photo of a connected business account.

Remarks:: Requires the can_edit_profile_photo business bot right.

Example

>>> ok = await bot.remove_business_account_profile_photo("bc1")

Parameters:

business_connection_id – Unique identifier of the business connection.
is_public – Pass True to remove the public photo, which is visible even if the main photo is hidden by the business account’s privacy settings. After the main photo is removed, the previous profile photo (if present) becomes the main photo.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_business_account_bio(business_connection_id: str, bio: str | None = None) → bool¶

Change the bio description of a connected business account.

Example

>>> ok = await bot.set_business_account_bio("bc1", "We build bots")

Parameters:

business_connection_id – Unique identifier of the business connection.
bio – New bio for the business account; 0-140 characters. Omit to remove the current bio.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_business_account_gift_settings(business_connection_id: str, *, show_gift_button: bool, accepted_gift_types: Mapping[str, object] | SupportsToDict) → bool¶

Change the gift settings of a connected business account.

Example

>>> ok = await bot.set_business_account_gift_settings(
...     "bc1", show_gift_button=True, accepted_gift_types={"unique_gifts": True}
... )

Parameters:

business_connection_id – Unique identifier of the business connection.
show_gift_button – Whether the gifts button should be shown on the business profile.
accepted_gift_types – AcceptedGiftTypes as a to_dict object or a plain dict of Telegram’s field names.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_business_account_name(business_connection_id: str, first_name: str, *, last_name: str | None = None) → bool¶

Change the first and last name of a connected business account.

Remarks:: Requires the can_edit_name business bot right.

Example

>>> ok = await bot.set_business_account_name("bc1", "Acme", last_name="Parts")

Parameters:

business_connection_id – Unique identifier of the business connection.
first_name – The new value of the first name for the business account; 1-64 characters.
last_name – The new value of the last name for the business account; 0-64 characters. Omit to leave it unset.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_business_account_profile_photo(business_connection_id: str, photo: Mapping[str, object] | SupportsToDict, *, is_public: bool | None = None) → bool¶

Change the profile photo of a connected business account.

Remarks:: photo must be an InputProfilePhoto object (dict or to_dict object) referencing an already-uploaded file_id or a URL; multipart uploads are out of scope for the JSON-only client. Requires the can_edit_profile_photo business bot right.

Example

>>> ok = await bot.set_business_account_profile_photo(
...     "bc1", {"type": "photo", "photo": "file-id-1"}
... )

Parameters:

business_connection_id – Unique identifier of the business connection.
photo – InputProfilePhoto describing the new profile photo.
is_public – Pass True to set the public photo, which will be visible even if the main photo is hidden by the business account’s privacy settings. An account can have only one public photo.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_business_account_username(business_connection_id: str, username: str | None = None) → bool¶

Change the username of a connected business account.

Remarks:: Omitting username sends no username field, matching node’s pass-through behaviour; Telegram then removes the current username.

Example

>>> ok = await bot.set_business_account_username("bc1", "acme")

Parameters:

business_connection_id – Unique identifier of the business connection.
username – New username for the business account; pass None or an empty value to remove it.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async transfer_business_account_stars(business_connection_id: str, star_count: int) → bool¶

Transfer Telegram Stars from the balance of a business account.

Example

>>> ok = await bot.transfer_business_account_stars("bc1", 50)

Parameters:

business_connection_id – Unique identifier of the business connection.
star_count – Number of Telegram Stars to transfer; 1-10000.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.chat_management¶

Chat management Bot API methods (parity with packages/go/pkg/bot/chat_management.go).

class telebot_py.bot.chat_management.ChatManagementMixin¶

Bases: Requester

Bot methods for chat titles, photos, pins, permissions, and settings.

async delete_chat_photo(chat_id: int | str) → bool¶

Delete a chat photo.

Photos can’t be deleted for private chats; the bot must be an administrator.

Example

>>> ok = await bot.delete_chat_photo(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_chat_sticker_set(chat_id: int | str) → bool¶

Delete the group sticker set from a supergroup.

The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights.

Example

>>> ok = await bot.delete_chat_sticker_set(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async export_chat_invite_link(chat_id: int | str) → str¶

Generate a new primary invite link for a chat.

Any previously generated primary link is revoked. The bot must be an administrator in the chat.

Example

>>> link = await bot.export_chat_invite_link(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.

Returns:

The exported invite link.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_chat_menu_button(chat_id: int | None = None) → MenuButtonDefault | MenuButtonCommands | MenuButtonWebApp¶

Get the current value of the bot’s menu button.

Example

>>> button = await bot.get_chat_menu_button()

Parameters:

chat_id – Unique identifier of the target private chat; omit for the default menu button.

Returns:

The MenuButton variant currently set.

Raises:

TypeParseError – If Telegram returns an unsupported menu button type.
InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_default_administrator_rights(*, for_channels: bool | None = None) → ChatAdministratorRights¶

Get the current default administrator rights of the bot.

Example

>>> rights = await bot.get_my_default_administrator_rights()

Parameters:

for_channels – Pass True to get rights for channel posts.

Returns:

The ChatAdministratorRights currently set as the default.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async pin_chat_message(chat_id: int | str, message_id: int, *, business_connection_id: str | None = None, disable_notification: bool | None = None) → bool¶

Add a message to the list of pinned messages in a chat.

Example

>>> ok = await bot.pin_chat_message(-100, 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
message_id – Identifier of the message to pin.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be pinned.
disable_notification – Pin without sending a notification.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_description(chat_id: int | str, description: str | _Unset = UNSET) → bool¶

Change the description of a group, supergroup, or channel.

Example

>>> ok = await bot.set_chat_description("@channel", "New description")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
description – New chat description; 0-255 characters. Omit the parameter to leave the description untouched; an explicit "" is sent as an empty description.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_menu_button(chat_id: int | None = None, menu_button: Mapping[str, object] | SupportsToDict | None = None) → bool¶

Change the bot’s menu button in a private chat, or the default one.

Example

>>> ok = await bot.set_chat_menu_button(42, {"type": "commands"})

Parameters:

chat_id – Unique identifier of the target private chat; omit for the default menu button.
menu_button – New menu button as a MenuButton dict or to_dict object.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_permissions(chat_id: int | str, permissions: Mapping[str, object] | SupportsToDict, *, use_independent_chat_permissions: bool | None = None) → bool¶

Set default chat permissions for all members.

The bot must be an administrator in the group or a supergroup.

Example

>>> ok = await bot.set_chat_permissions(-100, {"can_send_messages": True})

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
permissions – New default permissions as a ChatPermissions dict or to_dict object.
use_independent_chat_permissions – Pass True if permissions apply independently of chat-level permissions.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_photo(chat_id: int | str, photo: str) → bool¶

Set a new profile photo for the chat.

Photos can’t be changed for private chats; the bot must be an administrator. Accepts a file_id string; multipart uploads are intentionally out of scope (JSON payloads only).

Example

>>> ok = await bot.set_chat_photo(-100, "photo_file_id")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
photo – New chat photo file_id.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_sticker_set(chat_id: int | str, sticker_set_name: str) → bool¶

Set a new group sticker set for a supergroup.

The bot must be an administrator in the chat for this to work and must have the can_change_info administrator right. Use the field active_sticker_set_id returned by get_chat to test whether the bot can set the sticker set.

Example

>>> ok = await bot.set_chat_sticker_set(-100, "test_set_by_bot")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
sticker_set_name – Name of the sticker set to be set as the group sticker set.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_title(chat_id: int | str, title: str) → bool¶

Change the title of a chat.

Titles can’t be changed for private chats; the bot must be an administrator.

Example

>>> ok = await bot.set_chat_title(-100, "New Title")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
title – New chat title; 0-128 characters.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_default_administrator_rights(rights: Mapping[str, object] | SupportsToDict, *, for_channels: bool | None = None) → bool¶

Change the default administrator rights of the bot.

Example

>>> ok = await bot.set_my_default_administrator_rights(rights_dict)

Parameters:

rights – New default rights as a ChatAdministratorRights dict or to_dict object.
for_channels – Pass True to change rights for channel posts.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unpin_all_chat_messages(chat_id: int | str) → bool¶

Clear the list of pinned messages in a chat.

Example

>>> ok = await bot.unpin_all_chat_messages(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unpin_chat_message(chat_id: int | str, message_id: int | None = None, *, business_connection_id: str | None = None) → bool¶

Remove a message from the list of pinned messages in a chat.

Example

>>> ok = await bot.unpin_chat_message(-100, 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
message_id – Identifier of the message to unpin; omit to unpin the most recently pinned message.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be unpinned.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.chats¶

Chat information and moderation Bot API methods (parity with packages/go/pkg/bot/chats.go).

class telebot_py.bot.chats.ChatsMixin¶

Bases: Requester

Bot methods for chat info, membership counts, and member moderation.

async ban_chat_member(chat_id: int | str, user_id: int, *, until_date: int | None = None, revoke_messages: bool | None = None) → bool¶

Ban a user in a group, supergroup, or channel.

Example

>>> await bot.ban_chat_member(-1001234567890, 777000)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
user_id – Unique identifier of the target user.
until_date – Unix time when the ban ends; ignored if less than 30 seconds or more than 366 days from now (banned forever).
revoke_messages – Also delete all messages from the chat for the user being banned. Always True for channels.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_chat(chat_id: int | str) → ChatFullInfo¶

Get full up-to-date information about a chat.

Example

>>> chat = await bot.get_chat(-1001234567890)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup or channel.

Returns:

The ChatFullInfo object with current chat information, carrying the full documented field set (photo, birthdate, business details, permissions, reactions, rating, community, …).

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_chat_administrators(chat_id: int | str, *, return_bots: bool | None = None) → list[ChatMember]¶

Get a list of administrators in a chat.

Example

>>> admins = await bot.get_chat_administrators(-1001234567890)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
return_bots – Pass True to include bots in the list of administrators.

Returns:

List of ChatMember objects representing administrators.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_chat_member_count(chat_id: int | str) → int¶

Get the number of members in a chat.

Example

>>> count = await bot.get_chat_member_count(-1001234567890)

Parameters:

chat_id – Unique identifier for the target chat or channel username.

Returns:

The member count of the chat.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async leave_chat(chat_id: int | str) → bool¶

Leave a group, supergroup, or channel.

Example

>>> await bot.leave_chat(-1001234567890)

Parameters:

chat_id – Unique identifier for the target chat or channel username.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unban_chat_member(chat_id: int | str, user_id: int, *, only_if_banned: bool | None = None) → bool¶

Unban a previously banned user in a supergroup or channel.

Example

>>> await bot.unban_chat_member(-1001234567890, 777000)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
user_id – Unique identifier of the target user.
only_if_banned – Do nothing if the user is not banned.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.checklists¶

Checklist message Bot API methods.

Ported from node client/methods/messages/edit.ts (sendChecklist, editMessageChecklist).

class telebot_py.bot.checklists.ChecklistsMixin¶

Bases: Requester

Bot methods for sending and editing checklist messages.

Edit a checklist on behalf of a connected business account.

Remarks:: checklist follows the same InputChecklist shape as send_checklist(). Node declares the return as Message | boolean; True is returned when Telegram replies with a bare flag instead of the edited message.

Example

>>> result = await bot.edit_message_checklist(
...     "bc1", 123, 45, {"title": "Todo", "tasks": [{"id": 1, "text": "Ship"}]}
... )

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which the message was sent.
chat_id – Unique identifier for the target chat or username of the target bot.
message_id – Unique identifier of the target message.
checklist – InputChecklist describing the new checklist content.
reply_markup – InlineKeyboardMarkup replacing the message keyboard.

Returns:

The edited Message, or True when Telegram returned a bare flag.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a checklist on behalf of a connected business account.

Remarks:: checklist is an InputChecklist object — either an InputChecklist instance or a plain dict using Telegram’s field names (title, tasks, parse_mode, title_entities, others_can_add_tasks, others_can_mark_tasks_as_done).

Example

>>> from telebot_py.types import InputChecklist, InputChecklistTask
>>> message = await bot.send_checklist(
...     "bc1",
...     123,
...     InputChecklist(
...         title="Shopping",
...         tasks=[InputChecklistTask(id=1, text="Buy milk")],
...     ),
... )

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
chat_id – Unique identifier for the target chat or username of the target bot.
checklist – InputChecklist describing the checklist to send.
disable_notification – Sends the message silently.
protect_content – Protects the contents from forwarding and saving.
message_effect_id – Unique identifier of the message effect to add.
reply_parameters – ReplyParameters object describing the message to reply to.
reply_markup – InlineKeyboardMarkup for the message.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.client¶

HTTP core of the Telegram Bot API client.

class telebot_py.bot.client.Bot(token: str, *, base_url: str = 'https://api.telegram.org', transport: AsyncBaseTransport | None = None, retry_policy: RetryPolicy | None = None, sleep: Callable[[float], Awaitable[None]] | None = None, timeout: float = 30.0)¶

Bases: MessagesMixin, AttachmentsMixin, RichMessagesMixin, MediaMixin, MiscMediaMixin, PollsMixin, StickersMixin, StickerSetsMixin, InlineMixin, PaymentsMixin, GamesMixin, StoriesGiftsMixin, StoriesMixin, ChecklistsMixin, PaidMediaMixin, MiniAppsMixin, BusinessAccountMixin, GiftsMixin, OwnedGiftsMixin, EphemeralMixin, ChatsMixin, ChatManagementMixin, VerificationMixin, InviteLinksMixin, MembersMixin, TopicsMixin, ReactionsMixin, ProfileMixin, ManagedBotMixin, FilesMixin, BulkMixin, EditsMixin, WebhookMixin

Telegram Bot API HTTP client.

Owns a single httpx.AsyncClient and performs response-envelope unwrapping, typed error mapping, and retry with exponential backoff (FR-012). The transport is injectable so tests can run fully offline. Typed Bot API methods (messages, media, stickers, inline, payments, games, stories, story management, checklists, paid media, mini app queries, business accounts, gifts, owned gifts, ephemeral messages, chats, chat management, verification, invite links, members, topics, reactions, profile, managed bots, files, bulk operations, edits, webhook) are composed onto this class via mixins.

Example

>>> bot = Bot("123456:ABC...")
>>> me = await bot.get_me()
>>> await bot.shutdown()

Variables:

token – The bot token issued by BotFather.
base_url – Bot API server base URL.

async get_me() → User¶

Get basic information about the bot in form of a User object.

This is the startup identity check: a 401 here raises InvalidTokenError so misconfigured bots fail fast.

Example

>>> me = await bot.get_me()

Returns:

The User object representing the bot itself.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_updates(*, offset: int | None = None, limit: int | None = None, timeout: int = 0, allowed_updates: Sequence[str] | None = None) → list[Update]¶

Retrieve incoming updates using long polling.

Example

>>> updates = await bot.get_updates(offset=1001, timeout=30)

Parameters:

offset – Identifier of the first update to return; usually the last processed update_id plus one.
limit – Maximum number of updates to retrieve, 1-100.
timeout – Long-poll timeout in seconds, 0 for a normal short poll. Zero is omitted from the wire payload since Telegram’s own default is also 0.
allowed_updates – Update types to receive; defaults to all except chat_member.

Returns:

A list of parsed Update objects, oldest first.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async request(method: str, payload: Mapping[str, object] | None = None) → object¶

Call a Bot API method and return the unwrapped result.

Parameters:

method – The Bot API method name (e.g. sendMessage).
payload – Method parameters keyed by Telegram field names.

Returns:

The result field of Telegram’s response envelope.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok, or when retries are exhausted on 429/5xx responses.
NetworkError – If the transport keeps failing after retries are exhausted.

async shutdown() → None¶: Close the underlying HTTP client and release its connections.

telebot_py.bot.edits¶

Message editing and deletion Bot API methods.

class telebot_py.bot.edits.EditsMixin¶

Bases: Requester

Bot methods editing or deleting messages already sent.

async delete_message(chat_id: int | str, message_id: int) → bool¶

Delete a message in a chat.

Telegram imposes deletion limits (age and media kind); a failed deletion raises rather than returning False.

Example

>>> await bot.delete_message(123456, 7)

Parameters:

chat_id – Chat containing the message.
message_id – Identifier of the message to delete.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the caption of a media message sent by the bot or via the bot.

Example

>>> msg = await bot.edit_message_caption(chat_id=1, message_id=2, caption="new")

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to edit; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to edit, instead of chat_id and message_id.
caption – New caption of the message, 0-1024 characters; omit to remove the caption.
parse_mode – Parse mode for the new caption entities.
caption_entities – Special entities for the new caption.
show_caption_above_media – Pass True, if the caption must be shown above the message media.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The edited Message, or True when an inline message was edited.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the live location of a live-location message.

Example

>>> msg = await bot.edit_message_live_location(37.5, -122.5, chat_id=1, message_id=2)

Parameters:

latitude – New latitude of the location, in degrees.
longitude – New longitude of the location, in degrees.
business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to edit; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to edit, instead of chat_id and message_id.
live_period – New period in seconds during which the location can be updated, starting from the message send date.
horizontal_accuracy – Radius of uncertainty for the location, in meters; 0-1500.
heading – Direction in which the user is moving, in degrees; 1-360.
proximity_alert_radius – Maximum distance for proximity alerts about approaching another chat member, in meters; 1-100000.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The edited Message, or True when an inline message was edited.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the media of a media message sent by the bot or via the bot.

Example

>>> msg = await bot.edit_message_media(
...     {"type": "photo", "media": "https://example.com/new.jpg"},
...     chat_id=1,
...     message_id=2,
... )

Parameters:

media – The new media content, an InputMedia-family mapping (keys type, media, and type-specific optionals) given as a dict or to_dict object. Only file_id/HTTP URL media references are supported; file uploads are out of scope.
business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to edit; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to edit, instead of chat_id and message_id.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The edited Message, or True when an inline message was edited.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit only the reply markup of a message sent by the bot or via the bot.

Example

>>> msg = await bot.edit_message_reply_markup(chat_id=1, message_id=2, reply_markup={})

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to edit; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to edit, instead of chat_id and message_id.
reply_markup – New inline keyboard for the message; pass {} to remove the keyboard. Dict or to_dict object.

Returns:

The edited Message, or True when an inline message was edited.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the text of a message sent by the bot or via the bot.

Example

>>> msg = await bot.edit_message_text("new text", chat_id=1, message_id=2)

Parameters:

text – New text of the message, 1-4096 characters after entity parsing; required unless rich_message is given.
business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to edit; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to edit, instead of chat_id and message_id.
parse_mode – Parse mode for the new text entities.
entities – Special entities for the new text.
rich_message – InputRichMessage with the new rich content.
link_preview_options – Link preview generation options, as a LinkPreviewOptions object or a mapping.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The edited Message, or True when an inline message was edited.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Stream a partial message draft while the final answer is generated.

Remarks:: The draft is ephemeral: it acts as a temporary 30-second preview, so the bot must still call sendMessage with the complete text to persist the message. Passing an empty text shows a “Thinking…” placeholder.

Example

>>> ok = await bot.send_message_draft(123, 1, text="Working on it")

Parameters:

chat_id – Unique identifier for the target private chat.
draft_id – Unique identifier of the message draft; must be non-zero. Drafts sharing an identifier are animated.
message_thread_id – Unique identifier of the target message thread.
text – Text of the draft, 0-4096 characters after entities parsing.
parse_mode – Mode for parsing entities in the draft text.
entities – MessageEntity items as to_dict objects or dicts; can be specified instead of parse_mode.
can_stop – Whether to show the user a button stopping further drafts.
keep_on_stop – Whether to keep the draft in the chat when the stop button is pressed.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Stop updating a live location message before its period expires.

Example

>>> msg = await bot.stop_message_live_location(chat_id=1, message_id=2)

Parameters:

business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
chat_id – Chat containing the message; required unless inline_message_id is given.
message_id – Identifier of the message to stop; required unless inline_message_id is given.
inline_message_id – Identifier of the inline message to stop, instead of chat_id and message_id.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The stopped Message, or True when an inline message was stopped.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async stop_poll(chat_id: int | str, message_id: int, *, business_connection_id: str | None = None, reply_markup: Mapping[str, object] | SupportsToDict | None = None) → Poll¶

Stop a poll which was sent by the bot.

Example

>>> poll = await bot.stop_poll(123456, 7)
>>> poll.total_voter_count
3

Parameters:

chat_id – Chat containing the poll message.
message_id – Identifier of the message with the poll.
business_connection_id – Unique identifier of the business connection on behalf of which the message to be edited was sent.
reply_markup – New inline keyboard for the message; dict or to_dict object.

Returns:

The final stopped Poll state.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.ephemeral¶

Ephemeral message Bot API methods.

Ported from node client/methods/business/ephemeral.ts (editEphemeralMessageText, editEphemeralMessageCaption, editEphemeralMessageMedia, editEphemeralMessageReplyMarkup, deleteEphemeralMessage).

class telebot_py.bot.ephemeral.EphemeralMixin¶

Bases: Requester

Bot methods for editing and deleting ephemeral messages.

async delete_ephemeral_message(chat_id: int | str, receiver_user_id: int, ephemeral_message_id: int) → bool¶

Delete an ephemeral message.

Example

>>> ok = await bot.delete_ephemeral_message(100, 42, 7)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
receiver_user_id – Identifier of the user who received the message.
ephemeral_message_id – Identifier of the ephemeral message to delete.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the caption of an ephemeral media message.

Example

>>> result = await bot.edit_ephemeral_message_caption(
...     100, 42, 7, caption="new caption"
... )

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
receiver_user_id – Identifier of the user who received the message.
ephemeral_message_id – Identifier of the ephemeral message to edit.
caption – New caption of the message, 0-1024 characters after entities parsing.
parse_mode – Mode for parsing entities in the caption.
caption_entities – MessageEntity items as to_dict objects or dicts.
show_caption_above_media – Whether the caption must be shown above the message media.
reply_markup – InlineKeyboardMarkup for the message.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_ephemeral_message_media(chat_id: int | str, receiver_user_id: int, ephemeral_message_id: int, media: Mapping[str, object] | SupportsToDict, *, reply_markup: Mapping[str, object] | SupportsToDict | None = None) → bool¶

Edit the media of an ephemeral message.

Example

>>> result = await bot.edit_ephemeral_message_media(
...     100, 42, 7, {"type": "photo", "media": "file-id-1"}
... )

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
receiver_user_id – Identifier of the user who received the message.
ephemeral_message_id – Identifier of the ephemeral message to edit.
media – InputMedia object (dict or to_dict object) describing the new media content.
reply_markup – InlineKeyboardMarkup for the message.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_ephemeral_message_reply_markup(chat_id: int | str, receiver_user_id: int, ephemeral_message_id: int, *, reply_markup: Mapping[str, object] | SupportsToDict | None = None) → bool¶

Edit the inline keyboard of an ephemeral message.

Example

>>> result = await bot.edit_ephemeral_message_reply_markup(
...     100, 42, 7, reply_markup=markup
... )

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
receiver_user_id – Identifier of the user who received the message.
ephemeral_message_id – Identifier of the ephemeral message to edit.
reply_markup – New InlineKeyboardMarkup; omit or pass None according to Telegram’s semantics to remove the keyboard.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit the text of an ephemeral message.

Example

>>> result = await bot.edit_ephemeral_message_text(
...     100, 42, 7, text="new text"
... )

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
receiver_user_id – Identifier of the user who received the message.
ephemeral_message_id – Identifier of the ephemeral message to edit.
text – New text of the message, 1-4096 characters after entity parsing; required unless rich_message is given.
parse_mode – Mode for parsing entities in the message text.
entities – MessageEntity items as to_dict objects or dicts.
rich_message – InputRichMessage with the new rich content.
link_preview_options – Link preview generation options, as a LinkPreviewOptions object or a mapping.
reply_markup – InlineKeyboardMarkup for the message.

Returns:

True on success. Unlike the edit_message_* family, this method never returns the edited Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.errors¶

Typed error hierarchy for the framework (FR-012, contracts §9).

exception telebot_py.bot.errors.ApplicationError¶

Bases: TelebotError

Misuse of the application kernel lifecycle.

exception telebot_py.bot.errors.InvalidTokenError(error_code: int, description: str, *, method: str | None = None, retry_after: float | None = None)¶

Bases: TelegramApiError

The bot token was rejected by Telegram (HTTP 401).

exception telebot_py.bot.errors.NetworkError¶

Bases: TelebotError

Transport-level failure communicating with the Telegram servers.

exception telebot_py.bot.errors.TelebotError¶

Bases: Exception

Base class for all telebot-py errors.

exception telebot_py.bot.errors.TelegramApiError(error_code: int, description: str, *, method: str | None = None, retry_after: float | None = None)¶

Bases: TelebotError

The Telegram Bot API responded with an error.

Variables:

error_code – Telegram’s error_code (typically the HTTP status).
description – Telegram’s human-readable description.
method – The Bot API method that failed, when known.
retry_after – Telegram’s flood-control hint in seconds, when provided.

telebot_py.bot.files¶

File Bot API methods (parity with packages/go/pkg/bot/files.go).

class telebot_py.bot.files.FilesMixin¶

Bases: Requester

Bot methods for file metadata and user profile photos.

async get_file(file_id: str) → File¶

Get basic information about a file and prepare it for downloading.

The actual download URL is {base_url}/file/bot{token}/{file_path}.

Example

>>> file = await bot.get_file("file_123")

Parameters:

file_id – File identifier to get information about.

Returns:

The File object; file_path is set when the file is ready.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_user_profile_photos(user_id: int, *, offset: int | None = None, limit: int | None = None) → UserProfilePhotos¶

Get a list of profile pictures for a user.

Example

>>> photos = await bot.get_user_profile_photos(42, limit=10)

Parameters:

user_id – Unique identifier of the target user.
offset – Sequential number of the first photo to return.
limit – Maximum number of photos to retrieve, 1-100.

Returns:

The UserProfilePhotos object.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.games¶

Game and Telegram Passport Bot API methods (parity with games-passport.ts).

class telebot_py.bot.games.GamesMixin¶

Bases: Requester

Bot methods for sending games, managing scores, and reporting Passport errors.

async get_game_high_scores(user_id: int, *, chat_id: int | str | None = None, message_id: int | None = None, inline_message_id: str | None = None) → list[GameHighScore]¶

Get the high scores of a user and their neighbors in a game.

Example

>>> scores = await bot.get_game_high_scores(1, chat_id=2, message_id=30)

Parameters:

user_id – Target user identifier.
chat_id – Chat containing the game message (chat-message target).
message_id – Identifier of the game message (chat-message target).
inline_message_id – Identifier of the inline message (inline target).

Returns:

The GameHighScore entries.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a game.

Example

>>> msg = await bot.send_game("@gamechannel", "lucas")

Parameters:

chat_id – Unique identifier for the target chat (game chats only).
game_short_name – Short name of the game set up via BotFather.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
reply_parameters – Description of the message to reply to.
reply_markup – Inline keyboard for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Set the score of a user in a game.

Targets either a chat message (chat_id + message_id) or an inline message (inline_message_id).

Example

>>> result = await bot.set_game_score(1, 42, chat_id=2, message_id=30)

Parameters:

user_id – User identifier of the score setter.
score – New score, non-negative.
force – Pass True to allow decreasing the score, even when it is lower than current high scores in the chat.
disable_edit_message – Do not edit the game message to include the current scoreboard.
chat_id – Chat containing the game message (chat-message target).
message_id – Identifier of the game message (chat-message target).
inline_message_id – Identifier of the inline message (inline target).

Returns:

The edited Message for chat-message targets, or True for inline targets.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_passport_data_errors(user_id: int, errors: Sequence[Mapping[str, object] | SupportsToDict]) → bool¶

Tell a user that some Telegram Passport elements they provided are invalid.

The user will not be able to re-submit their Passport until the errors are fixed. Each entry may be a plain dict or any object exposing to_dict; variant-specific keys (field_name, file_hash, element_hash) are only reachable through the dict shape.

Example

>>> ok = await bot.set_passport_data_errors(42, [
...     {
...         "source": "data_field",
...         "type": "personal_details",
...         "field_name": "first_name",
...         "hash": "abc123",
...         "message": "First name is invalid",
...     }
... ])

Parameters:

user_id – Unique identifier of the target user.
errors – One error per problematic Passport element, as dicts or to_dict objects.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.gifts¶

Gift sending and gift-management Bot API methods.

Ported from node client/methods/payments.ts (getAvailableGifts, sendGift) and client/methods/business/gifts.ts (giftPremiumSubscription, convertGiftToStars, upgradeGift, transferGift).

class telebot_py.bot.gifts.GiftsMixin¶

Bases: Requester

Bot methods for sending gifts and managing owned gifts.

async convert_gift_to_stars(business_connection_id: str, owned_gift_id: str) → bool¶

Convert a given regular gift owned by a business account to Stars.

Remarks:: Requires the can_convert_gifts_to_stars business bot right.

Example

>>> ok = await bot.convert_gift_to_stars("bc1", "own1")

Parameters:

business_connection_id – Unique identifier of the business connection.
owned_gift_id – Unique identifier of the regular gift that should be converted to Telegram Stars.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_available_gifts() → Gifts¶

Get the list of gifts that can be sent by the bot to users and channel chats.

Example

>>> gifts = await bot.get_available_gifts()
>>> print(len(gifts.gifts))

Returns:

The Gifts object carrying the available gifts.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async gift_premium_subscription(user_id: int, month_count: int, star_count: int, *, text: str | None = None, text_parse_mode: str | None = None, text_entities: Sequence[Mapping[str, object] | SupportsToDict] | None = None) → bool¶

Gift a Telegram Premium subscription to a user.

Remarks:: month_count must be one of 3, 6, 12 and star_count must match the price Telegram charges for that duration (1000, 1500 and 2500 Stars respectively).

Example

>>> ok = await bot.gift_premium_subscription(123, 3, 1000)

Parameters:

user_id – Unique identifier of the target user.
month_count – Number of months the subscription will be active; one of 3, 6, 12.
star_count – Number of Telegram Stars to pay for the subscription.
text – Text shown along with the service message about the subscription; 0-128 characters.
text_parse_mode – Mode for parsing entities in the text.
text_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of text_parse_mode.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a gift to the given user or channel chat.

Remarks:: Telegram’s user_id and chat_id are mutually exclusive and each required only when the other is omitted; exactly one of them must be passed. The gift can’t be converted to Telegram Stars by the receiver.

Example

>>> ok = await bot.send_gift(
...     123, "gift1", text="Enjoy your gift!", pay_for_upgrade=True
... )
>>> ok = await bot.send_gift(chat_id="@my_channel", gift_id="gift1")

Parameters:

user_id – Unique identifier of the target user who will receive the gift. Required if chat_id is not specified.
gift_id – Identifier of the gift; limited gifts can’t be sent to channel chats.
chat_id – Unique identifier for the chat or username of the channel (in the format @username) that will receive the gift. Required if user_id is not specified.
pay_for_upgrade – Pass True to pay for the gift upgrade from the bot’s balance, thereby making the upgrade free for the receiver.
text – Text that will be shown along with the gift; 0-128 characters.
text_parse_mode – Mode for parsing entities in the text.
text_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of text_parse_mode.

Returns:

True on success.

Raises:

ValueError – If gift_id is missing, or if user_id and chat_id are both passed or both omitted.
InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async transfer_gift(business_connection_id: str, owned_gift_id: str, new_owner_chat_id: int, *, star_count: int | None = None) → bool¶

Transfer an owned unique gift to another user or chat.

Remarks:: Requires the can_transfer_and_upgrade_gifts business bot right, and additionally can_transfer_stars when star_count is positive.

Example

>>> ok = await bot.transfer_gift("bc1", "own1", -1001234567890)

Parameters:

business_connection_id – Unique identifier of the business connection.
owned_gift_id – Unique identifier of the regular gift that should be transferred.
new_owner_chat_id – Unique identifier of the chat which will own the gift. The chat must be active in the last 24 hours.
star_count – The amount of Telegram Stars that will be paid for the transfer from the business account balance. If positive, the can_transfer_stars right is required.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async upgrade_gift(business_connection_id: str, owned_gift_id: str, *, keep_original_details: bool | None = None, star_count: int | None = None) → bool¶

Upgrade a given regular gift to a unique gift.

Remarks:: Requires the can_transfer_and_upgrade_gifts business bot right, and additionally can_transfer_stars when the upgrade is paid (i.e. when star_count is positive).

Example

>>> ok = await bot.upgrade_gift("bc1", "own1", star_count=100)

Parameters:

business_connection_id – Unique identifier of the business connection.
owned_gift_id – Unique identifier of the regular gift that should be upgraded to a unique one.
keep_original_details – Pass True to keep the original gift text, sender and receiver in the upgraded gift.
star_count – The amount of Telegram Stars that will be paid for the upgrade from the business account balance. If gift.prepaid_upgrade_star_count is positive, pass 0; otherwise the can_transfer_stars right is required and the gift’s upgrade_star_count must be passed.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.inline¶

Inline-mode Bot API methods (parity with packages/go/pkg/bot/inline.go).

class telebot_py.bot.inline.InlineMixin¶

Bases: Requester

Bot methods for answering inline queries from search results.

Send answers to an inline query.

Example

>>> ok = await bot.answer_inline_query(query.id, [result.to_dict()])

Parameters:

inline_query_id – Unique identifier of the answered query.
results – Inline query results; dicts or to_dict objects.
cache_time – Seconds the result may be cached on the server.
is_personal – Pass True if results may be cached only for the querying user; by default results are public.
next_offset – Offset the client should use in the next query.
button – Inline query results button (InlineQueryResultsButton).

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async answer_web_app_query(web_app_query_id: str, result: Mapping[str, object] | SupportsToDict) → SentWebAppMessage¶

Set the result of an interaction with a Web App.

Example

>>> message = await bot.answer_web_app_query(query_id, result)

Parameters:

web_app_query_id – Unique identifier of the Web App query.
result – The result description as an InlineQueryResult dict.

Returns:

A SentWebAppMessage with the sent message identifier.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async save_prepared_inline_message(user_id: int, result: Mapping[str, object] | SupportsToDict, *, allow_user_chats: bool | None = None, allow_bot_chats: bool | None = None, allow_group_chats: bool | None = None, allow_channel_chats: bool | None = None) → PreparedInlineMessage¶

Store a message a Mini App user can send to a chat later.

Example

>>> prepared = await bot.save_prepared_inline_message(42, result)

Parameters:

user_id – Unique identifier of the user who may send the message.
result – The message description as an InlineQueryResult dict.
allow_user_chats – Allow sending to private chats with users.
allow_bot_chats – Allow sending to private chats with bots.
allow_group_chats – Allow sending to group and supergroup chats.
allow_channel_chats – Allow sending to channel chats.

Returns:

The stored PreparedInlineMessage.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.invite_links¶

Invite link Bot API methods (parity with packages/go/pkg/bot/invite_links.go).

class telebot_py.bot.invite_links.InviteLinksMixin¶

Bases: Requester

Bot methods for creating, editing, and revoking chat invite links.

Create an additional invite link for a chat.

The bot must be an administrator in the chat for this to work.

Example

>>> link = await bot.create_chat_invite_link(-100, member_limit=10)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
name – Invite link name; 0-32 characters.
expire_date – Point in time (Unix timestamp) when the link expires.
member_limit – Maximum number of users that can join via this link.
creates_join_request – Pass True if users joining via the link must be approved by an administrator.

Returns:

The new ChatInviteLink.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async create_chat_subscription_invite_link(chat_id: int | str, subscription_period: int, subscription_price: int, *, name: str | None = None) → ChatInviteLink¶

Create a subscription invite link for a channel chat.

The bot must have the can_invite_users administrator right.

Example

>>> link = await bot.create_chat_subscription_invite_link(-100, 2592000, 50)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
subscription_period – Number of seconds the subscription will be active for; 30-2548560, i.e. one month to one year.
subscription_price – Number of Telegram Stars that must be paid to subscribe after the initial period; 1-2500.
name – Invite link name; 0-32 characters.

Returns:

The new subscription ChatInviteLink.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit a non-primary invite link created by the bot.

The bot must be an administrator in the chat for this to work.

Example

>>> link = await bot.edit_chat_invite_link(-100, url, member_limit=20)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
invite_link – The invite link to edit.
name – Invite link name; 0-32 characters.
expire_date – Point in time (Unix timestamp) when the link expires.
member_limit – Maximum number of users that can join via this link.
creates_join_request – Pass True if users joining via the link must be approved by an administrator.

Returns:

The edited ChatInviteLink.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_chat_subscription_invite_link(chat_id: int | str, invite_link: str, *, name: str | None = None) → ChatInviteLink¶

Edit the name of a subscription invite link created by the bot.

The subscription period and price of an existing link can’t be changed.

Example

>>> link = await bot.edit_chat_subscription_invite_link(-100, url, name="VIP")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
invite_link – The subscription invite link to edit.
name – New invite link name; 0-32 characters.

Returns:

The edited subscription ChatInviteLink.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async revoke_chat_invite_link(chat_id: int | str, invite_link: str) → ChatInviteLink¶

Revoke an invite link created by the bot.

If the primary link is revoked, a new link is automatically generated. The bot must be an administrator in the chat.

Example

>>> link = await bot.revoke_chat_invite_link(-100, url)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
invite_link – The invite link to revoke.

Returns:

The revoked ChatInviteLink.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.media¶

Media-sending Bot API methods (parity with packages/go/pkg/bot/media.go).

class telebot_py.bot.media.MediaMixin¶

Bases: Requester

Bot methods for sending audio, video, animations, voice, and video notes.

Media parameters accept file_id strings or HTTP URLs; multipart file uploads are intentionally out of scope (JSON payloads only).

Send an animation (GIF or H.264/MPEG-4 AVC without sound).

Example

>>> msg = await bot.send_animation(123456, "anim_file_id", has_spoiler=True)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
animation – Animation to send as a file_id string or HTTP URL.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
duration – Duration of the animation in seconds.
width – Animation width.
height – Animation height.
thumbnail – Thumbnail file_id or URL of the file sent.
caption – Animation caption, 0-1024 characters.
parse_mode – Parse mode for the caption.
caption_entities – Special entities for the caption.
show_caption_above_media – Show the caption above the media.
has_spoiler – Mark the animation as covered with a spoiler.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send an audio file by file_id or HTTP URL.

Example

>>> msg = await bot.send_audio(123456, "audio_file_id", caption="song")

Parameters:

chat_id – Unique identifier for the target chat or channel username.
audio – Audio file to send as a file_id string or HTTP URL.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
caption – Audio caption, 0-1024 characters.
parse_mode – Parse mode for the caption.
caption_entities – Special entities for the caption.
duration – Duration of the audio in seconds.
performer – Performer of the audio.
title – Track name.
thumbnail – Thumbnail file_id or URL of the file sent.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a video file by file_id or HTTP URL.

Example

>>> msg = await bot.send_video(123456, "video_file_id", width=1920, height=1080)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
video – Video to send as a file_id string or HTTP URL.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
duration – Duration of the video in seconds.
width – Video width.
height – Video height.
thumbnail – Thumbnail file_id or URL of the file sent.
cover – Cover photo for the video. Pass a file_id string or HTTP URL.
start_timestamp – Start timestamp for the video in the message.
caption – Video caption, 0-1024 characters.
parse_mode – Parse mode for the caption.
caption_entities – Special entities for the caption.
show_caption_above_media – Show the caption above the media.
has_spoiler – Mark the video as covered with a spoiler.
supports_streaming – Pass True if the video is suitable for streaming.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a square video message (video note).

Example

>>> msg = await bot.send_video_note(123456, "vn_file_id", length=240)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
video_note – Video note to send as a file_id string or HTTP URL.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
duration – Duration of the video in seconds.
length – Video width and height, i.e. diameter of the video note.
thumbnail – Thumbnail file_id or URL of the file sent.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send an audio file for display as a voice message.

Example

>>> msg = await bot.send_voice(123456, "voice_file_id", duration=10)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
voice – Voice message to send as a file_id string or HTTP URL; OGG encoded with OPUS.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
caption – Voice message caption, 0-1024 characters.
parse_mode – Parse mode for the caption.
caption_entities – Special entities for the caption.
duration – Duration of the voice message in seconds.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.members¶

Chat member Bot API methods (parity with packages/go/pkg/bot/members.go).

class telebot_py.bot.members.MembersMixin¶

Bases: Requester

Bot methods for inspecting and managing individual chat members.

async approve_chat_join_request(chat_id: int | str, user_id: int) → bool¶

Approve a chat join request.

Example

>>> ok = await bot.approve_chat_join_request("@my_channel", 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
user_id – Unique identifier of the target user.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async ban_chat_sender_chat(chat_id: int | str, sender_chat_id: int) → bool¶

Ban a channel chat in a supergroup or a channel.

Example

>>> ok = await bot.ban_chat_sender_chat(-100, -1009876543210)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
sender_chat_id – Unique identifier of the target sender chat.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async decline_chat_join_request(chat_id: int | str, user_id: int) → bool¶

Decline a chat join request.

Example

>>> ok = await bot.decline_chat_join_request("@my_channel", 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
user_id – Unique identifier of the target user.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_chat_member(chat_id: int | str, user_id: int) → ChatMember¶

Get information about one member of a chat.

Example

>>> member = await bot.get_chat_member("@supergroup", 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
user_id – Unique identifier of the target user.

Returns:

The ChatMember describing the user’s membership.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_user_chat_boosts(chat_id: int | str, user_id: int) → UserChatBoosts¶

Get the list of boosts added to a chat by a user.

Requires administrator rights in the chat.

Example

>>> boosts = await bot.get_user_chat_boosts(-100, 42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
user_id – Unique identifier of the target user.

Returns:

The UserChatBoosts list of boosts the user added to the chat.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Promote or demote a user in a supergroup or a channel.

To demote, pass the applicable rights as False.

Example

>>> ok = await bot.promote_chat_member(-100, 42, can_delete_messages=True)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
user_id – Unique identifier of the target user.
is_anonymous – Pass True if the administrator’s presence is hidden.
can_manage_chat – Access to chat statistics and other admin features.
can_post_messages – Can post messages in the channel.
can_edit_messages – Can edit messages of other users.
can_delete_messages – Can delete messages of other users.
can_post_stories – Can post stories.
can_edit_stories – Can edit posted stories.
can_delete_stories – Can delete stories posted by others.
can_manage_video_chats – Can manage video chats.
can_restrict_members – Can restrict, ban, or unban members.
can_promote_members – Can add new administrators.
can_change_info – Can change the chat title, photo, and settings.
can_invite_users – Can invite new users to the chat.
can_pin_messages – Can pin messages (groups only).
can_manage_topics – Can manage forum topics.
can_manage_direct_messages – Can manage direct messages.
can_manage_tags – Can manage tags.
can_send_welcome_messages – Can send welcome messages.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async restrict_chat_member(chat_id: int | str, user_id: int, permissions: Mapping[str, object] | SupportsToDict, *, use_independent_chat_permissions: bool | None = None, until_date: int | None = None) → bool¶

Restrict a user in a supergroup.

Example

>>> ok = await bot.restrict_chat_member(-100, 42, {"can_send_polls": False})

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
user_id – Unique identifier of the target user.
permissions – New user permissions as a ChatPermissions dict or to_dict object.
use_independent_chat_permissions – Pass True if permissions apply independently of chat-level permissions.
until_date – Point in time (Unix timestamp) when restrictions are lifted.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_administrator_custom_title(chat_id: int | str, user_id: int, custom_title: str) → bool¶

Set a custom title for a bot-promoted administrator in a supergroup.

Example

>>> ok = await bot.set_chat_administrator_custom_title(-100, 42, "Moderator")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
user_id – Unique identifier of the target user.
custom_title – New custom title; 0-16 characters, no emoji.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_chat_member_tag(chat_id: int | str, user_id: int, tag: str | None = None) → bool¶

Set or remove a custom tag on a regular member of a forum supergroup.

The bot must be an administrator with the can_manage_tags right. Passing an empty tag removes the current one.

Example

>>> ok = await bot.set_chat_member_tag(-100, 42, "VIP")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
user_id – Unique identifier of the target user.
tag – New tag for the member; 0-64 characters. Omit to leave the existing tag untouched.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unban_chat_sender_chat(chat_id: int | str, sender_chat_id: int) → bool¶

Unban a previously banned channel chat in a supergroup or channel.

Example

>>> ok = await bot.unban_chat_sender_chat(-100, -1009876543210)

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
sender_chat_id – Unique identifier of the target sender chat.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.messages¶

Message-sending Bot API methods (parity with packages/go/pkg/bot/messages.go).

class telebot_py.bot.messages.MessagesMixin¶

Bases: Requester

Bot methods for sending text messages, chat actions, forwards, and copies.

async answer_callback_query(callback_query_id: str, *, text: str | None = None, show_alert: bool | None = None, url: str | None = None, cache_time: int | None = None) → bool¶

Send an answer to a callback query sent by a callback keyboard.

Example

>>> await bot.answer_callback_query(update.callback_query.id, text="Saved!")

Parameters:

callback_query_id – Unique identifier of the callback query to answer, e.g. update.callback_query.id.
text – Text of the notification, 0-200 characters; shown as an alert when show_alert is True.
show_alert – If True, show the text as an alert instead of a notification at the top of the chat screen.
url – URL that will be opened by the user’s client; only for games or callback buttons that open a bot URL.
cache_time – Maximum time the result may be cached client-side, in seconds.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Copy a message of any kind without linking to the original.

Example

>>> copied = await bot.copy_message(target_chat, source_chat, 123)

Parameters:

chat_id – Unique identifier for the destination chat.
from_chat_id – Chat where the source message lives.
message_id – Message identifier to copy.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
caption – New caption for the copy, 0-1024 characters.
parse_mode – Parse mode for the new caption.
caption_entities – Special entities for the new caption.
show_caption_above_media – Pass True, if the caption must be shown above the message media.
video_start_timestamp – New start timestamp for the copied video in seconds.
disable_notification – Send the copy silently.
protect_content – Protect the copied content.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the copied message; dict or to_dict object.

Returns:

A MessageId carrying the identifier of the copied message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Forward a message of any kind to another chat.

Example

>>> msg = await bot.forward_message(target_chat, source_chat, 123)

Parameters:

chat_id – Unique identifier for the destination chat.
from_chat_id – Chat where the original message was sent.
message_id – Message identifier in from_chat_id.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
video_start_timestamp – New start timestamp for the forwarded video in seconds.
disable_notification – Forward silently.
protect_content – Protect the forwarded content.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.

Returns:

The forwarded Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_user_personal_chat_messages(user_id: int, limit: int) → list[Message]¶

Get the last messages from the personal chat of a user.

Remarks:: The user is identified by user_id, not by the identifier of their personal chat. limit is required and must be 1-20.

Example

>>> messages = await bot.get_user_personal_chat_messages(42, 10)

Parameters:

user_id – Unique identifier of the target user.
limit – Maximum number of messages to return; 1-20.

Returns:

The messages of the personal chat, oldest first.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async send_chat_action(chat_id: int | str, action: str, *, business_connection_id: str | None = None, message_thread_id: int | None = None) → bool¶

Broadcast a chat action (typing, upload_photo, …) to the chat.

Example

>>> await bot.send_chat_action(123456, "typing")

Parameters:

chat_id – Unique identifier for the target chat or channel username.
action – Type of action to broadcast, e.g. typing, upload_photo, find_location.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a text message to a chat.

Example

>>> msg = await bot.send_message(123456, "Hello!", parse_mode="Markdown")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel (e.g. @channelusername).
text – Text of the message to be sent, 1-4096 characters.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread (topic) of a forum supergroup.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
parse_mode – Parse mode for text entities (HTML, Markdown, MarkdownV2).
entities – Special entities that appear in the text, as an alternative to parse_mode.
link_preview_options – Link preview generation options, as a LinkPreviewOptions object or a mapping.
disable_notification – Send silently; users get a notification with no sound.
protect_content – Protect the message content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Inline keyboard, custom reply keyboard, remove-keyboard instruction, or force-reply instruction; a plain dict or any object with to_dict.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.mini_apps¶

Mini App guest-query and join-request Bot API methods.

Ported from node client/methods/business/stories-boosts.ts (answerGuestQuery), client/methods/business/ephemeral.ts (sendChatJoinRequestWebApp, answerChatJoinRequestQuery), and client/methods/business/gifts.ts (savePreparedKeyboardButton).

class telebot_py.bot.mini_apps.MiniAppsMixin¶

Bases: Requester

Bot methods for replying to Mini App and join-request queries.

async answer_chat_join_request_query(chat_join_request_query_id: str, result: str) → bool¶

Process a received chat join request query.

Remarks:: Completes the flow started by send_chat_join_request_web_app: result must be one of the three values Telegram documents, approve to let the user join, decline to disallow it, or queue to leave the decision to other administrators.

Example

>>> ok = await bot.answer_chat_join_request_query("join-1", "approve")

Parameters:

chat_join_request_query_id – Unique identifier of the join request query to be answered.
result – Result of the query: approve, decline, or queue.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async answer_guest_query(guest_query_id: str, result: Mapping[str, object] | SupportsToDict) → SentGuestMessage¶

Reply to a received guest message from a mini app.

Remarks:: result is an InlineQueryResult object describing the message to send; the JSON-only client takes it as a dict or to_dict object rather than modelling every inline result type.

Example

>>> sent = await bot.answer_guest_query(
...     "guest-1",
...     {
...         "type": "article",
...         "id": "art_1",
...         "title": "Result",
...         "input_message_content": {"message_text": "Hello"},
...     },
... )

Parameters:

guest_query_id – Unique identifier for the query to be answered.
result – InlineQueryResult describing the message to be sent.

Returns:

The SentGuestMessage carrying the sent inline message identifier.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async save_prepared_keyboard_button(user_id: int, button: Mapping[str, object] | SupportsToDict) → PreparedKeyboardButton¶

Store a keyboard button a user of a Mini App can send later.

Remarks:: button must be a KeyboardButton of the type request_users, request_chat, or request_managed_bot.

Example

>>> prepared = await bot.save_prepared_keyboard_button(
...     42,
...     {"text": "Share team", "request_users": {"user_is_bot": True}},
... )

Parameters:

user_id – Unique identifier of the target user that can use the button.
button – KeyboardButton as a to_dict object or a plain dict describing the button to save.

Returns:

The PreparedKeyboardButton carrying the stored button identifier.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async send_chat_join_request_web_app(chat_join_request_query_id: str, web_app_url: str) → bool¶

Show a Mini App to a user before they decide on a join request.

Remarks:: Resolve the join request itself with Telegram’s answerChatJoinRequestQuery once the user interacts with the Mini App.

Example

>>> ok = await bot.send_chat_join_request_web_app(
...     "join-1", "https://example.com/app?start=abc"
... )

Parameters:

chat_join_request_query_id – Unique identifier of the join request query.
web_app_url – An HTTPS URL of the Web App to open, as specified in “Initializing Web Apps”.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.owned_gifts¶

Owned-gift listing Bot API methods.

Ported from node client/methods/business/gifts.ts (getBusinessAccountGifts, getUserGifts, getChatGifts). Node passes the listing filters through an untyped options object; python spells them out as keyword arguments so mypy --strict and the generated docs stay useful.

class telebot_py.bot.owned_gifts.OwnedGiftsMixin¶

Bases: Requester

Bot methods for listing gifts owned by users, chats, and accounts.

async get_business_account_gifts(business_connection_id: str, *, exclude_unsaved: bool | None = None, exclude_saved: bool | None = None, exclude_unlimited: bool | None = None, exclude_limited_upgradable: bool | None = None, exclude_limited_non_upgradable: bool | None = None, exclude_unique: bool | None = None, exclude_from_blockchain: bool | None = None, sort_by_price: bool | None = None, offset: str | None = None, limit: int | None = None) → OwnedGifts¶

Get gifts received and not yet refunded by a business account.

Example

>>> gifts = await bot.get_business_account_gifts("bc1", limit=10)
>>> print(gifts.total_count)

Parameters:

business_connection_id – Unique identifier of the business connection.
exclude_unsaved – Omit gifts saved by the recipient.
exclude_saved – Omit gifts not saved by the recipient.
exclude_unlimited – Omit unlimited gifts.
exclude_limited_upgradable – Omit limited gifts upgradable to unique.
exclude_limited_non_upgradable – Omit limited gifts not upgradable to unique.
exclude_unique – Omit unique gifts.
exclude_from_blockchain – Omit gifts and collectibles minted on the blockchain.
sort_by_price – Sort the results based on the price.
offset – Sequential offset of the first number to return.
limit – Maximum number of gifts to return; 1-100.

Returns:

The OwnedGifts page for the business account.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Get gifts owned by a chat that were sent by other users or bots.

Example

>>> gifts = await bot.get_chat_gifts(-1001234567890, offset="20")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
exclude_unsaved – Omit gifts that aren’t saved to the chat’s profile page. Always True unless the bot has the can_post_messages administrator right in the channel.
exclude_saved – Omit gifts that are saved to the chat’s profile page. Always False unless the bot has the can_post_messages administrator right in the channel.
exclude_unlimited – Omit unlimited gifts.
exclude_limited_upgradable – Omit limited gifts upgradable to unique.
exclude_limited_non_upgradable – Omit limited gifts not upgradable to unique.
exclude_unique – Omit unique gifts.
exclude_from_blockchain – Omit gifts and collectibles minted on the blockchain.
sort_by_price – Sort the results based on the price.
offset – Sequential offset of the first number to return.
limit – Maximum number of gifts to return; 1-100.

Returns:

The OwnedGifts page for the chat.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Get gifts owned by a user that were sent by other users or bots.

Example

>>> gifts = await bot.get_user_gifts(123, exclude_unique=True)

Parameters:

user_id – Unique identifier of the target user.
exclude_unlimited – Omit unlimited gifts.
exclude_limited_upgradable – Omit limited gifts upgradable to unique.
exclude_limited_non_upgradable – Omit limited gifts not upgradable to unique.
exclude_unique – Omit unique gifts.
exclude_from_blockchain – Omit gifts and collectibles minted on the blockchain.
sort_by_price – Sort the results based on the price.
offset – Sequential offset of the first number to return.
limit – Maximum number of gifts to return; 1-100.

Returns:

The OwnedGifts page for the user.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.paid_media¶

Paid media and live photo Bot API methods.

Ported from node client/methods/messages/send-media.ts (sendPaidMedia, sendLivePhoto).

class telebot_py.bot.paid_media.PaidMediaMixin¶

Bases: Requester

Bot methods for sending paid media and live photos.

Send a live photo (a short video plus its static photo).

Remarks:: live_photo and photo are file_id references to already uploaded files; the video must be no longer than 10 seconds and must not exceed 10 MB. Sending live photos by a URL is unsupported.

Example

>>> message = await bot.send_live_photo(123, "video-file-id", "photo-file-id")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
live_photo – Live photo video to send.
photo – The static photo to send.
caption – Live photo caption, 0-1024 characters after entities parsing.
parse_mode – Mode for parsing entities in the caption.
caption_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of parse_mode.
show_caption_above_media – Whether the caption must be shown above the message media.
has_spoiler – Whether the photo is covered by a spoiler animation.
disable_notification – Sends the message silently.
protect_content – Protects the contents from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – ReplyParameters object describing the message to reply to.
reply_markup – InlineKeyboardMarkup for the message.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier of the target message thread (topic) of a forum.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send paid media that users unlock by paying Telegram Stars.

Remarks:: media holds InputPaidMedia objects (InputPaidMediaPhoto / InputPaidMediaVideo instances or plain dicts), up to 10 items. Sending media groups with 2-10 items requires all items to share a type; the JSON-only client can’t attach new files, so pass a file_id or an HTTP URL.

Example

>>> from telebot_py.types import InputPaidMediaPhoto
>>> message = await bot.send_paid_media(
...     123, 50, [InputPaidMediaPhoto(type="photo", media="file-id-1")]
... )

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
star_count – Number of Telegram Stars that must be paid to buy access to the media; 1-25000.
media – InputPaidMedia items describing the media to send; up to 10 items.
payload – Bot-defined paid media payload, 0-128 bytes, not shown to the user.
caption – Media caption, 0-1024 characters after entities parsing.
parse_mode – Mode for parsing entities in the media caption.
caption_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of parse_mode.
show_caption_above_media – Whether the caption must be shown above the message media.
disable_notification – Sends the message silently.
protect_content – Protects the contents from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – ReplyParameters object describing the message to reply to.
reply_markup – InlineKeyboardMarkup for the message.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier of the target message thread (topic) of a forum.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.payments¶

Payment Bot API methods (parity with packages/go/pkg/bot/payments.go).

class telebot_py.bot.payments.PaymentsMixin¶

Bases: Requester

Bot methods for invoices, checkout queries, and Telegram Stars.

async answer_pre_checkout_query(pre_checkout_query_id: str, ok: bool, *, error_message: str | None = None) → bool¶

Answer a pre-checkout query.

Example

>>> await bot.answer_pre_checkout_query("pcq1", False, error_message="out of stock")

Parameters:

pre_checkout_query_id – Unique identifier of the pre-checkout query.
ok – Whether the order can proceed to checkout.
error_message – Reason checkout is impossible (required when ok is False).

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async answer_shipping_query(shipping_query_id: str, ok: bool, *, shipping_options: Sequence[Mapping[str, object] | SupportsToDict] | None = None, error_message: str | None = None) → bool¶

Answer a shipping query.

Example

>>> await bot.answer_shipping_query("sq1", True, shipping_options=options)

Parameters:

shipping_query_id – Unique identifier of the shipping query.
ok – Whether delivery to the specified address is possible.
shipping_options – ShippingOption items (required when ok is True).
error_message – Reason shipping is impossible (required when ok is False).

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async create_invoice_link(title: str, description: str, payload: str, currency: str, prices: Sequence[Mapping[str, object] | SupportsToDict], *, business_connection_id: str | None = None, provider_token: str | None = None, subscription_period: int | None = None, max_tip_amount: int | None = None, suggested_tip_amounts: Sequence[int] | None = None, provider_data: str | None = None, photo_url: str | None = None, photo_size: int | None = None, photo_width: int | None = None, photo_height: int | None = None, need_name: bool | None = None, need_phone_number: bool | None = None, need_email: bool | None = None, need_shipping_address: bool | None = None, send_phone_number_to_provider: bool | None = None, send_email_to_provider: bool | None = None, is_flexible: bool | None = None) → str¶

Create a link for an invoice.

Example

>>> link = await bot.create_invoice_link(
...     "Coffee", "A fine coffee", "order-1", "XTR", prices
... )

Parameters:

title – Product name, 1-32 characters.
description – Product description, 1-255 characters.
payload – Bot-defined invoice payload, 1-128 bytes.
currency – Three-letter ISO 4217 currency code, or XTR.
prices – LabeledPrice items as dicts or to_dict objects.
business_connection_id – Unique identifier of the business connection on behalf of which the message with the invoice will be sent.
provider_token – Payment provider token (omit for Telegram Stars).
subscription_period – Subscription period in seconds for recurring payments.
max_tip_amount – Maximum accepted tip amount.
suggested_tip_amounts – Suggested tip amounts in ascending order.
provider_data – JSON-serialized data about the invoice for the provider.
photo_url – URL of the product photo.
photo_size – Photo size in bytes.
photo_width – Photo width.
photo_height – Photo height.
need_name – Require the user’s full name.
need_phone_number – Require the user’s phone number.
need_email – Require the user’s email.
need_shipping_address – Require the user’s shipping address.
send_phone_number_to_provider – Share the phone number with the provider.
send_email_to_provider – Share the email with the provider.
is_flexible – Whether the final price depends on the shipping method.

Returns:

The created invoice link.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_user_star_subscription(user_id: int, telegram_payment_charge_id: str, is_canceled: bool) → bool¶

Cancel or restore a Telegram Stars subscription.

Example

>>> ok = await bot.edit_user_star_subscription(1, "charge-1", True)

Parameters:

user_id – Identifier of the user whose subscription will be edited.
telegram_payment_charge_id – Telegram payment identifier for the subscription.
is_canceled – Whether the subscription must be canceled.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_star_balance() → StarAmount¶

Get the current amount of Telegram Stars owned by the bot.

Example

>>> balance = await bot.get_my_star_balance()
>>> print(balance.amount)

Returns:

The StarAmount held by the bot.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_star_transactions(*, offset: int | None = None, limit: int | None = None) → StarTransactions¶

Get the bot’s Telegram Stars transactions.

Example

>>> transactions = await bot.get_star_transactions(limit=10)

Parameters:

offset – Number of transactions to skip.
limit – Maximum number of transactions to retrieve; 1-100.

Returns:

The StarTransactions list.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async refund_star_payment(user_id: int, telegram_payment_charge_id: str) → bool¶

Refund a Telegram Stars payment.

Example

>>> ok = await bot.refund_star_payment(1, "charge-1")

Parameters:

user_id – Identifier of the user whose payment will be refunded.
telegram_payment_charge_id – Telegram payment identifier.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send an invoice.

Example

>>> msg = await bot.send_invoice(1, "Coffee", "A fine coffee", "order-1", "XTR", prices)

Parameters:

chat_id – Unique identifier for the target chat or channel username.
title – Product name, 1-32 characters.
description – Product description, 1-255 characters.
payload – Bot-defined invoice payload, 1-128 bytes.
currency – Three-letter ISO 4217 currency code, or XTR.
prices – LabeledPrice items as dicts or to_dict objects.
provider_token – Payment provider token (omit for Telegram Stars).
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
max_tip_amount – Maximum accepted tip amount.
suggested_tip_amounts – Suggested tip amounts in ascending order; at most 4 items.
start_parameter – Deep-linking parameter for /start.
provider_data – JSON-serialized data about the invoice for the provider.
photo_url – URL of the product photo.
photo_size – Photo size in bytes.
photo_width – Photo width.
photo_height – Photo height.
need_name – Require the user’s full name.
need_phone_number – Require the user’s phone number.
need_email – Require the user’s email.
need_shipping_address – Require the user’s shipping address.
send_phone_number_to_provider – Share the phone number with the provider.
send_email_to_provider – Share the email with the provider.
is_flexible – Whether the final price depends on the shipping method.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Inline keyboard for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.profile¶

Bot profile Bot API methods (parity with packages/go/pkg/bot/profile.go).

class telebot_py.bot.profile.ProfileMixin¶

Bases: Requester

Bot methods for the bot’s own name, descriptions, commands, photo, and lifecycle.

async close() → bool¶

Close the bot instance before moving it to another local server.

Example

>>> ok = await bot.close()

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_my_commands(*, scope: Mapping[str, object] | SupportsToDict | None = None, language_code: str | None = None) → bool¶

Delete the list of the bot’s commands for the given scope.

Example

>>> ok = await bot.delete_my_commands()

Parameters:

scope – BotCommandScope limiting where the commands apply.
language_code – User language whose commands to delete.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_commands(*, scope: Mapping[str, object] | SupportsToDict | None = None, language_code: str | None = None) → list[BotCommand]¶

Get the current list of the bot’s commands.

Example

>>> commands = await bot.get_my_commands()

Parameters:

scope – BotCommandScope limiting where the commands apply.
language_code – User language whose commands to return.

Returns:

The BotCommand list.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_description(*, language_code: str | None = None) → BotDescription¶

Get the bot’s description in the given language.

Example

>>> description = await bot.get_my_description(language_code="en")

Parameters:

language_code – User language whose description to return.

Returns:

The BotDescription.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_name(*, language_code: str | None = None) → BotName¶

Get the bot’s name in the given language.

Example

>>> name = await bot.get_my_name(language_code="en")

Parameters:

language_code – User language whose name to return.

Returns:

The BotName.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_my_short_description(*, language_code: str | None = None) → BotShortDescription¶

Get the bot’s short description in the given language.

Example

>>> short = await bot.get_my_short_description(language_code="en")

Parameters:

language_code – User language whose short description to return.

Returns:

The BotShortDescription.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_user_profile_audios(user_id: int, offset: int | None = None, limit: int | None = None) → UserProfileAudios¶

Get the list of audios displayed on a user’s profile.

Example

>>> audios = await bot.get_user_profile_audios(42, 0, 10)
>>> print(audios.total_count)

Parameters:

user_id – Unique identifier of the target user.
offset – Sequential number of the first audio to be returned; omit to return all audios.
limit – Maximum number of audios to retrieve, 1-100; defaults to 100.

Returns:

The UserProfileAudios object carrying the requested audios.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async log_out() → bool¶

Log out from the cloud Bot API server before switching local servers.

Example

>>> ok = await bot.log_out()

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async remove_my_profile_photo() → bool¶

Delete the bot’s profile photo.

Example

>>> ok = await bot.remove_my_profile_photo()

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_commands(commands: Sequence[Mapping[str, object] | SupportsToDict], *, scope: Mapping[str, object] | SupportsToDict | None = None, language_code: str | None = None) → bool¶

Change the list of the bot’s commands.

Example

>>> ok = await bot.set_my_commands([{"command": "start", "description": "Begin"}])

Parameters:

commands – New command list; dicts or BotCommand objects.
scope – BotCommandScope limiting where the commands apply.
language_code – User language the commands apply to.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_description(description: str | _Unset = UNSET, *, language_code: str | None = None) → bool¶

Change the bot’s description shown on its profile page.

Example

>>> ok = await bot.set_my_description("A helpful bot")

Parameters:

description – New bot description; 0-512 characters. Omit the parameter to leave it untouched; pass an empty string to remove the dedicated description for the given language.
language_code – User language the description applies to.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_name(*, name: str | None = None, language_code: str | None = None) → bool¶

Change the bot’s name.

Example

>>> ok = await bot.set_my_name(name="Helper", language_code="en")

Parameters:

name – New bot name; 0-64 characters. Omit to remove the name.
language_code – User language the name applies to.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_profile_photo(photo: str) → bool¶

Set a new profile photo for the bot.

Accepts a file_id string or a URL; multipart uploads are intentionally out of scope (JSON payloads only).

Example

>>> ok = await bot.set_my_profile_photo("photo_file_id")

Parameters:

photo – New bot profile photo as a file_id or URL.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_my_short_description(short_description: str | _Unset = UNSET, *, language_code: str | None = None) → bool¶

Change the bot’s short description shown in chats.

Example

>>> ok = await bot.set_my_short_description("Say hi!")

Parameters:

short_description – New short description; 0-120 characters. Omit the parameter to leave it untouched; pass an empty string to remove the dedicated short description for the given language.
language_code – User language the short description applies to.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.reactions¶

Reaction Bot API methods (parity with packages/go/pkg/bot/reactions.go).

class telebot_py.bot.reactions.ReactionsMixin¶

Bases: Requester

Bot methods for setting and removing message reactions.

async delete_all_message_reactions(chat_id: int | str, *, user_id: int | None = None, actor_chat_id: int | None = None) → bool¶

Remove up to 10000 recent reactions in a chat added by a given user or chat.

Remarks:: The bot must have the can_delete_messages administrator right in the chat. Unlike delete_message_reaction this endpoint targets a sender across the whole chat and takes no message_id.

Example

>>> ok = await bot.delete_all_message_reactions("@supergroup", user_id=42)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
user_id – Identifier of the user whose reactions will be removed, if the reactions were added by a user.
actor_chat_id – Identifier of the chat whose reactions will be removed, if the reactions were added by a chat.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_message_reaction(chat_id: int | str, message_id: int, *, user_id: int | None = None, actor_chat_id: int | None = None) → bool¶

Remove a reaction from a message in a group or a supergroup chat.

Remarks:: The bot must have the can_delete_messages administrator right in the chat. Omit both user_id and actor_chat_id to remove the bot’s own reaction; pass user_id for a reaction added by a user and actor_chat_id for one added by a chat.

Example

>>> ok = await bot.delete_message_reaction(1, 7)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_id – Identifier of the target message.
user_id – Identifier of the user whose reaction will be removed, if the reaction was added by a user.
actor_chat_id – Identifier of the chat whose reaction will be removed, if the reaction was added by a chat.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Change the chosen reactions on a message.

A single reaction dict is normalized to a one-element list. Omitting reaction removes the currently set one; to remove reactions added by other users or chats use delete_message_reaction.

Example

>>> ok = await bot.set_message_reaction(1, 7, [{"type": "emoji", "emoji": "👍"}])

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
message_id – Identifier of the target message.
reaction – New list of reactions; a single reaction is also accepted. Omit to remove the currently set reaction.
is_big – Pass True to set the reaction with a big animation.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.retry¶

Retry policy for Bot API requests (FR-012).

class telebot_py.bot.retry.RetryPolicy(max_retries: int = 3, base_delay: float = 1.0, max_delay: float = 30.0)¶

Bases: object

Exponential-backoff retry configuration for Bot API requests.

Retries fire only on HTTP 429, 5xx responses, and transport failures; every other 4xx response fails immediately.

Variables:

max_retries (int) – Number of retries after the initial attempt.
base_delay (float) – First backoff delay in seconds; each further delay doubles.
max_delay (float) – Upper bound in seconds for any single backoff delay.

base_delay: float¶

delay_for(attempt: int, retry_after: float | None = None) → float¶

Backoff delay to wait before retry number attempt.

Parameters:

attempt – 1-based retry index (1 = delay before the first retry).
retry_after – Telegram’s flood-control hint, for 429 responses.

Returns:

The larger of the exponential step (1s, 2s, 4s, 8s, … capped at max_delay) and retry_after when provided.

is_retryable_status(status_code: int) → bool¶

Whether an HTTP status code should be retried.

Parameters:: status_code – The HTTP status code returned by Telegram.
Returns:: True for 429, 500, 502, 503, or 504; False otherwise.

max_delay: float¶

max_retries: int¶

telebot_py.bot.stickers¶

Sticker Bot API methods (parity with packages/go/pkg/bot/stickers.go).

class telebot_py.bot.stickers.StickersMixin¶

Bases: Requester

Bot methods for sending stickers and fetching forum topic icon stickers.

Sticker parameters accept file_id strings or attach:// references; multipart file uploads are intentionally out of scope (JSON payloads only).

async get_forum_topic_icon_stickers() → list[Sticker]¶

Get the custom emoji stickers usable as forum topic icons.

Example

>>> stickers = await bot.get_forum_topic_icon_stickers()

Returns:

The available forum topic icon Stickers.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Send a static, animated, or video sticker.

Example

>>> msg = await bot.send_sticker(123456, "sticker-file-id", emoji="😀")

Parameters:

chat_id – Unique identifier for the target chat or channel username.
sticker – Sticker to send as a file_id string.
business_connection_id – Unique identifier of the business connection on behalf of which the message will be sent.
message_thread_id – Unique identifier for the target message thread.
direct_messages_topic_id – Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat.
ephemeral_message_parameters – EphemeralMessageParameters as a to_dict object or dict.
emoji – Emoji associated with the sticker.
disable_notification – Send silently.
protect_content – Protect the content from forwarding and saving.
allow_paid_broadcast – Pass True to ignore broadcasting limits for a fee of 0.1 Telegram Stars per message.
message_effect_id – Unique identifier of the message effect to add.
suggested_post_parameters – SuggestedPostParameters as a to_dict object or dict; for direct messages chats only.
reply_parameters – Description of the message to reply to, as a ReplyParameters object or a mapping.
reply_markup – Markup for the message; dict or to_dict object.

Returns:

The sent Message.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.stories¶

Story management and suggested-post Bot API methods.

Ported from node client/methods/business/stories-boosts.ts (editStory, deleteStory) and client/methods/business/gifts.ts (repostStory, approveSuggestedPost, declineSuggestedPost). Posting stories lives in telebot_py.bot.stories_gifts.

class telebot_py.bot.stories.StoriesMixin¶

Bases: Requester

Bot methods for editing business-account stories and suggested posts.

async approve_suggested_post(chat_id: int | str, message_id: int, *, send_date: int | None = None) → bool¶

Approve a suggested post in a direct messages chat.

Remarks:: The bot needs the can_post_messages administrator right in the corresponding channel chat. send_date may only be supplied when the suggested post didn’t already carry one, and must be at most 30 days in the future.

Example

>>> ok = await bot.approve_suggested_post(-1001234, 55)

Parameters:

chat_id – Unique identifier of the target direct messages chat.
message_id – Identifier of the suggested post message to approve.
send_date – Point in time (Unix timestamp) when the post is expected to be published.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async decline_suggested_post(chat_id: int | str, message_id: int, *, comment: str | None = None) → bool¶

Decline a suggested post in a direct messages chat.

Remarks:: The bot needs the can_manage_direct_messages administrator right in the corresponding channel chat.

Example

>>> ok = await bot.decline_suggested_post(-1001234, 55, comment="Not now")

Parameters:

chat_id – Unique identifier of the target direct messages chat.
message_id – Identifier of the suggested post message to decline.
comment – Comment shown to the creator of the suggested post; 0-128 characters.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_story(business_connection_id: str, story_id: int) → bool¶

Delete a story previously posted on behalf of a connected business account.

Remarks:: Requires the can_manage_stories business bot right.

Example

>>> ok = await bot.delete_story("bc1", 7)

Parameters:

business_connection_id – Unique identifier of the business connection.
story_id – Unique identifier of the story to delete.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Edit a story previously posted by the bot on behalf of a business account.

Remarks:: Requires the can_manage_stories business bot right. content must be an InputStoryContent object (StoryArea / InputStoryContentPhoto / InputStoryContentVideo instances or plain dicts); areas carries the clickable overlays.

Example

>>> story = await bot.edit_story(
...     "bc1", 7, {"type": "photo", "photo": "attach://photo"}
... )

Parameters:

business_connection_id – Unique identifier of the business connection.
story_id – Unique identifier of the story to edit.
content – New content of the story.
caption – New caption of the story; 0-2048 characters after entity parsing.
parse_mode – Mode for parsing entities in the story caption.
caption_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of parse_mode.
areas – StoryArea items as to_dict objects or dicts describing the clickable areas of the story.

Returns:

The edited Story.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async repost_story(business_connection_id: str, from_chat_id: int, from_story_id: int, active_period: int, *, post_to_chat_page: bool | None = None, protect_content: bool | None = None) → Story¶

Repost a story from one managed business account to another.

Remarks:: Both business accounts must be managed by the same bot, and the source story must have been posted (or reposted) by the bot. active_period must be one of 21600, 43200, 86400, or 172800.

Example

>>> story = await bot.repost_story("bc1", 200, 9, 86400)

Parameters:

business_connection_id – Unique identifier of the business connection owning the reposted story.
from_chat_id – Unique identifier of the chat that posted the source story.
from_story_id – Unique identifier of the source story.
active_period – Seconds after which the story moves to the archive.
post_to_chat_page – Whether the story stays accessible on the chat page after it expires.
protect_content – Whether the story content is protected from forwarding and screenshotting.

Returns:

The reposted Story.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.stories_gifts¶

Story/gift Bot API methods (parity with packages/go/pkg/bot/stories_gifts.go).

class telebot_py.bot.stories_gifts.StoriesGiftsMixin¶

Bases: Requester

Bot methods for business-account stories, gifts, and user emoji status.

Post a story on behalf of a managed business account.

Remarks:: Requires the can_manage_stories business bot right. areas takes StoryArea objects or plain dicts.

Example

>>> story = await bot.post_story("bc1", {"type": "photo"}, 86400, caption="Hi")

Parameters:

business_connection_id – Unique identifier of the business connection.
content – Story content as an InputStoryContent dict (e.g. {"type": "photo", ...}).
active_period – Seconds after which the story is moved to the archive; must be one of 21600, 43200, 86400, or 172800.
caption – Story caption; 0-2048 characters after entities parsing.
parse_mode – Mode for parsing entities in the story caption.
caption_entities – MessageEntity items as to_dict objects or dicts; can be specified instead of parse_mode.
areas – StoryArea items as to_dict objects or dicts describing clickable areas shown on the story.
post_to_chat_page – Pass True to keep the story accessible after it expires.
protect_content – Pass True if the content of the story must be protected from forwarding and screenshotting.

Returns:

The posted Story.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async set_user_emoji_status(user_id: int, emoji_status_custom_emoji_id: str | None = None, *, emoji_status_expiration_date: int | None = None) → bool¶

Change the emoji status of a user who allowed the bot to do so.

Remarks:: The user must previously have allowed the bot to manage their emoji status via the Mini App method requestEmojiStatusAccess. Pass an empty string as emoji_status_custom_emoji_id to remove the status.

Example

>>> ok = await bot.set_user_emoji_status(42, "custom-emoji-id")

Parameters:

user_id – Unique identifier of the target user.
emoji_status_custom_emoji_id – Custom emoji identifier of the emoji status to set. Pass an empty string to remove the status.
emoji_status_expiration_date – Point in time (Unix timestamp) when the emoji status will be cleared.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.topics¶

Forum topic Bot API methods (parity with packages/go/pkg/bot/topics.go).

class telebot_py.bot.topics.TopicsMixin¶

Bases: Requester

Bot methods for creating and closing forum topics.

async close_forum_topic(chat_id: int | str, message_thread_id: int) → bool¶

Close an open topic in a forum supergroup chat.

Example

>>> ok = await bot.close_forum_topic(-100, 4)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_thread_id – Unique identifier of the target message thread.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async close_general_forum_topic(chat_id: int | str) → bool¶

Close an open ‘General’ topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right.

Example

>>> ok = await bot.close_general_forum_topic(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async create_forum_topic(chat_id: int | str, name: str, *, icon_color: int | None = None, icon_custom_emoji_id: str | None = None) → ForumTopic¶

Create a topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right.

Example

>>> topic = await bot.create_forum_topic(-100, "General")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
name – Topic name; 1-128 characters.
icon_color – Color of the topic icon in RGB format.
icon_custom_emoji_id – Unique identifier of the custom emoji shown as the topic icon.

Returns:

The created ForumTopic.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async delete_forum_topic(chat_id: int | str, message_thread_id: int) → bool¶

Delete a forum topic along with all its messages.

The bot must have the can_manage_topics administrator right, unless it is the creator of the topic. Implies closing the topic first.

Example

>>> ok = await bot.delete_forum_topic(-100, 4)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_thread_id – Unique identifier of the target message thread of the forum topic.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_forum_topic(chat_id: int | str, message_thread_id: int, *, name: str | None = None, icon_custom_emoji_id: str | None = None) → bool¶

Edit the name and icon of a topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right, unless it is the creator of the topic.

Example

>>> ok = await bot.edit_forum_topic(-100, 4, name="Announcements")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_thread_id – Unique identifier of the target message thread of the forum topic; must be positive.
name – New topic name; 1-128 characters.
icon_custom_emoji_id – New unique identifier of the custom emoji shown as the topic icon.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async edit_general_forum_topic(chat_id: int | str, name: str) → bool¶

Edit the name of the ‘General’ topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right. The name of the ‘General’ topic can never be empty.

Example

>>> ok = await bot.edit_general_forum_topic(-100, "General Chat")

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
name – New topic name; 1-128 characters.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async hide_general_forum_topic(chat_id: int | str) → bool¶

Hide the ‘General’ topic in a forum supergroup chat.

The bot must be a member of the group with the can_manage_topics administrator right. The ‘General’ topic is automatically unhidden when the chat is opened by other members.

Example

>>> ok = await bot.hide_general_forum_topic(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async reopen_forum_topic(chat_id: int | str, message_thread_id: int) → bool¶

Reopen a closed topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right, unless it is the creator of the topic.

Example

>>> ok = await bot.reopen_forum_topic(-100, 4)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_thread_id – Unique identifier of the target message thread of the forum topic.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async reopen_general_forum_topic(chat_id: int | str) → bool¶

Reopen a closed ‘General’ topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right.

Example

>>> ok = await bot.reopen_general_forum_topic(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unhide_general_forum_topic(chat_id: int | str) → bool¶

Unhide the ‘General’ topic in a forum supergroup chat.

The bot must have the can_manage_topics administrator right.

Example

>>> ok = await bot.unhide_general_forum_topic(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unpin_all_forum_topic_messages(chat_id: int | str, message_thread_id: int) → bool¶

Clear the list of pinned messages in a forum topic.

The bot must have the can_pin_messages administrator right in the topic to do this.

Example

>>> ok = await bot.unpin_all_forum_topic_messages(-100, 4)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.
message_thread_id – Unique identifier of the target message thread of the forum topic.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async unpin_all_general_forum_topic_messages(chat_id: int | str) → bool¶

Clear the list of pinned messages in a ‘General’ forum topic.

The bot must have the can_pin_messages administrator right in the supergroup to do this.

Example

>>> ok = await bot.unpin_all_general_forum_topic_messages(-100)

Parameters:

chat_id – Unique identifier for the target chat or username of the target supergroup.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.verification¶

Organizational verification Bot API methods.

Ported from node client/methods/chats/management.ts (verifyUser, verifyChat, removeUserVerification, removeChatVerification).

class telebot_py.bot.verification.VerificationMixin¶

Bases: Requester

Bot methods for verifying users and chats on behalf of the owner.

async remove_chat_verification(chat_id: int | str) → bool¶

Remove verification from a chat previously verified by this organization.

Example

>>> ok = await bot.remove_chat_verification("@my_channel")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async remove_user_verification(user_id: int) → bool¶

Remove verification from a user previously verified by this organization.

Example

>>> ok = await bot.remove_user_verification(42)

Parameters:

user_id – Unique identifier of the target user.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async verify_chat(chat_id: int | str, custom_description: str | None = None) → bool¶

Verify a chat on behalf of the organization which owns the bot.

Example

>>> ok = await bot.verify_chat("@my_channel", "Verified Community")

Parameters:

chat_id – Unique identifier for the target chat or username of the target channel.
custom_description – Custom description for the verification status; 0-70 characters.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async verify_user(user_id: int, custom_description: str | None = None) → bool¶

Verify a user on behalf of the organization which owns the bot.

Only available to bots owned by an organization that has been granted the can_verify_users right.

Example

>>> ok = await bot.verify_user(42, "Official Staff")

Parameters:

user_id – Unique identifier of the target user.
custom_description – Custom description for the verification status; 0-70 characters.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.bot.webhook¶

Webhook configuration Bot API methods (used by the application lifecycle).

class telebot_py.bot.webhook.WebhookMixin¶

Bases: Requester

Bot methods managing webhook delivery of updates.

async delete_webhook(*, drop_pending_updates: bool | None = None) → bool¶

Remove the webhook integration, reverting to getUpdates polling.

Example

>>> await bot.delete_webhook(drop_pending_updates=True)

Parameters:

drop_pending_updates – Discard all undelivered updates on removal.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

async get_webhook_info() → WebhookInfo¶

Get the current webhook status.

Example

>>> info = await bot.get_webhook_info()

Returns:

A WebhookInfo object; its url is empty when no webhook is set.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

Configure a URL to receive incoming updates via an outgoing webhook.

Example

>>> await bot.set_webhook("https://example.com/hook", secret_token="s3cret")

Parameters:

url – HTTPS URL Telegram posts updates to.
certificate – Upload your public key certificate so that the root certificate in use can be checked.
ip_address – The fixed IP address which will be used to send webhook requests instead of the IP address resolved through DNS.
secret_token – Sent back in the X-Telegram-Bot-Api-Secret-Token header of every delivery so the endpoint can verify origin.
max_connections – Maximum simultaneous connections for deliveries.
allowed_updates – Update types to receive; defaults to all except chat_member.
drop_pending_updates – Discard all undelivered updates on switch.

Returns:

True on success.

Raises:

InvalidTokenError – If Telegram rejects the token (HTTP 401).
TelegramApiError – If Telegram responds not-ok or retries exhaust.
NetworkError – If the transport keeps failing after retries.

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

telebot_py.ext_errors¶

Top-level re-export of the public error types. The classes themselves are documented under telebot_py.bot.errors.

Top-level error exports (contracts/public-api.md section 1 and 9).

telebot_py.bot¶

telebot_py.bot.base¶

telebot_py.bot.bulk¶

telebot_py.bot.business_account¶

telebot_py.bot.chat_management¶

telebot_py.bot.chats¶

telebot_py.bot.checklists¶

telebot_py.bot.client¶

telebot_py.bot.edits¶

telebot_py.bot.ephemeral¶

telebot_py.bot.errors¶

telebot_py.bot.files¶

telebot_py.bot.games¶

telebot_py.bot.gifts¶

telebot_py.bot.inline¶

telebot_py.bot.invite_links¶

telebot_py.bot.media¶

telebot_py.bot.members¶

telebot_py.bot.messages¶

telebot_py.bot.mini_apps¶

telebot_py.bot.owned_gifts¶

telebot_py.bot.paid_media¶

telebot_py.bot.payments¶

telebot_py.bot.profile¶

telebot_py.bot.reactions¶

telebot_py.bot.retry¶

telebot_py.bot.stickers¶

telebot_py.bot.stories¶

telebot_py.bot.stories_gifts¶

telebot_py.bot.topics¶

telebot_py.bot.verification¶

telebot_py.bot.webhook¶

telebot_py.ext_errors¶

telebot-py

Navigation

Related Topics