pyTelegramBotAPI

Release 4.25.0

coder2020official

Jan 03, 2025

CONTENTS

1 TeleBot 1
1.1 Chats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Some features: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Indices and tables 323

Python Module Index 325

Index 327

i
ii
CHAPTER

ONE

TELEBOT

TeleBot is synchronous and asynchronous implementation of Telegram Bot API.

1.1 Chats
English chat: Private chat
Russian chat: @pytelegrambotapi_talks_ru
News: @pyTelegramBotAPI
Pypi: Pypi
Source: Github repository

1.2 Some features:

Easy to learn and use.
Easy to understand.
Both sync and async.
Examples on features.
States
And more. . .

1.3 Content
1.3.1 Installation Guide
Using PIP

$ pip install pyTelegramBotAPI

Using pipenv

$ pipenv install pyTelegramBotAPI

1
pyTelegramBotAPI, Release 4.25.0

By cloning repository

$ git clone https://github.com/eternnoir/pyTelegramBotAPI.git

$ cd pyTelegramBotAPI
$ python setup.py install

Directly using pip

$ pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git

It is generally recommended to use the first option.

While the API is production-ready, it is still under development and it has regular updates, do not forget to update it
regularly by calling:

$ pip install pytelegrambotapi --upgrade

1.3.2 Quick start

Synchronous TeleBot

#!/usr/bin/python

# This is a simple echo bot using the decorator mechanism.

# It echoes any incoming text messages.

import telebot

API_TOKEN = '<api_token>'

bot = telebot.TeleBot(API_TOKEN)

# Handle '/start' and '/help'

@bot.message_handler(commands=['help', 'start'])
def send_welcome(message):
bot.reply_to(message, """\
Hi there, I am EchoBot.
I am here to echo your kind words back to you. Just say anything nice and I'll say the␣
˓→exact same thing to you!\

""")

# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
@bot.message_handler(func=lambda message: True)
def echo_message(message):
bot.reply_to(message, message.text)

bot.infinity_polling()

2 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Asynchronous TeleBot

#!/usr/bin/python

# This is a simple echo bot using the decorator mechanism.

# It echoes any incoming text messages.
import asyncio

from telebot.async_telebot import AsyncTeleBot

bot = AsyncTeleBot('TOKEN')

# Handle '/start' and '/help'

@bot.message_handler(commands=['help', 'start'])
async def send_welcome(message):
text = 'Hi, I am EchoBot.\nJust write me something and I will repeat it!'
await bot.reply_to(message, text)

# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
@bot.message_handler(func=lambda message: True)
async def echo_message(message):
await bot.reply_to(message, message.text)

asyncio.run(bot.polling())

1.3.3 Types of API

class telebot.types.AffiliateInfo(commission_per_mille, amount, affiliate_user=None,
affiliate_chat=None, nanostar_amount=None, **kwargs)
Bases: JsonDeserializable
Contains information about the affiliate that received a commission via this transaction.
Telegram documentation: https://core.telegram.org/bots/api#affiliateinfo
Parameters
• affiliate_user (User) – Optional. The bot or the user that received an affiliate commis-
sion if it was received by a bot or a user
• affiliate_chat (Chat) – Optional. The chat that received an affiliate commission if it
was received by a chat
• commission_per_mille (int) – The number of Telegram Stars received by the affiliate for
each 1000 Telegram Stars received by the bot from referred users
• amount (int) – Integer amount of Telegram Stars received by the affiliate from the transac-
tion, rounded to 0; can be negative for refunds
• nanostar_amount (int) – Optional. The number of 1/1000000000 shares of Telegram
Stars received by the affiliate; from -999999999 to 999999999; can be negative for refunds
Returns
Instance of the class

1.3. Content 3
pyTelegramBotAPI, Release 4.25.0

Return type
AffiliateInfo
class telebot.types.Animation(file_id, file_unique_id, width=None, height=None, duration=None,
thumbnail=None, file_name=None, mime_type=None, file_size=None,
**kwargs)
Bases: JsonDeserializable
This object represents an animation file (GIF or H.264/MPEG-4 AVC video without sound).
Telegram Documentation: https://core.telegram.org/bots/api#animation
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• width (int) – Video width as defined by sender
• height (int) – Video height as defined by sender
• duration (int) – Duration of the video in seconds as defined by sender
• thumbnail (telebot.types.PhotoSize) – Optional. Animation thumbnail as defined by
sender
• file_name (str) – Optional. Original animation filename as defined by sender
• mime_type (str) – Optional. MIME type of the file as defined by sender
• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.
Returns
Instance of the class
Return type
telebot.types.Animation
property thumb: PhotoSize | None

class telebot.types.Audio(file_id, file_unique_id, duration, performer=None, title=None, file_name=None,

mime_type=None, file_size=None, thumbnail=None, **kwargs)
Bases: JsonDeserializable
This object represents an audio file to be treated as music by the Telegram clients.
Telegram Documentation: https://core.telegram.org/bots/api#audio
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• duration (int) – Duration of the audio in seconds as defined by sender
• performer (str) – Optional. Performer of the audio as defined by sender or by audio tags
• title (str) – Optional. Title of the audio as defined by sender or by audio tags

4 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

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

• mime_type (str) – Optional. MIME type of the file as defined by sender
• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.
• thumbnail (telebot.types.PhotoSize) – Optional. Thumbnail of the album cover to
which the music file belongs
Returns
Instance of the class
Return type
telebot.types.Audio
property thumb: PhotoSize | None

class telebot.types.BackgroundFill
Bases: ABC, JsonDeserializable
This object describes the way a background is filled based on the selected colors. Currently, it can be one
of
BackgroundFillSolid BackgroundFillGradient BackgroundFillFreeformGradient
Telegram documentation: https://core.telegram.org/bots/api#backgroundfill
Returns
Instance of the class
Return type
BackgroundFillSolid or BackgroundFillGradient or
BackgroundFillFreeformGradient
class telebot.types.BackgroundFillFreeformGradient(type, colors, **kwargs)
Bases: BackgroundFill
The background is a freeform gradient that rotates after every message in the chat.
Telegram documentation: https://core.telegram.org/bots/api#backgroundfillfreeformgradient
Parameters
• type (str) – Type of the background fill, always “freeform_gradient”
• colors (list of int) – A list of the 3 or 4 base colors that are used to generate the freeform
gradient in the RGB24 format
Returns
Instance of the class
Return type
BackgroundFillFreeformGradient
class telebot.types.BackgroundFillGradient(type, top_color, bottom_color, rotation_angle, **kwargs)
Bases: BackgroundFill
The background is a gradient fill.
Telegram documentation: https://core.telegram.org/bots/api#backgroundfillgradient
Parameters

1.3. Content 5
pyTelegramBotAPI, Release 4.25.0

• type (str) – Type of the background fill, always “gradient”

• top_color (int) – Top color of the gradient in the RGB24 format
• bottom_color (int) – Bottom color of the gradient in the RGB24 format
• rotation_angle (int) – Clockwise rotation angle of the background fill in degrees; 0-359
Returns
Instance of the class
Return type
BackgroundFillGradient
class telebot.types.BackgroundFillSolid(type, color, **kwargs)
Bases: BackgroundFill
The background is filled using the selected color.
Telegram documentation: https://core.telegram.org/bots/api#backgroundfillsolid
Parameters
• type (str) – Type of the background fill, always “solid”
• color (int) – The color of the background fill in the RGB24 format
Returns
Instance of the class
Return type
BackgroundFillSolid
class telebot.types.BackgroundType
Bases: ABC, JsonDeserializable
This object describes the type of a background. Currently, it can be one of
BackgroundTypeFill BackgroundTypeWallpaper BackgroundTypePattern BackgroundTypeChatTheme
Telegram documentation: https://core.telegram.org/bots/api#backgroundtype
Returns
Instance of the class
Return type
BackgroundTypeFill or BackgroundTypeWallpaper or BackgroundTypePattern or
BackgroundTypeChatTheme
class telebot.types.BackgroundTypeChatTheme(type, theme_name, **kwargs)
Bases: BackgroundFill
The background is taken directly from a built-in chat theme.
Telegram documentation: https://core.telegram.org/bots/api#backgroundtypechattheme
Parameters
• type (str) – Type of the background, always “chat_theme”
• theme_name (str) – Intensity of the pattern when it is shown above the filled background;
0-100
Returns
Instance of the class

6 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Return type
BackgroundTypeChatTheme
class telebot.types.BackgroundTypeFill(type, fill, dark_theme_dimming, **kwargs)
Bases: BackgroundFill
The background is automatically filled based on the selected colors.
Telegram documentation: https://core.telegram.org/bots/api#backgroundtypefill
Parameters
• type (str) – Type of the background, always “fill”
• fill (BackgroundFill) – The background fill
• dark_theme_dimming (int) – Dimming of the background in dark themes, as a percentage;
0-100
Returns
Instance of the class
Return type
BackgroundTypeFill
class telebot.types.BackgroundTypePattern(type, document, fill, intensity, is_inverted=None,
is_moving=None, **kwargs)
Bases: BackgroundFill
The background is a wallpaper in the JPEG format.
Telegram documentation: https://core.telegram.org/bots/api#backgroundtypepattern
Parameters
• type (str) – Type of the background, always “pattern”
• document (Document) – Document with the pattern
• fill (BackgroundFill) – The background fill that is combined with the pattern
• intensity (int) – Intensity of the pattern when it is shown above the filled background;
0-100
• is_inverted (bool) – Optional. True, if the background fill must be applied only to the
pattern itself. All other pixels are black in this case. For dark themes only
• is_moving (bool) – Optional. True, if the background moves slightly when the device is
tilted
Returns
Instance of the class
Return type
BackgroundTypePattern
class telebot.types.BackgroundTypeWallpaper(type, document, dark_theme_dimming, is_blurred=None,
is_moving=None, **kwargs)
Bases: BackgroundFill
The background is a wallpaper in the JPEG format.
Telegram documentation: https://core.telegram.org/bots/api#backgroundtypewallpaper
Parameters

1.3. Content 7
pyTelegramBotAPI, Release 4.25.0

• type (str) – Type of the background, always “wallpaper”

• document (Document) – Document with the wallpaper
• dark_theme_dimming (int) – Dimming of the background in dark themes, as a percentage;
0-100
• is_blurred (bool) – Optional. True, if the wallpaper is downscaled to fit in a 450x450
square and then box-blurred with radius 12
• is_moving (bool) – Optional. True, if the background moves slightly when the device is
tilted
Returns
Instance of the class
Return type
BackgroundTypeWallpaper
class telebot.types.Birthdate(day, month, year=None, **kwargs)
Bases: JsonDeserializable
This object represents a user’s birthdate.
Telegram documentation: https://core.telegram.org/bots/api#birthdate
Parameters
• day (int) – Day of the user’s birth; 1-31
• month (int) – Month of the user’s birth; 1-12
• year (int) – Optional. Year of the user’s birth
Returns
Instance of the class
Return type
Birthdate
class telebot.types.BotCommand(command, description, **kwargs)
Bases: JsonSerializable, JsonDeserializable, Dictionaryable
This object represents a bot command.
Telegram Documentation: https://core.telegram.org/bots/api#botcommand
Parameters
• command (str) – Text of the command; 1-32 characters. Can contain only lowercase English
letters, digits and underscores.
• description (str) – Description of the command; 1-256 characters.
Returns
Instance of the class
Return type
telebot.types.BotCommand
class telebot.types.BotCommandScope(type='default', chat_id=None, user_id=None)
Bases: ABC, JsonSerializable
This object represents the scope to which bot commands are applied. Currently, the following 7 scopes are
supported:

8 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• BotCommandScopeDefault
• BotCommandScopeAllPrivateChats
• BotCommandScopeAllGroupChats
• BotCommandScopeAllChatAdministrators
• BotCommandScopeChat
• BotCommandScopeChatAdministrators
• BotCommandScopeChatMember
Determining list of commands The following algorithm is used to determine the list of commands for a particular
user viewing the bot menu. The first list of commands which is set is returned:
Commands in the chat with the bot:
• BotCommandScopeChat + language_code
• BotCommandScopeChat
• BotCommandScopeAllPrivateChats + language_code
• BotCommandScopeAllPrivateChats
• BotCommandScopeDefault + language_code
• BotCommandScopeDefault
Commands in group and supergroup chats:
• BotCommandScopeChatMember + language_code
• BotCommandScopeChatMember
• BotCommandScopeChatAdministrators + language_code (administrators only)
• BotCommandScopeChatAdministrators (administrators only)
• BotCommandScopeChat + language_code
• BotCommandScopeChat
• BotCommandScopeAllChatAdministrators + language_code (administrators only)
• BotCommandScopeAllChatAdministrators (administrators only)
• BotCommandScopeAllGroupChats + language_code
• BotCommandScopeAllGroupChats
• BotCommandScopeDefault + language_code
• BotCommandScopeDefault

Returns
Instance of the class
Return type
telebot.types.BotCommandScope

class telebot.types.BotCommandScopeAllChatAdministrators
Bases: BotCommandScope
Represents the scope of bot commands, covering all group and supergroup chat administrators.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopeallchatadministrators

1.3. Content 9
pyTelegramBotAPI, Release 4.25.0

Parameters
type (str) – Scope type, must be all_chat_administrators
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeAllChatAdministrators
class telebot.types.BotCommandScopeAllGroupChats
Bases: BotCommandScope
Represents the scope of bot commands, covering all group and supergroup chats.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopeallgroupchats
Parameters
type (str) – Scope type, must be all_group_chats
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeAllGroupChats
class telebot.types.BotCommandScopeAllPrivateChats
Bases: BotCommandScope
Represents the scope of bot commands, covering all private chats.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopeallprivatechats
Parameters
type (str) – Scope type, must be all_private_chats
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeAllPrivateChats
class telebot.types.BotCommandScopeChat(chat_id: int | str | None = None)
Bases: BotCommandScope
Represents the scope of bot commands, covering a specific chat.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopechat
Parameters
• type (str) – Scope type, must be chat
• chat_id (int or str) – Unique identifier for the target chat or username of the target su-
pergroup (in the format @supergroupusername)
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeChat

10 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.BotCommandScopeChatAdministrators(chat_id: int | str | None = None)

Bases: BotCommandScope
Represents the scope of bot commands, covering all administrators of a specific group or supergroup chat.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopechatadministrators
Parameters
• type (str) – Scope type, must be chat_administrators
• chat_id (int or str) – Unique identifier for the target chat or username of the target su-
pergroup (in the format @supergroupusername)
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeChatAdministrators
class telebot.types.BotCommandScopeChatMember(chat_id: int | str | None = None, user_id: int | str | None
= None)
Bases: BotCommandScope
Represents the scope of bot commands, covering a specific member of a group or supergroup chat.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopechatmember
Parameters
• type (str) – Scope type, must be chat_member
• chat_id (int or str) – Unique identifier for the target chat or username of the target su-
pergroup (in the format @supergroupusername)
• user_id (int) – Unique identifier of the target user
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeChatMember
class telebot.types.BotCommandScopeDefault
Bases: BotCommandScope
Represents the default scope of bot commands. Default commands are used if no commands with a narrower
scope are specified for the user.
Telegram Documentation: https://core.telegram.org/bots/api#botcommandscopedefault
Parameters
type (str) – Scope type, must be default
Returns
Instance of the class
Return type
telebot.types.BotCommandScopeDefault
class telebot.types.BotDescription(description: str, **kwargs)
Bases: JsonDeserializable
This object represents a bot description.
Telegram documentation: https://core.telegram.org/bots/api#botdescription

1.3. Content 11
pyTelegramBotAPI, Release 4.25.0

Parameters
description (str) – Bot description
Returns
Instance of the class
Return type
telebot.types.BotDescription
class telebot.types.BotName(name: str, **kwargs)
Bases: JsonDeserializable
This object represents a bot name.
Telegram Documentation: https://core.telegram.org/bots/api#botname
Parameters
name (str) – The bot name
Returns
Instance of the class
Return type
BotName
class telebot.types.BotShortDescription(short_description: str, **kwargs)
Bases: JsonDeserializable
This object represents a bot short description.
Telegram documentation: https://core.telegram.org/bots/api#botshortdescription
Parameters
short_description (str) – Bot short description
Returns
Instance of the class
Return type
telebot.types.BotShortDescription
class telebot.types.BusinessConnection(id, user, user_chat_id, date, can_reply, is_enabled, **kwargs)
Bases: JsonDeserializable
This object describes the connection of the bot with a business account.
Telegram documentation: https://core.telegram.org/bots/api#businessconnection
Parameters
• id (str) – Unique identifier of the business connection
• user (User) – Business account user that created the business connection
• user_chat_id (int) – Identifier of a private chat with the user who created the business
connection
• date (int) – Date the connection was established in Unix time
• can_reply (bool) – True, if the bot can act on behalf of the business account in chats that
were active in the last 24 hours
• is_enabled (bool) – True, if the connection is active
Returns
Instance of the class

12 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Return type
BusinessConnection
class telebot.types.BusinessIntro(title=None, message=None, sticker=None, **kwargs)
Bases: JsonDeserializable
This object represents a business intro.
Telegram documentation: https://core.telegram.org/bots/api#businessintro
Parameters
• title (str) – Optional. Title text of the business intro
• message (str) – Optional. Message text of the business intro
• sticker (Sticker) – Optional. Sticker of the business intro
Returns
Instance of the class
Return type
BusinessIntro
class telebot.types.BusinessLocation(address, location=None, **kwargs)
Bases: JsonDeserializable
This object represents a business location.
Telegram documentation: https://core.telegram.org/bots/api#businesslocation
Parameters
• address (str) – Address of the business
• location (Location) – Optional. Location of the business
Returns
Instance of the class
Return type
BusinessLocation
class telebot.types.BusinessMessagesDeleted(business_connection_id, chat, message_ids, **kwargs)
Bases: JsonDeserializable
This object is received when messages are deleted from a connected business account.
Telegram documentation: https://core.telegram.org/bots/api#businessmessagesdeleted
Parameters
• business_connection_id (str) – Unique identifier of the business connection
• chat (Chat) – Information about a chat in the business account. The bot may not have access
to the chat or the corresponding user.
• message_ids (list of int) – A JSON-serialized list of identifiers of deleted messages in
the chat of the business account
Returns
Instance of the class
Return type
BusinessMessagesDeleted

1.3. Content 13
pyTelegramBotAPI, Release 4.25.0

class telebot.types.BusinessOpeningHours(time_zone_name, opening_hours, **kwargs)

Bases: JsonDeserializable
This object represents business opening hours.
Telegram documentation: https://core.telegram.org/bots/api#businessopeninghours
Parameters
• time_zone_name (str) – Unique name of the time zone for which the opening hours are
defined
• opening_hours (list of BusinessOpeningHoursInterval) – List of time intervals de-
scribing business opening hours
Returns
Instance of the class
Return type
BusinessOpeningHours
class telebot.types.BusinessOpeningHoursInterval(opening_minute, closing_minute, **kwargs)
Bases: JsonDeserializable
This object represents a business opening hours interval.
Telegram documentation: https://core.telegram.org/bots/api#businessopeninghoursinterval
Parameters
• opening_minute (int) – The minute’s sequence number in a week, starting on Monday,
marking the start of the time interval during which the business is open; 0 - 7 24 60
• closing_minute (int) – The minute’s sequence number in a week, starting on Monday,
marking the end of the time interval during which the business is open; 0 - 8 24 60
Returns
Instance of the class
Return type
BusinessOpeningHoursInterval
class telebot.types.CallbackQuery(id, from_user, data, chat_instance, json_string, message=None,
inline_message_id=None, game_short_name=None, **kwargs)
Bases: JsonDeserializable
This object represents an incoming callback query from a callback button in an inline keyboard. If the button that
originated the query was attached to a message sent by the bot, the field message will be present. If the button
was attached to a message sent via the bot (in inline mode), the field inline_message_id will be present. Exactly
one of the fields data or game_short_name will be present.
Telegram Documentation: https://core.telegram.org/bots/api#callbackquery
Parameters
• id (str) – Unique identifier for this query
• from_user (telebot.types.User) – Sender
• message (telebot.types.Message or telebot.types.InaccessibleMessage) – Op-
tional. Message sent by the bot with the callback button that originated the query
• inline_message_id (str) – Optional. Identifier of the message sent via the bot in inline
mode, that originated the query.

14 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• chat_instance (str) – Global identifier, uniquely corresponding to the chat to which the
message with the callback button was sent. Useful for high scores in games.
• data (str) – Optional. Data associated with the callback button. Be aware that the message
originated the query can contain no callback buttons with this data.
• game_short_name (str) – Optional. Short name of a Game to be returned, serves as the
unique identifier for the game
Returns
Instance of the class
Return type
telebot.types.CallbackQuery
class telebot.types.Chat(id, type, title=None, username=None, first_name=None, last_name=None,
photo=None, bio=None, has_private_forwards=None, description=None,
invite_link=None, pinned_message=None, permissions=None,
slow_mode_delay=None, message_auto_delete_time=None,
has_protected_content=None, sticker_set_name=None, can_set_sticker_set=None,
linked_chat_id=None, location=None, join_to_send_messages=None,
join_by_request=None, has_restricted_voice_and_video_messages=None,
is_forum=None, max_reaction_count=None, active_usernames=None,
emoji_status_custom_emoji_id=None, has_hidden_members=None,
has_aggressive_anti_spam_enabled=None, emoji_status_expiration_date=None,
available_reactions=None, accent_color_id=None,
background_custom_emoji_id=None, profile_accent_color_id=None,
profile_background_custom_emoji_id=None, has_visible_history=None,
unrestrict_boost_count=None, custom_emoji_sticker_set_name=None,
business_intro=None, business_location=None, business_opening_hours=None,
personal_chat=None, birthdate=None, can_send_paid_media=None, **kwargs)
Bases: ChatFullInfo
In BotAPI 7.3 Chat was reduced and full info moved to ChatFullInfo: “Split out the class ChatFullInfo from the
class Chat and changed the return type of the method getChat to ChatFullInfo.”
https://core.telegram.org/bots/api#chatfullinfo
Currently Chat is left as full copy of ChatFullInfo for compatibility.
class telebot.types.ChatAdministratorRights(is_anonymous: bool, can_manage_chat: bool,
can_delete_messages: bool, can_manage_video_chats:
bool, can_restrict_members: bool, can_promote_members:
bool, can_change_info: bool, can_invite_users: bool,
can_post_messages: bool | None = None,
can_edit_messages: bool | None = None,
can_pin_messages: bool | None = None,
can_manage_topics: bool | None = None,
can_post_stories: bool | None = None, can_edit_stories:
bool | None = None, can_delete_stories: bool | None =
None, **kwargs)
Bases: JsonDeserializable, JsonSerializable, Dictionaryable
Represents the rights of an administrator in a chat.
Telegram Documentation: https://core.telegram.org/bots/api#chatadministratorrights
Parameters
• is_anonymous (bool) – True, if the user’s presence in the chat is hidden

1.3. Content 15
pyTelegramBotAPI, Release 4.25.0

• can_manage_chat (bool) – True, if the administrator can access the chat event log, chat
statistics, message statistics in channels, see channel members, see anonymous administra-
tors in supergroups and ignore slow mode. Implied by any other administrator privilege
• can_delete_messages (bool) – True, if the administrator can delete messages of other
users
• can_manage_video_chats (bool) – True, if the administrator can manage video chats
• can_restrict_members (bool) – True, if the administrator can restrict, ban or unban chat
members
• can_promote_members (bool) – True, if the administrator can add new administrators with
a subset of their own privileges or demote administrators that he has promoted, directly or
indirectly (promoted by administrators that were appointed by the user)
• can_change_info (bool) – True, if the user is allowed to change the chat title, photo and
other settings
• can_invite_users (bool) – True, if the user is allowed to invite new users to the chat
• can_post_messages (bool) – Optional. True, if the administrator can post in the channel;
channels only
• can_edit_messages (bool) – Optional. True, if the administrator can edit messages of
other users and can pin messages; channels only
• can_pin_messages (bool) – Optional. True, if the user is allowed to pin messages; groups
and supergroups only
• can_manage_topics (bool) – Optional. True, if the user is allowed to create, rename,
close, and reopen forum topics; supergroups only
• can_post_stories (bool) – Optional. True, if the administrator can post channel stories
• can_edit_stories (bool) – Optional. True, if the administrator can edit stories
• can_delete_stories (bool) – Optional. True, if the administrator can delete stories of
other users
Returns
Instance of the class
Return type
telebot.types.ChatAdministratorRights
class telebot.types.ChatBackground(type, **kwargs)
Bases: JsonDeserializable
This object represents a chat background.
Telegram documentation: https://core.telegram.org/bots/api#chatbackground
Parameters
type (BackgroundType) – Type of the background
Returns
Instance of the class
Return type
ChatBackground

16 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatBoost(boost_id, add_date, expiration_date, source, **kwargs)

Bases: JsonDeserializable
This object contains information about a chat boost.
Telegram documentation: https://core.telegram.org/bots/api#chatboost
Parameters
• boost_id (str) – Unique identifier of the boost
• add_date (int) – Point in time (Unix timestamp) when the chat was boosted
• expiration_date (int) – Point in time (Unix timestamp) when the boost will automati-
cally expire, unless the booster’s Telegram Premium subscription is prolonged
• source (ChatBoostSource) – Optional. Source of the added boost (made Optional for
now due to API error)
Returns
Instance of the class
Return type
ChatBoost
class telebot.types.ChatBoostAdded(boost_count, **kwargs)
Bases: JsonDeserializable
This object represents a service message about a user boosting a chat.
Telegram documentation: https://core.telegram.org/bots/api#chatboostadded
Parameters
boost_count (int) – Number of boosts added by the user
Returns
Instance of the class
Return type
ChatBoostAdded
class telebot.types.ChatBoostRemoved(chat, boost_id, remove_date, source, **kwargs)
Bases: JsonDeserializable
This object represents a boost removed from a chat.
Telegram documentation: https://core.telegram.org/bots/api#chatboostremoved
Parameters
• chat (Chat) – Chat which was boosted
• boost_id (str) – Unique identifier of the boost
• remove_date (int) – Point in time (Unix timestamp) when the boost was removed
• source (ChatBoostSource) – Source of the removed boost
Returns
Instance of the class
Return type
ChatBoostRemoved

1.3. Content 17
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatBoostSource
Bases: ABC, JsonDeserializable
This object describes the source of a chat boost. It can be one of
ChatBoostSourcePremium ChatBoostSourceGiftCode ChatBoostSourceGiveaway
Telegram documentation: https://core.telegram.org/bots/api#chatboostsource
Returns
Instance of the class
Return type
ChatBoostSourcePremium or ChatBoostSourceGiftCode or ChatBoostSourceGiveaway
class telebot.types.ChatBoostSourceGiftCode(source, user, **kwargs)
Bases: ChatBoostSource
The boost was obtained by the creation of Telegram Premium gift codes to boost a chat.
Telegram documentation: https://core.telegram.org/bots/api#chatboostsourcegiftcode
Parameters
• source (str) – Source of the boost, always “gift_code”
• user (User) – User for which the gift code was created
Returns
Instance of the class
Return type
ChatBoostSourceGiftCode
class telebot.types.ChatBoostSourceGiveaway(source, giveaway_message_id, user=None,
is_unclaimed=None, prize_star_count=None, **kwargs)
Bases: ChatBoostSource
The boost was obtained by the creation of a Telegram Premium giveaway.
Telegram documentation: https://core.telegram.org/bots/api#chatboostsourcegiveaway
Parameters
• source (str) – Source of the boost, always “giveaway”
• giveaway_message_id (int) – Identifier of a message in the chat with the giveaway; the
message could have been deleted already. May be 0 if the message isn’t sent yet.
• user (User) – User that won the prize in the giveaway if any
• is_unclaimed (bool) – True, if the giveaway was completed, but there was no user to win
the prize
• prize_star_count (int) – Optional. The number of Telegram Stars to be split between
giveaway winners; for Telegram Star giveaways only
Returns
Instance of the class
Return type
ChatBoostSourceGiveaway

18 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatBoostSourcePremium(source, user, **kwargs)

Bases: ChatBoostSource
The boost was obtained by subscribing to Telegram Premium or by gifting a Telegram Premium subscription to
another user.
Telegram documentation: https://core.telegram.org/bots/api#chatboostsourcepremium
Parameters
• source (str) – Source of the boost, always “premium”
• user (User) – User that boosted the chat
Returns
Instance of the class
Return type
ChatBoostSourcePremium
class telebot.types.ChatBoostUpdated(chat, boost, **kwargs)
Bases: JsonDeserializable
This object represents a boost added to a chat or changed.
Telegram documentation: https://core.telegram.org/bots/api#chatboostupdated
Parameters
• chat (Chat) – Chat which was boosted
• boost (ChatBoost) – Infomation about the chat boost
Returns
Instance of the class
Return type
ChatBoostUpdated
class telebot.types.ChatFullInfo(id, type, title=None, username=None, first_name=None,
last_name=None, photo=None, bio=None, has_private_forwards=None,
description=None, invite_link=None, pinned_message=None,
permissions=None, slow_mode_delay=None,
message_auto_delete_time=None, has_protected_content=None,
sticker_set_name=None, can_set_sticker_set=None,
linked_chat_id=None, location=None, join_to_send_messages=None,
join_by_request=None,
has_restricted_voice_and_video_messages=None, is_forum=None,
max_reaction_count=None, active_usernames=None,
emoji_status_custom_emoji_id=None, has_hidden_members=None,
has_aggressive_anti_spam_enabled=None,
emoji_status_expiration_date=None, available_reactions=None,
accent_color_id=None, background_custom_emoji_id=None,
profile_accent_color_id=None,
profile_background_custom_emoji_id=None, has_visible_history=None,
unrestrict_boost_count=None, custom_emoji_sticker_set_name=None,
business_intro=None, business_location=None,
business_opening_hours=None, personal_chat=None, birthdate=None,
can_send_paid_media=None, **kwargs)
Bases: JsonDeserializable
This object represents a chat.

1.3. Content 19
pyTelegramBotAPI, Release 4.25.0

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

Parameters
• id (int) – Unique identifier for this chat. This number may have more than 32 significant
bits and some programming languages may have difficulty/silent defects in interpreting it.
But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type
are safe for storing this identifier.
• type (str) – Type of chat, can be either “private”, “group”, “supergroup” or “channel”
• title (str) – Optional. Title, for supergroups, channels and group chats
• username (str) – Optional. Username, for private chats, supergroups and channels if avail-
able
• first_name (str) – Optional. First name of the other party in a private chat
• last_name (str) – Optional. Last name of the other party in a private chat
• is_forum (bool) – Optional. True, if the supergroup chat is a forum (has topics enabled)
• max_reaction_count (int) – Optional. The maximum number of reactions that can be
set on a message in the chat
• photo (telebot.types.ChatPhoto) – Optional. Chat photo. Returned only in getChat.
• active_usernames (list of str) – Optional. If non-empty, the list of all active chat
usernames; for private chats, supergroups and channels. Returned only in getChat.
• birthdate (str) – Optional. Birthdate of the other party in a private chat. Returned only
in getChat.
• business_intro (telebot.types.BusinessIntro) – Optional. Business intro for the
chat. Returned only in getChat.
• business_location (telebot.types.BusinessLocation) – Optional. Business loca-
tion for the chat. Returned only in getChat.
:param business_opening_hours : Optional. Business opening hours for the chat. Returned only in getChat.
:type business_opening_hours: telebot.types.BusinessHours
Parameters
• personal_chat (telebot.types.Chat) – Optional. For private chats, the personal chan-
nel of the user. Returned only in getChat.
• available_reactions (list of telebot.types.ReactionType) – Optional. List of
available chat reactions; for private chats, supergroups and channels. Returned only in
getChat.
• accent_color_id (int) – Optional. Optional. Identifier of the accent color for the chat
name and backgrounds of the chat photo, reply header, and link preview. See accent colors
for more details. Returned only in getChat. Always returned in getChat.
• background_custom_emoji_id (str) – Optional. Custom emoji identifier of emoji cho-
sen by the chat for the reply header and link preview background. Returned only in getChat.
• profile_accent_color_id (int) – Optional. Identifier of the accent color for the chat’s
profile background. See profile accent colors for more details. Returned only in getChat.
• profile_background_custom_emoji_id (str) – Optional. Custom emoji identifier of
the emoji chosen by the chat for its profile background. Returned only in getChat.

20 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• emoji_status_custom_emoji_id (str) – Optional. Custom emoji identifier of emoji

status of the other party in a private chat. Returned only in getChat.
• emoji_status_expiration_date (int) – Optional. Expiration date of the emoji status
of the other party in a private chat, if any. Returned only in getChat.
• bio (str) – Optional. Bio of the other party in a private chat. Returned only in getChat.
• has_private_forwards (bool) – Optional. bool, if privacy settings of the other party
in the private chat allows to use tg://user?id=<user_id> links only in chats with the user.
Returned only in getChat.
• has_restricted_voice_and_video_messages – Optional. True, if the privacy settings
of the other party restrict sending voice and video note messages in the private chat. Returned
only in getChat.
:type bool
Parameters
• join_to_send_messages (bool) – Optional. bool, if users need to join the supergroup
before they can send messages. Returned only in getChat.
• join_by_request (bool) – Optional. bool, if all users directly joining the supergroup
need to be approved by supergroup administrators. Returned only in getChat.
• description (str) – Optional. Description, for groups, supergroups and channel chats.
Returned only in getChat.
• invite_link (str) – Optional. Primary invite link, for groups, supergroups and channel
chats. Returned only in getChat.
• pinned_message (telebot.types.Message) – Optional. The most recent pinned mes-
sage (by sending date). Returned only in getChat.
• permissions (telebot.types.ChatPermissions) – Optional. Default chat member
permissions, for groups and supergroups. Returned only in getChat.
• slow_mode_delay (int) – Optional. For supergroups, the minimum allowed delay between
consecutive messages sent by each unpriviledged user; in seconds. Returned only in getChat.
• unrestrict_boost_count (int) – Optional. For supergroups, the minimum number of
boosts that a non-administrator user needs to add in order to ignore slow mode and chat
permissions. Returned only in getChat.
• message_auto_delete_time (int) – Optional. The time after which all messages sent to
the chat will be automatically deleted; in seconds. Returned only in getChat.
• has_aggressive_anti_spam_enabled (bool) – Optional. bool, if the chat has enabled
aggressive anti-spam protection. Returned only in getChat.
• has_hidden_members (bool) – Optional. bool, if the chat has enabled hidden members.
Returned only in getChat.
• has_protected_content (bool) – Optional. bool, if messages from the chat can’t be
forwarded to other chats. Returned only in getChat.
• has_visible_history (bool) – Optional. True, if new chat members will have access to
old messages; available only to chat administrators. Returned only in getChat.
• sticker_set_name (str) – Optional. For supergroups, name of group sticker set. Returned
only in getChat.

1.3. Content 21
pyTelegramBotAPI, Release 4.25.0

• can_set_sticker_set (bool) – Optional. bool, if the bot can change the group sticker
set. Returned only in getChat.
• custom_emoji_sticker_set_name – Optional. For supergroups, the name of the group’s
custom emoji sticker set. Custom emoji from this set can be used by all users and bots in the
group. Returned only in getChat.
• custom_emoji_sticker_set_name – str
• linked_chat_id (int) – Optional. Unique identifier for the linked chat, i.e. the discussion
group identifier for a channel and vice versa; for supergroups and channel chats. This identi-
fier may be greater than 32 bits and some programming languages may have difficulty/silent
defects in interpreting it. But it is smaller than 52 bits, so a signed 64 bit integer or double-
precision float type are safe for storing this identifier. Returned only in getChat.
• location (telebot.types.ChatLocation) – Optional. For supergroups, the location to
which the supergroup is connected. Returned only in getChat.
• can_send_paid_media (bool) – Optional. True, if paid media messages can be sent or
forwarded to the channel chat. The field is available only for channel chats.
Returns
Instance of the class
Return type
telebot.types.ChatFullInfo
class telebot.types.ChatInviteLink(invite_link: str, creator: User, creates_join_request: bool, is_primary:
bool, is_revoked: bool, name: str | None = None, expire_date: int |
None = None, member_limit: int | None = None,
pending_join_request_count: int | None = None, **kwargs)
Bases: JsonSerializable, JsonDeserializable, Dictionaryable
Represents an invite link for a chat.
Telegram Documentation: https://core.telegram.org/bots/api#chatinvitelink
Parameters
• invite_link (str) – The invite link. If the link was created by another chat administrator,
then the second part of the link will be replaced with “. . . ”.
• creator (telebot.types.User) – Creator of the link
• creates_join_request (bool) – True, if users joining the chat via the link need to be
approved by chat administrators
• is_primary (bool) – True, if the link is primary
• is_revoked (bool) – True, if the link is revoked
• name (str) – Optional. Invite link name
• expire_date (int) – Optional. Point in time (Unix timestamp) when the link will expire
or has been expired
• member_limit (int) – Optional. The maximum number of users that can be members of
the chat simultaneously after joining the chat via this invite link; 1-99999
• pending_join_request_count (int) – Optional. Number of pending join requests cre-
ated using this link
Returns
Instance of the class

22 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.ChatInviteLink
class telebot.types.ChatJoinRequest(chat, from_user, user_chat_id, date, bio=None, invite_link=None,
**kwargs)
Bases: JsonDeserializable
Represents a join request sent to a chat.
Telegram Documentation: https://core.telegram.org/bots/api#chatjoinrequest
Parameters
• chat (telebot.types.Chat) – Chat to which the request was sent
• from_user (telebot.types.User) – User that sent the join request
• user_chat_id (int) – Optional. Identifier of a private chat with the user who sent the
join request. This number may have more than 32 significant bits and some programming
languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant
bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. The
bot can use this identifier for 24 hours to send messages until the join request is processed,
assuming no other administrator contacted the user.
• date (int) – Date the request was sent in Unix time
• bio (str) – Optional. Bio of the user.
• invite_link (telebot.types.ChatInviteLink) – Optional. Chat invite link that was
used by the user to send the join request
Returns
Instance of the class
Return type
telebot.types.ChatJoinRequest
class telebot.types.ChatLocation(location: Location, address: str, **kwargs)
Bases: JsonSerializable, JsonDeserializable, Dictionaryable
Represents a location to which a chat is connected.
Telegram Documentation: https://core.telegram.org/bots/api#chatlocation
Parameters
• location (telebot.types.Location) – The location to which the supergroup is con-
nected. Can’t be a live location.
• address (str) – Location address; 1-64 characters, as defined by the chat owner
Returns
Instance of the class
Return type
telebot.types.ChatLocation

1.3. Content 23
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatMember(user, status, custom_title=None, is_anonymous=None,

can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None, can_pin_messages=None,
is_member=None, can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None, can_add_web_page_previews=None,
can_manage_chat=None, can_manage_video_chats=None,
until_date=None, can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: JsonDeserializable
This object contains information about one member of a chat. Currently, the following 6 types of chat members
are supported:
• telebot.types.ChatMemberOwner
• telebot.types.ChatMemberAdministrator
• telebot.types.ChatMemberMember
• telebot.types.ChatMemberRestricted
• telebot.types.ChatMemberLeft
• telebot.types.ChatMemberBanned
Telegram Documentation: https://core.telegram.org/bots/api#chatmember
property can_manage_voice_chats

class telebot.types.ChatMemberAdministrator(user, status, custom_title=None, is_anonymous=None,

can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None,
can_promote_members=None, can_change_info=None,
can_invite_users=None, can_pin_messages=None,
is_member=None, can_send_messages=None,
can_send_audios=None, can_send_documents=None,
can_send_photos=None, can_send_videos=None,
can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None,
can_manage_chat=None, can_manage_video_chats=None,
until_date=None, can_manage_topics=None,
can_post_stories=None, can_edit_stories=None,
can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that has some additional privileges.
Telegram Documentation: https://core.telegram.org/bots/api#chatmemberadministrator
Parameters
• status (str) – The member’s status in the chat, always “administrator”

24 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

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

• can_be_edited (bool) – True, if the bot is allowed to edit administrator privileges of that
user
• is_anonymous (bool) – True, if the user’s presence in the chat is hidden
• can_manage_chat (bool) – True, if the administrator can access the chat event log, chat
statistics, message statistics in channels, see channel members, see anonymous administra-
tors in supergroups and ignore slow mode. Implied by any other administrator privilege
• can_delete_messages (bool) – True, if the administrator can delete messages of other
users
• can_manage_video_chats (bool) – True, if the administrator can manage video chats
• can_restrict_members (bool) – True, if the administrator can restrict, ban or unban chat
members
• can_promote_members (bool) – True, if the administrator can add new administrators with
a subset of their own privileges or demote administrators that he has promoted, directly or
indirectly (promoted by administrators that were appointed by the user)
• can_change_info (bool) – True, if the user is allowed to change the chat title, photo and
other settings
• can_invite_users (bool) – True, if the user is allowed to invite new users to the chat
• can_post_messages (bool) – Optional. True, if the administrator can post in the channel;
channels only
• can_edit_messages (bool) – Optional. True, if the administrator can edit messages of
other users and can pin messages; channels only
• can_pin_messages (bool) – Optional. True, if the user is allowed to pin messages; groups
and supergroups only
• can_manage_topics (bool) – Optional. True, if the user is allowed to create, rename,
close, and reopen forum topics; supergroups only
• custom_title (str) – Optional. Custom title for this user
• can_post_stories (bool) – Optional. True, if the administrator can post channel stories
• can_edit_stories (bool) – Optional. True, if the administrator can edit stories
• can_delete_stories (bool) – Optional. True, if the administrator can delete stories of
other users
Returns
Instance of the class
Return type
telebot.types.ChatMemberAdministrator

1.3. Content 25
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatMemberBanned(user, status, custom_title=None, is_anonymous=None,

can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None,
can_pin_messages=None, is_member=None,
can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None, can_manage_chat=None,
can_manage_video_chats=None, until_date=None,
can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that was banned in the chat and can’t return to the chat or view chat messages.
Telegram Documentation: https://core.telegram.org/bots/api#chatmemberbanned
Parameters
• status (str) – The member’s status in the chat, always “kicked”
• user (telebot.types.User) – Information about the user
• until_date (int) – Date when restrictions will be lifted for this user; unix time. If 0, then
the user is banned forever
Returns
Instance of the class
Return type
telebot.types.ChatMemberBanned
class telebot.types.ChatMemberLeft(user, status, custom_title=None, is_anonymous=None,
can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None,
can_pin_messages=None, is_member=None,
can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None, can_manage_chat=None,
can_manage_video_chats=None, until_date=None,
can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that isn’t currently a member of the chat, but may join it themselves.
Telegram Documentation: https://core.telegram.org/bots/api#chatmemberleft
Parameters
• status (str) – The member’s status in the chat, always “left”

26 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

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

Returns
Instance of the class
Return type
telebot.types.ChatMemberLeft
class telebot.types.ChatMemberMember(user, status, custom_title=None, is_anonymous=None,
can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None,
can_pin_messages=None, is_member=None,
can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None, can_manage_chat=None,
can_manage_video_chats=None, until_date=None,
can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that has no additional privileges or restrictions.
Telegram Documentation: https://core.telegram.org/bots/api#chatmembermember
Parameters
• status (str) – The member’s status in the chat, always “member”
• user (telebot.types.User) – Information about the user
Returns
Instance of the class
Return type
telebot.types.ChatMemberMember
class telebot.types.ChatMemberOwner(user, status, custom_title=None, is_anonymous=None,
can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None,
can_pin_messages=None, is_member=None,
can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None, can_manage_chat=None,
can_manage_video_chats=None, until_date=None,
can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that owns the chat and has all administrator privileges.

1.3. Content 27
pyTelegramBotAPI, Release 4.25.0

Telegram Documentation: https://core.telegram.org/bots/api#chatmemberowner

Parameters
• status (str) – The member’s status in the chat, always “creator”
• user (telebot.types.User) – Information about the user
• is_anonymous (bool) – True, if the user’s presence in the chat is hidden
• custom_title (str) – Optional. Custom title for this user
Returns
Instance of the class
Return type
telebot.types.ChatMemberOwner
class telebot.types.ChatMemberRestricted(user, status, custom_title=None, is_anonymous=None,
can_be_edited=None, can_post_messages=None,
can_edit_messages=None, can_delete_messages=None,
can_restrict_members=None, can_promote_members=None,
can_change_info=None, can_invite_users=None,
can_pin_messages=None, is_member=None,
can_send_messages=None, can_send_audios=None,
can_send_documents=None, can_send_photos=None,
can_send_videos=None, can_send_video_notes=None,
can_send_voice_notes=None, can_send_polls=None,
can_send_other_messages=None,
can_add_web_page_previews=None, can_manage_chat=None,
can_manage_video_chats=None, until_date=None,
can_manage_topics=None, can_post_stories=None,
can_edit_stories=None, can_delete_stories=None, **kwargs)
Bases: ChatMember
Represents a chat member that is under certain restrictions in the chat. Supergroups only.
Telegram Documentation: https://core.telegram.org/bots/api#chatmemberrestricted
Parameters
• status (str) – The member’s status in the chat, always “restricted”
• user (telebot.types.User) – Information about the user
• is_member (bool) – True, if the user is a member of the chat at the moment of the request
• can_change_info (bool) – True, if the user is allowed to change the chat title, photo and
other settings
• can_invite_users (bool) – True, if the user is allowed to invite new users to the chat
• can_pin_messages (bool) – True, if the user is allowed to pin messages
• can_manage_topics (bool) – True, if the user is allowed to create forum topics
• can_send_messages (bool) – True, if the user is allowed to send text messages, contacts,
locations and venues
• can_send_audios (bool) – True, if the user is allowed to send audios
• can_send_documents (bool) – True, if the user is allowed to send documents
• can_send_photos (bool) – True, if the user is allowed to send photos

28 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• can_send_videos (bool) – True, if the user is allowed to send videos

• can_send_video_notes (bool) – True, if the user is allowed to send video notes
• can_send_voice_notes (bool) – True, if the user is allowed to send voice notes
• can_send_polls (bool) – True, if the user is allowed to send polls
• can_send_other_messages (bool) – True, if the user is allowed to send animations,
games, stickers and use inline bots
• can_add_web_page_previews (bool) – True, if the user is allowed to add web page pre-
views to their messages
• until_date (int) – Date when restrictions will be lifted for this user; unix time. If 0, then
the user is restricted forever
Returns
Instance of the class
Return type
telebot.types.ChatMemberRestricted
class telebot.types.ChatMemberUpdated(chat, from_user, date, old_chat_member, new_chat_member,
invite_link=None, via_join_request=None,
via_chat_folder_invite_link=None, **kwargs)
Bases: JsonDeserializable
This object represents changes in the status of a chat member.
Telegram Documentation: https://core.telegram.org/bots/api#chatmemberupdated
Parameters
• chat (telebot.types.Chat) – Chat the user belongs to
• from_user (telebot.types.User) – Performer of the action, which resulted in the change
• date (int) – Date the change was done in Unix time
• old_chat_member (telebot.types.ChatMember) – Previous information about the chat
member
• new_chat_member (telebot.types.ChatMember) – New information about the chat
member
• invite_link (telebot.types.ChatInviteLink) – Optional. Chat invite link, which
was used by the user to join the chat; for joining by invite link events only.
• via_join_request (bool) – Optional. True, if the user joined the chat after sending a
direct join request without using an invite link and being approved by an administrator
• via_chat_folder_invite_link (bool) – Optional. True, if the user joined the chat via
a chat folder invite link
Returns
Instance of the class
Return type
telebot.types.ChatMemberUpdated
property difference: Dict[str, List]
Get the difference between old_chat_member and new_chat_member as a dict in the following format {‘pa-
rameter’: [old_value, new_value]} E.g {‘status’: [‘member’, ‘kicked’], ‘until_date’: [None, 1625055092]}

1.3. Content 29
pyTelegramBotAPI, Release 4.25.0

Returns
Dict of differences
Return type
Dict[str, List]
class telebot.types.ChatPermissions(can_send_messages=None, can_send_media_messages=None,
can_send_audios=None, can_send_documents=None,
can_send_photos=None, can_send_videos=None,
can_send_video_notes=None, can_send_voice_notes=None,
can_send_polls=None, can_send_other_messages=None,
can_add_web_page_previews=None, can_change_info=None,
can_invite_users=None, can_pin_messages=None,
can_manage_topics=None, **kwargs)
Bases: JsonDeserializable, JsonSerializable, Dictionaryable
Describes actions that a non-administrator user is allowed to take in a chat.
Telegram Documentation: https://core.telegram.org/bots/api#chatpermissions
Parameters
• can_send_messages (bool) – Optional. True, if the user is allowed to send text messages,
contacts, locations and venues
• can_send_audios (bool) – Optional. True, if the user is allowed to send audios
• can_send_documents (bool) – Optional. True, if the user is allowed to send documents
• can_send_photos (bool) – Optional. True, if the user is allowed to send photos
• can_send_videos (bool) – Optional. True, if the user is allowed to send videos
• can_send_video_notes (bool) – Optional. True, if the user is allowed to send video notes
• can_send_voice_notes (bool) – Optional. True, if the user is allowed to send voice notes
• can_send_polls (bool) – Optional. True, if the user is allowed to send polls, implies
can_send_messages
• can_send_other_messages (bool) – Optional. True, if the user is allowed to send ani-
mations, games, stickers and use inline bots
• can_add_web_page_previews (bool) – Optional. True, if the user is allowed to add web
page previews to their messages
• can_change_info (bool) – Optional. True, if the user is allowed to change the chat title,
photo and other settings. Ignored in public supergroups
• can_invite_users (bool) – Optional. True, if the user is allowed to invite new users to
the chat
• can_pin_messages (bool) – Optional. True, if the user is allowed to pin messages. Ignored
in public supergroups
• can_manage_topics (bool) – Optional. True, if the user is allowed to create forum topics.
If omitted defaults to the value of can_pin_messages
• can_send_media_messages (bool) – deprecated.
Returns
Instance of the class
Return type
telebot.types.ChatPermissions

30 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChatPhoto(small_file_id, small_file_unique_id, big_file_id, big_file_unique_id,

**kwargs)
Bases: JsonDeserializable
This object represents a chat photo.
Telegram Documentation: https://core.telegram.org/bots/api#chatphoto
Parameters
• small_file_id (str) – File identifier of small (160x160) chat photo. This file_id can be
used only for photo download and only for as long as the photo is not changed.
• small_file_unique_id (str) – Unique file identifier of small (160x160) chat photo,
which is supposed to be the same over time and for different bots. Can’t be used to download
or reuse the file.
• big_file_id (str) – File identifier of big (640x640) chat photo. This file_id can be used
only for photo download and only for as long as the photo is not changed.
• big_file_unique_id (str) – Unique file identifier of big (640x640) chat photo, which is
supposed to be the same over time and for different bots. Can’t be used to download or reuse
the file.
Returns
Instance of the class
Return type
telebot.types.ChatPhoto
class telebot.types.ChatShared(request_id: int, chat_id: int, title: str | None = None, photo: List[PhotoSize]
| None = None, username: str | None = None, **kwargs)
Bases: JsonDeserializable
This object contains information about the chat whose identifier was shared with the bot using a tele-
bot.types.KeyboardButtonRequestChat button.
Telegram documentation: https://core.telegram.org/bots/api#Chatshared
Parameters
• request_id (int) – identifier of the request
• chat_id (int) – Identifier of the shared chat. This number may have more than 32 signifi-
cant bits and some programming languages may have difficulty/silent defects in interpreting
it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are
safe for storing this identifier. The bot may not have access to the chat and could be unable
to use this identifier, unless the chat is already known to the bot by some other means.
• title (str) – Optional. Title of the shared chat
• photo (list of telebot.types.PhotoSize) – Optional. Array of Photosize
• username (str) – Optional. Username of the shared chat
Returns
Instance of the class
Return type
telebot.types.ChatShared

1.3. Content 31
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ChosenInlineResult(result_id, from_user, query, location=None,

inline_message_id=None, **kwargs)
Bases: JsonDeserializable
Represents a result of an inline query that was chosen by the user and sent to their chat partner.
Telegram Documentation: https://core.telegram.org/bots/api#choseninlineresult
Parameters
• result_id (str) – The unique identifier for the result that was chosen
• from (telebot.types.User) – The user that chose the result
• location (telebot.types.Location) – Optional. Sender location, only for bots that
require user location
• inline_message_id (str) – Optional. Identifier of the sent inline message. Available
only if there is an inline keyboard attached to the message. Will be also received in callback
queries and can be used to edit the message.
• query (str) – The query that was used to obtain the result
Returns
Instance of the class
Return type
telebot.types.ChosenInlineResult
class telebot.types.Contact(phone_number, first_name, last_name=None, user_id=None, vcard=None,
**kwargs)
Bases: JsonDeserializable
This object represents a phone contact.
Telegram Documentation: https://core.telegram.org/bots/api#contact
Parameters
• phone_number (str) – Contact’s phone number
• first_name (str) – Contact’s first name
• last_name (str) – Optional. Contact’s last name
• user_id (int) – Optional. Contact’s user identifier in Telegram. This number may have
more than 32 significant bits and some programming languages may have difficulty/silent
defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-
precision float type are safe for storing this identifier.
• vcard (str) – Optional. Additional data about the contact in the form of a vCard
Returns
Instance of the class
Return type
telebot.types.Contact
class telebot.types.CopyTextButton(text: str, **kwargs)
Bases: JsonSerializable, JsonDeserializable
This object represents an inline keyboard button that copies specified text to the clipboard.
Telegram documentation: https://core.telegram.org/bots/api#copytextbutton

32 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Parameters
text (str) – The text to be copied to the clipboard; 1-256 characters
Returns
Instance of the class
Return type
CopyTextButton
to_dict()

class telebot.types.Dice(value, emoji, **kwargs)

Bases: JsonSerializable, Dictionaryable, JsonDeserializable
This object represents an animated emoji that displays a random value.
Telegram Documentation: https://core.telegram.org/bots/api#dice
Parameters
• emoji (str) – Emoji on which the dice throw animation is based
• value (int) – Value of the dice, 1-6 for “”, “” and “” base emoji, 1-5 for “” and “” base
emoji, 1-64 for “” base emoji
Returns
Instance of the class
Return type
telebot.types.Dice
class telebot.types.Dictionaryable
Bases: object
Subclasses of this class are guaranteed to be able to be converted to dictionary. All subclasses of this class must
override to_dict.
class telebot.types.Document(file_id, file_unique_id, thumbnail=None, file_name=None, mime_type=None,
file_size=None, **kwargs)
Bases: JsonDeserializable
This object represents a general file (as opposed to photos, voice messages and audio files).
Telegram Documentation: https://core.telegram.org/bots/api#document
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• thumbnail (telebot.types.PhotoSize) – Optional. Document thumbnail as defined by
sender
• file_name (str) – Optional. Original filename as defined by sender
• mime_type (str) – Optional. MIME type of the file as defined by sender
• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.

1.3. Content 33
pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
telebot.types.Document
property thumb: PhotoSize | None

class telebot.types.ExternalReplyInfo(origin: MessageOrigin, chat: Chat | None = None, message_id: int

| None = None, link_preview_options: LinkPreviewOptions | None
= None, animation: Animation | None = None, audio: Audio |
None = None, document: Document | None = None, photo:
List[PhotoSize] | None = None, sticker: Sticker | None = None,
story: Story | None = None, video: Video | None = None,
video_note: VideoNote | None = None, voice: Voice | None =
None, has_media_spoiler: bool | None = None, contact: Contact |
None = None, dice: Dice | None = None, game: Game | None =
None, giveaway: Giveaway | None = None, giveaway_winners:
GiveawayWinners | None = None, invoice: Invoice | None = None,
location: Location | None = None, poll: Poll | None = None,
venue: Venue | None = None, paid_media: PaidMediaInfo | None
= None, **kwargs)
Bases: JsonDeserializable
This object contains information about a message that is being replied to, which may come from another chat or
forum topic.
Telegram documentation: https://core.telegram.org/bots/api#externalreplyinfo
Parameters
• origin (MessageOrigin) – Origin of the message replied to by the given message
• chat (Chat) – Optional. Chat the original message belongs to. Available only if the chat is
a supergroup or a channel.
• message_id (int) – Optional. Unique message identifier inside the original chat. Available
only if the original chat is a supergroup or a channel.
• link_preview_options (LinkPreviewOptions) – Optional. Options used for link pre-
view generation for the original message, if it is a text message
• animation (Animation) – Optional. Message is an animation, information about the ani-
mation
• audio (Audio) – Optional. Message is an audio file, information about the file
• document (Document) – Optional. Message is a general file, information about the file
• paid_media (PaidMedia) – Optional. Message is a paid media content
• photo (list of PhotoSize) – Optional. Message is a photo, available sizes of the photo
• sticker (Sticker) – Optional. Message is a sticker, information about the sticker
• story (Story) – Optional. Message is a forwarded story
• video (Video) – Optional. Message is a video, information about the video
• video_note (VideoNote) – Optional. Message is a video note, information about the video
message
• voice (Voice) – Optional. Message is a voice message, information about the file

34 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• has_media_spoiler (bool) – Optional. True, if the message media is covered by a spoiler

animation
• contact (Contact) – Optional. Message is a shared contact, information about the contact
• dice (Dice) – Optional. Message is a dice with random value
• game (Game) – Optional. Message is a game, information about the game. More about games
»
• giveaway (Giveaway) – Optional. Message is a scheduled giveaway, information about the
giveaway
• giveaway_winners (GiveawayWinners) – Optional. A giveaway with public winners was
completed
• invoice (Invoice) – Optional. Message is an invoice for a payment, information about the
invoice. More about payments »
• location (Location) – Optional. Message is a shared location, information about the
location
• poll (Poll) – Optional. Message is a native poll, information about the poll
• venue (Venue) – Optional. Message is a venue, information about the venue
Returns
Instance of the class
Return type
ExternalReplyInfo
class telebot.types.File(file_id, file_unique_id, file_size=None, file_path=None, **kwargs)
Bases: JsonDeserializable
This object represents a file ready to be downloaded. The file can be downloaded via the link https://api.telegram.
org/file/bot<token>/<file_path>. It is guaranteed that the link will be valid for at least 1 hour. When the link
expires, a new one can be requested by calling getFile.
Telegram Documentation: https://core.telegram.org/bots/api#file
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.
• file_path (str) – Optional. File path. Use https://api.telegram.org/
file/bot<token>/<file_path> to get the file.
Returns
Instance of the class
Return type
telebot.types.File

1.3. Content 35
pyTelegramBotAPI, Release 4.25.0

class telebot.types.ForceReply(selective: bool | None = None, input_field_placeholder: str | None = None)

Bases: JsonSerializable
Upon receiving a message with this object, Telegram clients will display a reply interface to the user (act as if
the user has selected the bot’s message and tapped ‘Reply’). This can be extremely useful if you want to create
user-friendly step-by-step interfaces without having to sacrifice privacy mode.
Telegram Documentation: https://core.telegram.org/bots/api#forcereply
Parameters
• force_reply (bool) – Shows reply interface to the user, as if they manually selected the
bot’s message and tapped ‘Reply’
• input_field_placeholder (str) – Optional. The placeholder to be shown in the input
field when the reply is active; 1-64 characters
• selective (bool) – Optional. Use this parameter if you want to force reply from specific
users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the
bot’s message is a reply to a message in the same chat and forum topic, sender of the original
message.
Returns
Instance of the class
Return type
telebot.types.ForceReply
class telebot.types.ForumTopic(message_thread_id: int, name: str, icon_color: int, icon_custom_emoji_id:
str | None = None, **kwargs)
Bases: JsonDeserializable
This object represents a forum topic.
Telegram documentation: https://core.telegram.org/bots/api#forumtopic
Parameters
• message_thread_id (int) – Unique identifier of the forum topic
• name (str) – Name of the topic
• icon_color (int) – Color of the topic icon in RGB format
• icon_custom_emoji_id (str) – Optional. Unique identifier of the custom emoji shown
as the topic icon
Returns
Instance of the class
Return type
telebot.types.ForumTopic
class telebot.types.ForumTopicClosed
Bases: JsonDeserializable
This object represents a service message about a forum topic closed in the chat. Currently holds no information.
Telegram documentation: https://core.telegram.org/bots/api#forumtopicclosed
class telebot.types.ForumTopicCreated(name: str, icon_color: int, icon_custom_emoji_id: str | None =
None, **kwargs)
Bases: JsonDeserializable

36 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

This object represents a service message about a new forum topic created in the chat.
Telegram documentation: https://core.telegram.org/bots/api#forumtopiccreated
Parameters
• name (str) – Name of the topic
• icon_color (int) – Color of the topic icon in RGB format
• icon_custom_emoji_id (str) – Optional. Unique identifier of the custom emoji shown
as the topic icon
Returns
Instance of the class
Return type
telebot.types.ForumTopicCreated
class telebot.types.ForumTopicEdited(name: str | None = None, icon_custom_emoji_id: str | None = None,
**kwargs)
Bases: JsonDeserializable
This object represents a service message about an edited forum topic.
Telegram documentation: https://core.telegram.org/bots/api#forumtopicedited
Parameters
• name (str) – Optional, Name of the topic(if updated)
• icon_custom_emoji_id (str) – Optional. New identifier of the custom emoji shown as
the topic icon, if it was edited; an empty string if the icon was removed
class telebot.types.ForumTopicReopened
Bases: JsonDeserializable
This object represents a service message about a forum topic reopened in the chat. Currently holds no informa-
tion.
Telegram documentation: https://core.telegram.org/bots/api#forumtopicreopened
class telebot.types.Game(title, description, photo, text=None, text_entities=None, animation=None,
**kwargs)
Bases: JsonDeserializable
This object represents a game. Use BotFather to create and edit games, their short names will act as unique
identifiers.
Telegram Documentation: https://core.telegram.org/bots/api#game
Parameters
• title (str) – Title of the game
• description (str) – Description of the game
• photo (list of telebot.types.PhotoSize) – Photo that will be displayed in the game
message in chats.
• text (str) – Optional. Brief description of the game or high scores included in the game
message. Can be automatically edited to include current high scores for the game when the
bot calls setGameScore, or manually edited using editMessageText. 0-4096 characters.
• text_entities (list of telebot.types.MessageEntity) – Optional. Special entities
that appear in text, such as usernames, URLs, bot commands, etc.

1.3. Content 37
pyTelegramBotAPI, Release 4.25.0

• animation (telebot.types.Animation) – Optional. Animation that will be displayed

in the game message in chats. Upload via BotFather
Returns
Instance of the class
Return type
telebot.types.Game
classmethod parse_entities(message_entity_array) → List[MessageEntity]
Parse the message entity array into a list of MessageEntity objects
classmethod parse_photo(photo_size_array) → List[PhotoSize]
Parse the photo array into a list of PhotoSize objects
class telebot.types.GameHighScore(position: int, user: User, score: int, **kwargs)
Bases: JsonDeserializable
This object represents one row of the high scores table for a game.
Telegram Documentation: https://core.telegram.org/bots/api#gamehighscore
Parameters
• position (int) – Position in high score table for the game
• user (telebot.types.User) – User
• score (int) – Score
Returns
Instance of the class
Return type
telebot.types.GameHighScore
class telebot.types.GeneralForumTopicHidden
Bases: JsonDeserializable
This object represents a service message about General forum topic hidden in the chat. Currently holds no
information.
Telegram documentation: https://core.telegram.org/bots/api#generalforumtopichidden
class telebot.types.GeneralForumTopicUnhidden
Bases: JsonDeserializable
This object represents a service message about General forum topic unhidden in the chat. Currently holds no
information.
Telegram documentation: https://core.telegram.org/bots/api#generalforumtopicunhidden
class telebot.types.Gift(id, sticker, star_count, total_count=None, remaining_count=None,
upgrade_star_count=None, **kwargs)
Bases: JsonDeserializable
This object represents a gift that can be sent by the bot.
Telegram documentation: https://core.telegram.org/bots/api#gift
Parameters
• id (str) – Unique identifier of the gift
• sticker (Sticker) – The sticker that represents the gift

38 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• star_count (int) – The number of Telegram Stars that must be paid to send the sticker
• upgrade_star_count (int) – Optional. The number of Telegram Stars that must be paid
to upgrade the gift to a unique one
• total_count (int) – Optional. The total number of the gifts of this type that can be sent;
for limited gifts only
• remaining_count (int) – Optional. The number of remaining gifts of this type that can
be sent; for limited gifts only
Returns
Instance of the class
Return type
Gift
class telebot.types.Gifts(gifts, **kwargs)
Bases: JsonDeserializable
This object represent a list of gifts.
Telegram documentation: https://core.telegram.org/bots/api#gifts
Parameters
gifts (list of Gift) – The list of gifts
Returns
Instance of the class
Return type
Gifts
class telebot.types.Giveaway(chats: List[Chat], winners_selection_date: int, winner_count: int,
only_new_members: bool | None = None, has_public_winners: bool | None =
None, prize_description: str | None = None, country_codes: List[str] | None =
None, premium_subscription_month_count: int | None = None,
prize_star_count: int | None = None, **kwargs)
Bases: JsonDeserializable
This object represents a message about a scheduled giveaway.
Telegram documentation: https://core.telegram.org/bots/api#giveaway
Parameters
• chats (list of Chat) – The list of chats which the user must join to participate in the
giveaway
• winners_selection_date (int) – Point in time (Unix timestamp) when winners of the
giveaway will be selected
• winner_count (int) – The number of users which are supposed to be selected as winners
of the giveaway
• only_new_members (bool) – Optional. True, if only users who join the chats after the
giveaway started should be eligible to win
• has_public_winners (bool) – Optional. True, if the list of giveaway winners will be
visible to everyone
• prize_description (str) – Optional. Description of additional giveaway prize

1.3. Content 39
pyTelegramBotAPI, Release 4.25.0

• country_codes (list of str) – Optional. A list of two-letter ISO 3166-1 alpha-2 country
codes indicating the countries from which eligible users for the giveaway must come. If
empty, then all users can participate in the giveaway.
• prize_star_count (int) – Optional. The number of Telegram Stars to be split between
giveaway winners; for Telegram Star giveaways only
• premium_subscription_month_count (int) – Optional. The number of months the
Telegram Premium subscription won from the giveaway will be active for
Returns
Instance of the class
Return type
Giveaway
class telebot.types.GiveawayCompleted(winner_count: int, unclaimed_prize_count: int | None = None,
giveaway_message: Message | None = None, is_star_giveaway:
bool | None = None, **kwargs)
Bases: JsonDeserializable
This object represents a service message about the completion of a giveaway without public winners.
Telegram documentation: https://core.telegram.org/bots/api#giveawaycompleted
Parameters
• winner_count (int) – Number of winners in the giveaway
• unclaimed_prize_count (int) – Optional. Number of undistributed prizes
• giveaway_message (Message) – Optional. Message with the giveaway that was completed,
if it wasn’t deleted
• is_star_giveaway (bool) – Optional. True, if the giveaway was a Telegram Star giveaway
Returns
Instance of the class
Return type
GiveawayCompleted
class telebot.types.GiveawayCreated(prize_star_count=None, **kwargs)
Bases: JsonDeserializable
This object represents a service message about the creation of a scheduled giveaway.
Prize_star_count
Optional. The number of Telegram Stars to be split between giveaway winners; for Telegram
Star giveaways only
Returns
Instance of the class
class telebot.types.GiveawayWinners(chat: Chat, giveaway_message_id: int, winners_selection_date: int,
winner_count: int, winners: List[User], additional_chat_count: int |
None = None, premium_subscription_month_count: int | None =
None, unclaimed_prize_count: int | None = None,
only_new_members: bool | None = None, was_refunded: bool | None
= None, prize_description: str | None = None, prize_star_count: int |
None = None, **kwargs)
Bases: JsonDeserializable

40 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

This object represents a message about the completion of a giveaway with public winners.
Telegram documentation: https://core.telegram.org/bots/api#giveawaywinners
Parameters
• chat (Chat) – The chat that created the giveaway
• giveaway_message_id (int) – Identifier of the messsage with the giveaway in the chat
• winners_selection_date (int) – Point in time (Unix timestamp) when winners of the
giveaway were selected
• winner_count (int) – Total number of winners in the giveaway
• winners (list of User) – List of up to 100 winners of the giveaway
• additional_chat_count (int) – Optional. The number of other chats the user had to join
in order to be eligible for the giveaway
• premium_subscription_month_count (int) – Optional. The number of months the
Telegram Premium subscription won from the giveaway will be active for
• unclaimed_prize_count (int) – Optional. Number of undistributed prizes
• only_new_members (bool) – Optional. True, if only users who had joined the chats after
the giveaway started were eligible to win
• was_refunded (bool) – Optional. True, if the giveaway was canceled because the payment
for it was refunded
• prize_description (str) – Optional. Description of additional giveaway prize
• prize_star_count (int) – Optional. The number of Telegram Stars to be split between
giveaway winners; for Telegram Star giveaways only
Returns
Instance of the class
Return type
GiveawayWinners
class telebot.types.InaccessibleMessage(chat, message_id, date, **kwargs)
Bases: JsonDeserializable
This object describes a message that was deleted or is otherwise inaccessible to the bot.
Telegram documentation: https://core.telegram.org/bots/api#inaccessiblemessage
Parameters
• chat (Chat) – Chat the message belonged to
• message_id (int) – Unique message identifier inside the chat
• date (int) – Always 0. The field can be used to differentiate regular and inaccessible mes-
sages.
Returns
Instance of the class
Return type
InaccessibleMessage

1.3. Content 41
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineKeyboardButton(text: str, url: str | None = None, callback_data: str | None =
None, web_app: WebAppInfo | None = None,
switch_inline_query: str | None = None,
switch_inline_query_current_chat: str | None = None,
switch_inline_query_chosen_chat:
SwitchInlineQueryChosenChat | None = None,
callback_game=None, pay: bool | None = None, login_url:
LoginUrl | None = None, copy_text: CopyTextButton | None =
None, **kwargs)
Bases: Dictionaryable, JsonSerializable, JsonDeserializable
This object represents one button of an inline keyboard. You must use exactly one of the optional fields.
Telegram Documentation: https://core.telegram.org/bots/api#inlinekeyboardbutton
Parameters
• text (str) – Label text on the button
• url (str) – Optional. HTTP or tg:// URL to be opened when the button is pressed. Links
tg://user?id=<user_id> can be used to mention a user by their ID without using a username,
if this is allowed by their privacy settings.
• callback_data (str) – Optional. Data to be sent in a callback query to the bot when button
is pressed, 1-64 bytes
• web_app (telebot.types.WebAppInfo) – Optional. Description of the Web App that will
be launched when the user presses the button. The Web App will be able to send an arbitrary
message on behalf of the user using the method answerWebAppQuery. Available only in
private chats between a user and the bot.
• login_url (telebot.types.LoginUrl) – Optional. An HTTPS URL used to automati-
cally authorize the user. Can be used as a replacement for the Telegram Login Widget.
• switch_inline_query (str) – Optional. If set, pressing the button will prompt the user
to select one of their chats, open that chat and insert the bot’s username and the specified
inline query in the input field. May be empty, in which case just the bot’s username will
be inserted.Note: This offers an easy way for users to start using your bot in inline mode
when they are currently in a private chat with it. Especially useful when combined with
switch_pm. . . actions - in this case the user will be automatically returned to the chat they
switched from, skipping the chat selection screen.
• switch_inline_query_current_chat (str) – Optional. If set, pressing the button will
insert the bot’s username and the specified inline query in the current chat’s input field. May
be empty, in which case only the bot’s username will be inserted.This offers a quick way for
the user to open your bot in inline mode in the same chat - good for selecting something from
multiple options.
• switch_inline_query_chosen_chat (telebot.types.
SwitchInlineQueryChosenChat) – Optional. If set, pressing the button will prompt the
user to select one of their chats of the specified type, open that chat and insert the bot’s
username and the specified inline query in the input field
• callback_game (telebot.types.CallbackGame) – Optional. Description of the game
that will be launched when the user presses the button. NOTE: This type of button must
always be the first button in the first row.
• pay (bool) – Optional. Specify True, to send a Pay button. NOTE: This type of button must
always be the first button in the first row and can only be used in invoice messages.

42 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• copy_text (telebot.types.CopyTextButton) – Optional. Description of the button

that copies the specified text to the clipboard.
Returns
Instance of the class
Return type
telebot.types.InlineKeyboardButton
class telebot.types.InlineKeyboardMarkup(keyboard=None, row_width=3)
Bases: Dictionaryable, JsonSerializable, JsonDeserializable
This object represents an inline keyboard that appears right next to the message it belongs to.

ò Note

It is recommended to use telebot.util.quick_markup() instead.

Listing 1: Example of a custom keyboard with buttons.

from telebot.util import quick_markup

markup = quick_markup({
'Twitter': {'url': 'https://twitter.com'},
'Facebook': {'url': 'https://facebook.com'},
'Back': {'callback_data': 'whatever'}
}, row_width=2)
# returns an InlineKeyboardMarkup with two buttons in a row, one leading to Twitter,
˓→ the other to facebook

# and a back button below

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

Parameters
• keyboard (list of list of telebot.types.InlineKeyboardButton) – list of button
rows, each represented by an list of telebot.types.InlineKeyboardButton objects
• row_width (int) – number of telebot.types.InlineKeyboardButton objects on each
row
Returns
Instance of the class
Return type
telebot.types.InlineKeyboardMarkup
add(*args, row_width=None) → InlineKeyboardMarkup
This method adds buttons to the keyboard without exceeding row_width.
E.g. InlineKeyboardMarkup.add(“A”, “B”, “C”) yields the json result: {keyboard: [[“A”], [“B”], [“C”]]}
when row_width is set to 1. When row_width is set to 2, the result: {keyboard: [[“A”, “B”], [“C”]]} See
https://core.telegram.org/bots/api#inlinekeyboardmarkup
Parameters
• args (list of telebot.types.InlineKeyboardButton) – Array of InlineKeyboard-
Button to append to the keyboard

1.3. Content 43
pyTelegramBotAPI, Release 4.25.0

• row_width (int) – width of row

Returns
self, to allow function chaining.
Return type
telebot.types.InlineKeyboardMarkup
max_row_keys = 8

row(*args) → InlineKeyboardMarkup
Adds a list of InlineKeyboardButton to the keyboard. This method does not consider row_width.
InlineKeyboardMarkup.row(“A”).row(“B”, “C”).to_json() outputs: ‘{keyboard: [[“A”], [“B”, “C”]]}’ See
https://core.telegram.org/bots/api#inlinekeyboardmarkup
Parameters
args (list of telebot.types.InlineKeyboardButton) – Array of InlineKeyboardBut-
ton to append to the keyboard
Returns
self, to allow function chaining.
Return type
telebot.types.InlineKeyboardMarkup
class telebot.types.InlineQuery(id, from_user, query, offset, chat_type=None, location=None, **kwargs)
Bases: JsonDeserializable
This object represents an incoming inline query. When the user sends an empty query, your bot could return
some default or trending results.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequery
Parameters
• id (str) – Unique identifier for this query
• from_user (telebot.types.User) – Sender
• query (str) – Text of the query (up to 256 characters)
• offset (str) – Offset of the results to be returned, can be controlled by the bot
• chat_type (str) – Optional. Type of the chat from which the inline query was sent. Can
be either “sender” for a private chat with the inline query sender, “private”, “group”, “super-
group”, or “channel”. The chat type should be always known for requests sent from official
clients and most third-party clients, unless the request was sent from a secret chat
• location (telebot.types.Location) – Optional. Sender location, only for bots that
request user location
Returns
Instance of the class
Return type
telebot.types.InlineQuery

44 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultArticle(id: str, title: str, input_message_content:

InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent, reply_markup:
InlineKeyboardMarkup | None = None, url: str | None =
None, hide_url: bool | None = None, description: str |
None = None, thumbnail_url: str | None = None,
thumbnail_width: int | None = None, thumbnail_height:
int | None = None)
Bases: InlineQueryResultBase
Represents a link to an article or web page.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultarticle
Parameters
• type (str) – Type of the result, must be article
• id (str) – Unique identifier for this result, 1-64 Bytes
• title (str) – Title of the result
• input_message_content (telebot.types.InputMessageContent) – Content of the
message to be sent
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• url (str) – Optional. URL of the result
• hide_url (bool) – Optional. Pass True, if you don’t want the URL to be shown in the
message
• description (str) – Optional. Short description of the result
• thumbnail_url (str) – Optional. Url of the thumbnail for the result
• thumbnail_width (int) – Optional. Thumbnail width
• thumbnail_height (int) – Optional. Thumbnail height
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultArticle
property thumb_height: int

property thumb_url: str

property thumb_width: int

1.3. Content 45
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultAudio(id: str, audio_url: str, title: str, caption: str | None = None,
caption_entities: List[MessageEntity] | None = None,
parse_mode: str | None = None, performer: str | None =
None, audio_duration: int | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent
| InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultBase
Represents a link to an MP3 audio file. By default, this audio file will be sent by the user. Alternatively, you can
use input_message_content to send a message with the specified content instead of the audio.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultaudio
Parameters
• type (str) – Type of the result, must be audio
• id (str) – Unique identifier for this result, 1-64 bytes
• audio_url (str) – A valid URL for the audio file
• title (str) – Title
• caption (str) – Optional. Caption, 0-1024 characters after entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the audio caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• performer (str) – Optional. Performer
• audio_duration (int) – Optional. Audio duration in seconds
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the audio
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultAudio
class telebot.types.InlineQueryResultBase(type: str, id: str, title: str | None = None, caption: str | None
= None, input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent |
InputContactMessageContent | InputInvoiceMessageContent |
None = None, reply_markup: InlineKeyboardMarkup | None
= None, caption_entities: List[MessageEntity] | None =
None, parse_mode: str | None = None)
Bases: ABC, Dictionaryable, JsonSerializable
This object represents one result of an inline query. Telegram clients currently support results of the following
20 types:
• InlineQueryResultCachedAudio

46 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• InlineQueryResultCachedDocument
• InlineQueryResultCachedGif
• InlineQueryResultCachedMpeg4Gif
• InlineQueryResultCachedPhoto
• InlineQueryResultCachedSticker
• InlineQueryResultCachedVideo
• InlineQueryResultCachedVoice
• InlineQueryResultArticle
• InlineQueryResultAudio
• InlineQueryResultContact
• InlineQueryResultGame
• InlineQueryResultDocument
• InlineQueryResultGif
• InlineQueryResultLocation
• InlineQueryResultMpeg4Gif
• InlineQueryResultPhoto
• InlineQueryResultVenue
• InlineQueryResultVideo
• InlineQueryResultVoice
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresult
class telebot.types.InlineQueryResultCachedAudio(id: str, audio_file_id: str, caption: str | None =
None, caption_entities: List[MessageEntity] | None
= None, parse_mode: str | None = None,
reply_markup: InlineKeyboardMarkup | None =
None, input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to an MP3 audio file stored on the Telegram servers. By default, this audio file will be sent by
the user. Alternatively, you can use input_message_content to send a message with the specified content instead
of the audio.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedaudio
Parameters
• type (str) – Type of the result, must be audio
• id (str) – Unique identifier for this result, 1-64 bytes
• audio_file_id (str) – A valid file identifier for the audio file
• caption (str) – Optional. Caption, 0-1024 characters after entities parsing

1.3. Content 47
pyTelegramBotAPI, Release 4.25.0

• parse_mode (str) – Optional. Mode for parsing entities in the audio caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the audio
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedAudio
class telebot.types.InlineQueryResultCachedBase
Bases: ABC, JsonSerializable
Base class of all InlineQueryResultCached* classes.
class telebot.types.InlineQueryResultCachedDocument(id: str, document_file_id: str, title: str,
description: str | None = None, caption: str |
None = None, caption_entities:
List[MessageEntity] | None = None,
parse_mode: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to a file stored on the Telegram servers. By default, this file will be sent by the user with an
optional caption. Alternatively, you can use input_message_content to send a message with the specified content
instead of the file.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcacheddocument
Parameters
• type (str) – Type of the result, must be document
• id (str) – Unique identifier for this result, 1-64 bytes
• title (str) – Title for the result
• document_file_id (str) – A valid file identifier for the file
• description (str) – Optional. Short description of the result
• caption (str) – Optional. Caption of the document to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the document caption. See
formatting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode

48 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard

attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the file
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedDocument
class telebot.types.InlineQueryResultCachedGif(id: str, gif_file_id: str, title: str | None = None,
description: str | None = None, caption: str | None =
None, caption_entities: List[MessageEntity] | None =
None, parse_mode: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to an animated GIF file stored on the Telegram servers. By default, this animated GIF file will
be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message
with specified content instead of the animation.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedgif
Parameters
• type (str) – Type of the result, must be gif
• id (str) – Unique identifier for this result, 1-64 bytes
• gif_file_id (str) – A valid file identifier for the GIF file
• title (str) – Optional. Title for the result
• caption (str) – Optional. Caption of the GIF file to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the caption. See formatting
options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the GIF animation
• show_caption_above_media (bool) – Optional. Pass True, if a caption is not required for
the media
Returns
Instance of the class

1.3. Content 49
pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.InlineQueryResultCachedGif
class telebot.types.InlineQueryResultCachedMpeg4Gif(id: str, mpeg4_file_id: str, title: str | None =
None, description: str | None = None, caption:
str | None = None, caption_entities:
List[MessageEntity] | None = None,
parse_mode: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None =
None)
Bases: InlineQueryResultCachedBase
Represents a link to a video animation (H.264/MPEG-4 AVC video without sound) stored on the Telegram
servers. By default, this animated MPEG-4 file will be sent by the user with an optional caption. Alternatively,
you can use input_message_content to send a message with the specified content instead of the animation.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedmpeg4gif
Parameters
• type (str) – Type of the result, must be mpeg4_gif
• id (str) – Unique identifier for this result, 1-64 bytes
• mpeg4_file_id (str) – A valid file identifier for the MPEG4 file
• title (str) – Optional. Title for the result
• caption (str) – Optional. Caption of the MPEG-4 file to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the caption. See formatting
options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the video animation
• show_caption_above_media (bool) – Optional. Pass True, if caption should be shown
above the media
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedMpeg4Gif

50 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultCachedPhoto(id: str, photo_file_id: str, title: str | None = None,

description: str | None = None, caption: str | None =
None, caption_entities: List[MessageEntity] | None
= None, parse_mode: str | None = None,
reply_markup: InlineKeyboardMarkup | None =
None, input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to a photo stored on the Telegram servers. By default, this photo will be sent by the user with an
optional caption. Alternatively, you can use input_message_content to send a message with the specified content
instead of the photo.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedphoto
Parameters
• type (str) – Type of the result, must be photo
• id (str) – Unique identifier for this result, 1-64 bytes
• photo_file_id (str) – A valid file identifier of the photo
• title (str) – Optional. Title for the result
• description (str) – Optional. Short description of the result
• caption (str) – Optional. Caption of the photo to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the photo caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the photo
• show_caption_above_media (bool) – Optional. Pass True, if a caption is not required for
the media
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedPhoto

1.3. Content 51
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultCachedSticker(id: str, sticker_file_id: str, reply_markup:

InlineKeyboardMarkup | None = None,
input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to a sticker stored on the Telegram servers. By default, this sticker will be sent by the user.
Alternatively, you can use input_message_content to send a message with the specified content instead of the
sticker.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedsticker
Parameters
• type (str) – Type of the result, must be sticker
• id (str) – Unique identifier for this result, 1-64 bytes
• sticker_file_id (str) – A valid file identifier of the sticker
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the sticker
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedSticker
class telebot.types.InlineQueryResultCachedVideo(id: str, video_file_id: str, title: str, description: str |
None = None, caption: str | None = None,
caption_entities: List[MessageEntity] | None =
None, parse_mode: str | None = None,
reply_markup: InlineKeyboardMarkup | None =
None, input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to a video file stored on the Telegram servers. By default, this video file will be sent by the user
with an optional caption. Alternatively, you can use input_message_content to send a message with the specified
content instead of the video.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedvideo
Parameters
• type (str) – Type of the result, must be video
• id (str) – Unique identifier for this result, 1-64 bytes

52 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• video_file_id (str) – A valid file identifier for the video file

• title (str) – Title for the result
• description (str) – Optional. Short description of the result
• caption (str) – Optional. Caption of the video to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the video caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the video
• show_caption_above_media (bool) – Optional. Pass True, if a caption is not required for
the media
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedVideo
class telebot.types.InlineQueryResultCachedVoice(id: str, voice_file_id: str, title: str, caption: str |
None = None, caption_entities: List[MessageEntity]
| None = None, parse_mode: str | None = None,
reply_markup: InlineKeyboardMarkup | None =
None, input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultCachedBase
Represents a link to a voice message stored on the Telegram servers. By default, this voice message will be
sent by the user. Alternatively, you can use input_message_content to send a message with the specified content
instead of the voice message.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcachedvoice
Parameters
• type (str) – Type of the result, must be voice
• id (str) – Unique identifier for this result, 1-64 bytes
• voice_file_id (str) – A valid file identifier for the voice message
• title (str) – Voice message title
• caption (str) – Optional. Caption, 0-1024 characters after entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the voice message caption. See
formatting options for more details.

1.3. Content 53
pyTelegramBotAPI, Release 4.25.0

• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-

cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the voice message
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultCachedVoice
class telebot.types.InlineQueryResultContact(id: str, phone_number: str, first_name: str, last_name:
str | None = None, vcard: str | None = None,
reply_markup: InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
thumbnail_url: str | None = None, thumbnail_width: int |
None = None, thumbnail_height: int | None = None)
Bases: InlineQueryResultBase
Represents a contact with a phone number. By default, this contact will be sent by the user. Alternatively, you
can use input_message_content to send a message with the specified content instead of the contact.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultcontact
Parameters
• type (str) – Type of the result, must be contact
• id (str) – Unique identifier for this result, 1-64 Bytes
• phone_number (str) – Contact’s phone number
• first_name (str) – Contact’s first name
• last_name (str) – Optional. Contact’s last name
• vcard (str) – Optional. Additional data about the contact in the form of a vCard, 0-2048
bytes
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the contact
• thumbnail_url (str) – Optional. Url of the thumbnail for the result
• thumbnail_width (int) – Optional. Thumbnail width
• thumbnail_height (int) – Optional. Thumbnail height
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultContact

54 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

property thumb_height: int

property thumb_url: str

property thumb_width: int

class telebot.types.InlineQueryResultDocument(id: str, title: str, document_url: str, mime_type: str,

caption: str | None = None, caption_entities:
List[MessageEntity] | None = None, parse_mode: str |
None = None, description: str | None = None,
reply_markup: InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
thumbnail_url: str | None = None, thumbnail_width: int
| None = None, thumbnail_height: int | None = None)
Bases: InlineQueryResultBase
Represents a link to a file. By default, this file will be sent by the user with an optional caption. Alternatively,
you can use input_message_content to send a message with the specified content instead of the file. Currently,
only .PDF and .ZIP files can be sent using this method.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultdocument
Parameters
• type (str) – Type of the result, must be document
• id (str) – Unique identifier for this result, 1-64 bytes
• title (str) – Title for the result
• caption (str) – Optional. Caption of the document to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the document caption. See
formatting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• document_url (str) – A valid URL for the file
• mime_type (str) – MIME type of the content of the file, either “application/pdf” or “appli-
cation/zip”
• description (str) – Optional. Short description of the result
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the file
• thumbnail_url (str) – Optional. URL of the thumbnail (JPEG only) for the file
• thumbnail_width (int) – Optional. Thumbnail width
• thumbnail_height (int) – Optional. Thumbnail height

1.3. Content 55
pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
telebot.types.InlineQueryResultDocument
property thumb_height: int

property thumb_url: str

property thumb_width: int

class telebot.types.InlineQueryResultGame(id: str, game_short_name: str, reply_markup:

InlineKeyboardMarkup | None = None)
Bases: InlineQueryResultBase
Represents a Game.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultgame
Parameters
• type (str) – Type of the result, must be game
• id (str) – Unique identifier for this result, 1-64 bytes
• game_short_name (str) – Short name of the game
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultGame
class telebot.types.InlineQueryResultGif(id: str, gif_url: str, thumbnail_url: str, gif_width: int | None =
None, gif_height: int | None = None, title: str | None = None,
caption: str | None = None, caption_entities:
List[MessageEntity] | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent |
InputContactMessageContent | InputInvoiceMessageContent |
None = None, gif_duration: int | None = None, parse_mode:
str | None = None, thumbnail_mime_type: str | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultBase
Represents a link to an animated GIF file. By default, this animated GIF file will be sent by the user with optional
caption. Alternatively, you can use input_message_content to send a message with the specified content instead
of the animation.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultgif
Parameters
• type (str) – Type of the result, must be gif
• id (str) – Unique identifier for this result, 1-64 bytes
• gif_url (str) – A valid URL for the GIF file. File size must not exceed 1MB

56 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• gif_width (int) – Optional. Width of the GIF

• gif_height (int) – Optional. Height of the GIF
• gif_duration (int) – Optional. Duration of the GIF in seconds
• thumbnail_url (str) – URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail
for the result
• thumbnail_mime_type (str) – Optional. MIME type of the thumbnail, must be one of
“image/jpeg”, “image/gif”, or “video/mp4”. Defaults to “image/jpeg”
• title (str) – Optional. Title for the result
• caption (str) – Optional. Caption of the GIF file to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the caption. See formatting
options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the GIF animation
• show_caption_above_media (bool) – Optional. If true, a caption is shown over the photo
or video
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultGif
property thumb_mime_type: str

property thumb_url: str

class telebot.types.InlineQueryResultLocation(id: str, title: str, latitude: float, longitude: float,

horizontal_accuracy: float, live_period: int | None =
None, reply_markup: InlineKeyboardMarkup | None =
None, input_message_content:
InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
thumbnail_url: str | None = None, thumbnail_width: int
| None = None, thumbnail_height: int | None = None,
heading: int | None = None, proximity_alert_radius: int
| None = None)
Bases: InlineQueryResultBase
Represents a location on a map. By default, the location will be sent by the user. Alternatively, you can use
input_message_content to send a message with the specified content instead of the location.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultlocation
Parameters

1.3. Content 57
pyTelegramBotAPI, Release 4.25.0

• type (str) – Type of the result, must be location

• id (str) – Unique identifier for this result, 1-64 Bytes
• latitude (float number) – Location latitude in degrees
• longitude (float number) – Location longitude in degrees
• title (str) – Location title
• horizontal_accuracy (float number) – Optional. The radius of uncertainty for the lo-
cation, measured in meters; 0-1500
• live_period (int) – Optional. Period in seconds during which the location can be up-
dated, should be between 60 and 86400, or 0x7FFFFFFF for live locations that can be edited
indefinitely.
• heading (int) – Optional. For live locations, a direction in which the user is moving, in
degrees. Must be between 1 and 360 if specified.
• proximity_alert_radius (int) – Optional. For live locations, a maximum distance for
proximity alerts about approaching another chat member, in meters. Must be between 1 and
100000 if specified.
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the location
• thumbnail_url (str) – Optional. Url of the thumbnail for the result
• thumbnail_width (int) – Optional. Thumbnail width
• thumbnail_height (int) – Optional. Thumbnail height
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultLocation
property thumb_height: int

property thumb_url: str

property thumb_width: int

class telebot.types.InlineQueryResultMpeg4Gif(id: str, mpeg4_url: str, thumbnail_url: str,

mpeg4_width: int | None = None, mpeg4_height: int |
None = None, title: str | None = None, caption: str |
None = None, caption_entities: List[MessageEntity] |
None = None, parse_mode: str | None = None,
reply_markup: InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent |
InputVenueMessageContent |
InputContactMessageContent |
InputInvoiceMessageContent | None = None,
mpeg4_duration: int | None = None,
thumbnail_mime_type: str | None = None,
show_caption_above_media: bool | None = None)

58 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Bases: InlineQueryResultBase
Represents a link to a video animation (H.264/MPEG-4 AVC video without sound). By default, this animated
MPEG-4 file will be sent by the user with optional caption. Alternatively, you can use input_message_content
to send a message with the specified content instead of the animation.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultmpeg4gif
Parameters
• type (str) – Type of the result, must be mpeg4_gif
• id (str) – Unique identifier for this result, 1-64 bytes
• mpeg4_url (str) – A valid URL for the MPEG4 file. File size must not exceed 1MB
• mpeg4_width (int) – Optional. Video width
• mpeg4_height (int) – Optional. Video height
• mpeg4_duration (int) – Optional. Video duration in seconds
• thumbnail_url (str) – URL of the static (JPEG or GIF) or animated (MPEG4) thumbnail
for the result
• thumbnail_mime_type (str) – Optional. MIME type of the thumbnail, must be one of
“image/jpeg”, “image/gif”, or “video/mp4”. Defaults to “image/jpeg”
• title (str) – Optional. Title for the result
• caption (str) – Optional. Caption of the MPEG-4 file to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the caption. See formatting
options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the video animation
• show_caption_above_media (bool) – Optional. If true, a caption is shown over the photo
or video
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultMpeg4Gif
property thumb_mime_type: str

property thumb_url: str

1.3. Content 59
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultPhoto(id: str, photo_url: str, thumbnail_url: str, photo_width: int |

None = None, photo_height: int | None = None, title: str |
None = None, description: str | None = None, caption: str |
None = None, caption_entities: List[MessageEntity] | None
= None, parse_mode: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent
| InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultBase
Represents a link to a photo. By default, this photo will be sent by the user with optional caption. Alternatively,
you can use input_message_content to send a message with the specified content instead of the photo.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultphoto
Parameters
• type (str) – Type of the result, must be photo
• id (str) – Unique identifier for this result, 1-64 bytes
• photo_url (str) – A valid URL of the photo. Photo must be in JPEG format. Photo size
must not exceed 5MB
• thumbnail_url (str) – URL of the thumbnail for the photo
• photo_width (int) – Optional. Width of the photo
• photo_height (int) – Optional. Height of the photo
• title (str) – Optional. Title for the result
• description (str) – Optional. Short description of the result
• caption (str) – Optional. Caption of the photo to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the photo caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the photo
• show_caption_above_media (bool) – Optional. If true, a caption is shown over the photo
or video
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultPhoto
property thumb_url: str

60 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.InlineQueryResultVenue(id: str, title: str, latitude: float, longitude: float, address:
str, foursquare_id: str | None = None, foursquare_type: str |
None = None, google_place_id: str | None = None,
google_place_type: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent
| InputContactMessageContent |
InputInvoiceMessageContent | None = None, thumbnail_url:
str | None = None, thumbnail_width: int | None = None,
thumbnail_height: int | None = None)
Bases: InlineQueryResultBase
Represents a venue. By default, the venue will be sent by the user. Alternatively, you can use in-
put_message_content to send a message with the specified content instead of the venue.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultvenue
Parameters
• type (str) – Type of the result, must be venue
• id (str) – Unique identifier for this result, 1-64 Bytes
• latitude (float) – Latitude of the venue location in degrees
• longitude (float) – Longitude of the venue location in degrees
• title (str) – Title of the venue
• address (str) – Address of the venue
• foursquare_id (str) – Optional. Foursquare identifier of the venue if known
• foursquare_type (str) – Optional. Foursquare type of the venue, if known. (For example,
“arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
• google_place_id (str) – Optional. Google Places identifier of the venue
• google_place_type (str) – Optional. Google Places type of the venue. (See supported
types.)
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the venue
• thumbnail_url (str) – Optional. Url of the thumbnail for the result
• thumbnail_width (int) – Optional. Thumbnail width
• thumbnail_height (int) – Optional. Thumbnail height
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultVenue
property thumb_height: int

property thumb_url: str

1.3. Content 61
pyTelegramBotAPI, Release 4.25.0

property thumb_width: int

class telebot.types.InlineQueryResultVideo(id: str, video_url: str, mime_type: str, thumbnail_url: str,

title: str, caption: str | None = None, caption_entities:
List[MessageEntity] | None = None, parse_mode: str | None
= None, video_width: int | None = None, video_height: int |
None = None, video_duration: int | None = None,
description: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None,
input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent
| InputContactMessageContent |
InputInvoiceMessageContent | None = None,
show_caption_above_media: bool | None = None)
Bases: InlineQueryResultBase
Represents a link to a page containing an embedded video player or a video file. By default, this video file will be
sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message
with the specified content instead of the video.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultvideo
Parameters
• type (str) – Type of the result, must be video
• id (str) – Unique identifier for this result, 1-64 bytes
• video_url (str) – A valid URL for the embedded video player or video file
• mime_type (str) – MIME type of the content of the video URL, “text/html” or “video/mp4”
• thumbnail_url (str) – URL of the thumbnail (JPEG only) for the video
• title (str) – Title for the result
• caption (str) – Optional. Caption of the video to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the video caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• video_width (int) – Optional. Video width
• video_height (int) – Optional. Video height
• video_duration (int) – Optional. Video duration in seconds
• description (str) – Optional. Short description of the result
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the video. This field is required if InlineQueryRe-
sultVideo is used to send an HTML-page as a result (e.g., a YouTube video).
• show_caption_above_media (bool) – Optional. If true, a caption is shown over the video
Returns
Instance of the class

62 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.InlineQueryResultVideo
property thumb_url: str

class telebot.types.InlineQueryResultVoice(id: str, voice_url: str, title: str, caption: str | None = None,
caption_entities: List[MessageEntity] | None = None,
parse_mode: str | None = None, voice_duration: int | None
= None, reply_markup: InlineKeyboardMarkup | None =
None, input_message_content: InputTextMessageContent |
InputLocationMessageContent | InputVenueMessageContent
| InputContactMessageContent |
InputInvoiceMessageContent | None = None)
Bases: InlineQueryResultBase
Represents a link to a voice recording in an .OGG container encoded with OPUS. By default, this voice recording
will be sent by the user. Alternatively, you can use input_message_content to send a message with the specified
content instead of the the voice message.
Telegram Documentation: https://core.telegram.org/bots/api#inlinequeryresultvoice
Parameters
• type (str) – Type of the result, must be voice
• id (str) – Unique identifier for this result, 1-64 bytes
• voice_url (str) – A valid URL for the voice recording
• title (str) – Recording title
• caption (str) – Optional. Caption, 0-1024 characters after entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the voice message caption. See
formatting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• voice_duration (int) – Optional. Recording duration in seconds
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message
• input_message_content (telebot.types.InputMessageContent) – Optional. Con-
tent of the message to be sent instead of the voice recording
Returns
Instance of the class
Return type
telebot.types.InlineQueryResultVoice
class telebot.types.InlineQueryResultsButton(text: str, web_app: WebAppInfo | None = None,
start_parameter: str | None = None)
Bases: JsonSerializable, Dictionaryable
This object represents a button to be shown above inline query results. You must use exactly one of the optional
fields.
Telegram documentation: https://core.telegram.org/bots/api#inlinequeryresultsbutton
Parameters

1.3. Content 63
pyTelegramBotAPI, Release 4.25.0

• text (str) – Label text on the button

• web_app (telebot.types.WebAppInfo) – Optional. Description of the Web App that will
be launched when the user presses the button. The Web App will be able to switch back to
the inline mode using the method web_app_switch_inline_query inside the Web App.
• start_parameter (str) – Optional. Deep-linking parameter for the /start message sent
to the bot when a user presses the button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are
allowed. Example: An inline bot that sends YouTube videos can ask the user to connect the
bot to their YouTube account to adapt search results accordingly. To do this, it displays a
‘Connect your YouTube account’ button above the results, or even before showing any. The
user presses the button, switches to a private chat with the bot and, in doing so, passes a
start parameter that instructs the bot to return an OAuth link. Once done, the bot can offer a
switch_inline button so that the user can easily return to the chat where they wanted to use
the bot’s inline capabilities.
Returns
Instance of the class
Return type
InlineQueryResultsButton
class telebot.types.InputContactMessageContent(phone_number, first_name, last_name=None,
vcard=None)
Bases: Dictionaryable
Represents the content of a contact message to be sent as the result of an inline query.
Telegram Documentation: https://core.telegram.org/bots/api#inputcontactmessagecontent
Parameters
• phone_number (str) – Contact’s phone number
• first_name (str) – Contact’s first name
• last_name (str) – Optional. Contact’s last name
• vcard (str) – Optional. Additional data about the contact in the form of a vCard, 0-2048
bytes
Returns
Instance of the class
Return type
telebot.types.InputContactMessageContent
class telebot.types.InputFile(file: str | IOBase | Path, file_name: str | None = None)
Bases: object
A class to send files through Telegram Bot API.
You need to pass a file, which should be an instance of io.IOBase or pathlib.Path, or str.
If you pass an str as a file, it will be opened and closed by the class.
Parameters
file (io.IOBase or pathlib.Path or str) – A file to send.

64 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Listing 2: Example on sending a file using this class

from telebot.types import InputFile

# Sending a file from disk

bot.send_document(
chat_id,
InputFile('/path/to/file/file.txt')
)

# Sending a file from an io.IOBase object

with open('/path/to/file/file.txt', 'rb') as f:
bot.send_document(
chat_id,
InputFile(f)
)

# Sending a file using pathlib.Path:

bot.send_document(
chat_id,
InputFile(pathlib.Path('/path/to/file/file.txt'))
)

property file: IOBase | str

File object.
property file_name: str
File name.
class telebot.types.InputInvoiceMessageContent(title: str, description: str, payload: str,
provider_token: str | None, currency: str, prices:
List[LabeledPrice], max_tip_amount: int | None =
None, suggested_tip_amounts: List[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)
Bases: Dictionaryable
Represents the content of an invoice message to be sent as the result of an inline query.
Telegram Documentation: https://core.telegram.org/bots/api#inputinvoicemessagecontent
Parameters
• title (str) – Product name, 1-32 characters
• description (str) – Product description, 1-255 characters
• payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the
user, use for your internal processes.

1.3. Content 65
pyTelegramBotAPI, Release 4.25.0

• provider_token (str or None) – Payment provider token, obtained via @BotFather; To

create invoice in stars, provide an empty token.
• currency (str) – Three-letter ISO 4217 currency code, see more on currencies
• prices (list of telebot.types.LabeledPrice) – Price breakdown, a JSON-serialized
list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• max_tip_amount (int) – Optional. The maximum accepted amount for tips in the smallest
units of the currency (integer, not float/double). For example, for a maximum tip of US$ 1.45
pass max_tip_amount = 145. See the exp parameter in currencies.json, it shows the number
of digits past the decimal point for each currency (2 for the majority of currencies). Defaults
to 0
• suggested_tip_amounts (list of int) – Optional. A JSON-serialized array of suggested
amounts of tip in the smallest units of the currency (integer, not float/double). At most 4
suggested tip amounts can be specified. The suggested tip amounts must be positive, passed
in a strictly increased order and must not exceed max_tip_amount.
• provider_data (str) – Optional. A JSON-serialized object for data about the invoice,
which will be shared with the payment provider. A detailed description of the required fields
should be provided by the payment provider.
• photo_url (str) – Optional. URL of the product photo for the invoice. Can be a photo of
the goods or a marketing image for a service.
• photo_size (int) – Optional. Photo size in bytes
• photo_width (int) – Optional. Photo width
• photo_height (int) – Optional. Photo height
• need_name (bool) – Optional. Pass True, if you require the user’s full name to complete
the order
• need_phone_number (bool) – Optional. Pass True, if you require the user’s phone number
to complete the order
• need_email (bool) – Optional. Pass True, if you require the user’s email address to com-
plete the order
• need_shipping_address (bool) – Optional. Pass True, if you require the user’s shipping
address to complete the order
• send_phone_number_to_provider (bool) – Optional. Pass True, if the user’s phone
number should be sent to provider
• send_email_to_provider (bool) – Optional. Pass True, if the user’s email address should
be sent to provider
• is_flexible (bool) – Optional. Pass True, if the final price depends on the shipping
method
Returns
Instance of the class
Return type
telebot.types.InputInvoiceMessageContent
class telebot.types.InputLocationMessageContent(latitude, longitude, horizontal_accuracy=None,
live_period=None, heading=None,
proximity_alert_radius=None)
Bases: Dictionaryable

66 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Represents the content of a location message to be sent as the result of an inline query.
Telegram Documentation: https://core.telegram.org/bots/api#inputlocationmessagecontent
Parameters
• latitude (float) – Latitude of the location in degrees
• longitude (float) – Longitude of the location in degrees
• horizontal_accuracy (float number) – Optional. The radius of uncertainty for the lo-
cation, measured in meters; 0-1500
• live_period (int) – Optional. Period in seconds during which the location can be up-
dated, should be between 60 and 86400, or 0x7FFFFFFF for live locations that can be edited
indefinitely.
• heading (int) – Optional. For live locations, a direction in which the user is moving, in
degrees. Must be between 1 and 360 if specified.
• proximity_alert_radius (int) – Optional. For live locations, a maximum distance for
proximity alerts about approaching another chat member, in meters. Must be between 1 and
100000 if specified.
Returns
Instance of the class
Return type
telebot.types.InputLocationMessageContent
class telebot.types.InputMedia(type, media, caption=None, parse_mode=None, caption_entities=None)
Bases: Dictionaryable, JsonSerializable
This object represents the content of a media message to be sent. It should be one of
• InputMediaAnimation
• InputMediaDocument
• InputMediaAudio
• InputMediaPhoto
• InputMediaVideo
class telebot.types.InputMediaAnimation(media: str | InputFile, thumbnail: str | InputFile | None = None,
caption: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None, width: int
| None = None, height: int | None = None, duration: int | None =
None, has_spoiler: bool | None = None,
show_caption_above_media: bool | None = None)
Bases: InputMedia
Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent.
Telegram Documentation: https://core.telegram.org/bots/api#inputmediaanimation
Parameters
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »

1.3. Content 67
pyTelegramBotAPI, Release 4.25.0

• thumbnail (InputFile or str) – Optional. Thumbnail of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG
format and less than 200 kB in size. A thumbnail’s width and height should not exceed
320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be
reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>”
if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More
information on Sending Files »
• caption (str) – Optional. Caption of the animation to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the animation caption. See
formatting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• width (int) – Optional. Animation width
• height (int) – Optional. Animation height
• duration (int) – Optional. Animation duration in seconds
• has_spoiler (bool) – Optional. True, if the uploaded animation is a spoiler
• show_caption_above_media (bool) – Optional. True, if the caption should be shown
above the animation
Returns
Instance of the class
Return type
telebot.types.InputMediaAnimation
property thumb: str | Any | None

class telebot.types.InputMediaAudio(media: str | InputFile, thumbnail: str | InputFile | None = None,

caption: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None, duration: int |
None = None, performer: str | None = None, title: str | None = None)
Bases: InputMedia
Represents an audio file to be treated as music to be sent.
Telegram Documentation: https://core.telegram.org/bots/api#inputmediaaudio
Parameters
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »
• thumbnail (InputFile or str) – Optional. Thumbnail of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG
format and less than 200 kB in size. A thumbnail’s width and height should not exceed
320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be
reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>”
if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More
information on Sending Files »

68 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• caption (str) – Optional. Caption of the audio to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the audio caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• duration (int) – Optional. Duration of the audio in seconds
• performer (str) – Optional. Performer of the audio
• title (str) – Optional. Title of the audio
Returns
Instance of the class
Return type
telebot.types.InputMediaAudio
property thumb: str | Any | None

class telebot.types.InputMediaDocument(media: str | InputFile, thumbnail: str | InputFile | None = None,

caption: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None,
disable_content_type_detection: bool | None = None)
Bases: InputMedia
Represents a general file to be sent.
Telegram Documentation: https://core.telegram.org/bots/api#inputmediadocument
Parameters
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »
• thumbnail (InputFile or str) – Optional. Thumbnail of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG
format and less than 200 kB in size. A thumbnail’s width and height should not exceed
320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be
reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>”
if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More
information on Sending Files »
• caption (str) – Optional. Caption of the document to be sent, 0-1024 characters after
entities parsing
• parse_mode (str) – Optional. Mode for parsing entities in the document caption. See
formatting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• disable_content_type_detection (bool) – Optional. Disables automatic server-side
content type detection for files uploaded using multipart/form-data. Always True, if the
document is sent as part of an album.
Returns
Instance of the class

1.3. Content 69
pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.InputMediaDocument
property thumb: str | Any | None

class telebot.types.InputMediaPhoto(media: str | InputFile, caption: str | None = None, parse_mode: str |
None = None, caption_entities: List[MessageEntity] | None = None,
has_spoiler: bool | None = None, show_caption_above_media: bool |
None = None)
Bases: InputMedia
Represents a photo to be sent.
Telegram Documentation: https://core.telegram.org/bots/api#inputmediaphoto
Parameters
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »
• caption (str) – Optional. Caption of the photo to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the photo caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• has_spoiler (bool) – Optional. True, if the uploaded photo is a spoiler
• show_caption_above_media (bool) – Optional. True, if the caption should be shown
above the photo
Returns
Instance of the class
Return type
telebot.types.InputMediaPhoto
class telebot.types.InputMediaVideo(media: str | InputFile, thumbnail: str | InputFile | None = None,
caption: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None, width: int |
None = None, height: int | None = None, duration: int | None = None,
supports_streaming: bool | None = None, has_spoiler: bool | None =
None, show_caption_above_media: bool | None = None)
Bases: InputMedia
Represents a video to be sent.
Telegram Documentation: https://core.telegram.org/bots/api#inputmediavideo
Parameters
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »

70 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• thumbnail (InputFile or str) – Optional. Thumbnail of the file sent; can be ignored if
thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG
format and less than 200 kB in size. A thumbnail’s width and height should not exceed
320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can’t be
reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>”
if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More
information on Sending Files »
• caption (str) – Optional. Caption of the video to be sent, 0-1024 characters after entities
parsing
• parse_mode (str) – Optional. Mode for parsing entities in the video caption. See format-
ting options for more details.
• caption_entities (list of telebot.types.MessageEntity) – Optional. List of spe-
cial entities that appear in the caption, which can be specified instead of parse_mode
• width (int) – Optional. Video width
• height (int) – Optional. Video height
• duration (int) – Optional. Video duration in seconds
• supports_streaming (bool) – Optional. Pass True, if the uploaded video is suitable for
streaming
• has_spoiler (bool) – Optional. True, if the uploaded video is a spoiler
• show_caption_above_media (bool) – Optional. True, if the caption should be shown
above the video
Returns
Instance of the class
Return type
telebot.types.InputMediaVideo
property thumb: str | Any | None

class telebot.types.InputPaidMedia(type: str, media: str | InputFile, **kwargs)

Bases: JsonSerializable
This object describes the paid media to be sent. Currently, it can be one of
InputPaidMediaPhoto InputPaidMediaVideo
Telegram documentation: https://core.telegram.org/bots/api#inputpaidmedia
Returns
Instance of the class
Return type
InputPaidMediaPhoto or InputPaidMediaVideo
to_dict()

class telebot.types.InputPaidMediaPhoto(media: str | InputFile, **kwargs)

Bases: InputPaidMedia
The paid media to send is a photo.
Telegram documentation: https://core.telegram.org/bots/api#inputpaidmediaphoto
Parameters

1.3. Content 71
pyTelegramBotAPI, Release 4.25.0

• type (str) – Type of the media, must be photo

• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »
Returns
Instance of the class
Return type
InputPaidMediaPhoto
class telebot.types.InputPaidMediaVideo(media: str | InputFile, thumbnail: InputFile | None = None,
width: int | None = None, height: int | None = None, duration:
int | None = None, supports_streaming: bool | None = None,
**kwargs)
Bases: InputPaidMedia
The paid media to send is a video.
Telegram documentation: https://core.telegram.org/bots/api#inputpaidmediavideo
Parameters
• type (str) – Type of the media, must be video
• media (str) – File to send. Pass a file_id to send a file that exists on the Telegram
servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet,
or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under
<file_attach_name> name. More information on Sending Files »
• thumbnail (InputFile) – Optional. Thumbnail of the file sent; can be ignored if thumbnail
generation for the file is supported server-side. The thumbnail should be in JPEG format and
less than 200 kB in size. A thumbnail’s width and height should not exceed 320. Ignored if
the file is not uploaded using multipart/form-data. Thumbnails can’t be reused and can be
only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail
was uploaded using multipart/form-data under <file_attach_name>. More information on
Sending Files »
• width (int) – Optional. Video width
• height (int) – Optional. Video height
• duration (int) – Optional. Video duration in seconds
• supports_streaming (bool) – Optional. Pass True if the uploaded video is suitable for
streaming
Returns
Instance of the class
Return type
InputPaidMediaVideo
to_dict()

class telebot.types.InputPollOption(text: str, text_parse_mode: str | None = None, text_entities:

List[MessageEntity] | None = None, **kwargs)
Bases: JsonSerializable
This object contains information about one answer option in a poll to send.

72 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Telegram Documentation: https://core.telegram.org/bots/api#inputpolloption

Parameters
• text (str) – Option text, 1-100 characters
• text_parse_mode (str) – Optional. Mode for parsing entities in the text. See formatting
options for more details. Currently, only custom emoji entities are allowed
• text_entities (list of telebot.types.MessageEntity) – Optional. A JSON-
serialized list of special entities that appear in the poll option text. It can be specified instead
of text_parse_mode
Returns
Instance of the class
Return type
telebot.types.PollOption
to_dict()

class telebot.types.InputSticker(sticker: str | InputFile, emoji_list: List[str], format: str | None = None,
mask_position: MaskPosition | None = None, keywords: List[str] | None
= None)
Bases: Dictionaryable, JsonSerializable
This object describes a sticker to be added to a sticker set.
Parameters
• sticker (str or telebot.types.InputFile) – The added sticker. Pass a file_id as a
String to send a file that already exists on the Telegram servers, pass an HTTP URL as a
String for Telegram to get a file from the Internet, or upload a new one using multipart/form-
data. Animated and video stickers can’t be uploaded via HTTP URL.
• emoji_list (list of str) – One or more(up to 20) emoji(s) corresponding to the sticker
• mask_position (telebot.types.MaskPosition) – Optional. Position where the mask
should be placed on faces. For “mask” stickers only.
• keywords (list of str) – Optional. List of 0-20 search keywords for the sticker with total
length of up to 64 characters. For “regular” and “custom_emoji” stickers only.
• format (str) – Format of the added sticker, must be one of “static” for a .WEBP or .PNG
image, “animated” for a .TGS animation, “video” for a WEBM video
Returns
Instance of the class
Return type
telebot.types.InputSticker
convert_input_sticker() → Tuple[str, dict | None]

class telebot.types.InputTextMessageContent(message_text: str, parse_mode: str | None = None, entities:

List[MessageEntity] | None = None,
disable_web_page_preview: bool | None = None,
link_preview_options: LinkPreviewOptions | None =
None)
Bases: Dictionaryable
Represents the content of a text message to be sent as the result of an inline query.

1.3. Content 73
pyTelegramBotAPI, Release 4.25.0

Telegram Documentation: https://core.telegram.org/bots/api#inputtextmessagecontent

Parameters
• message_text (str) – Text of the message to be sent, 1-4096 characters
• parse_mode (str) – Optional. Mode for parsing entities in the message text. See formatting
options for more details.
• entities (list of telebot.types.MessageEntity) – Optional. List of special entities
that appear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (bool) – deprecated
• link_preview_options (telebot.types.LinkPreviewOptions) – Optional. Link
preview generation options for the message
Returns
Instance of the class
Return type
telebot.types.InputTextMessageContent
class telebot.types.InputVenueMessageContent(latitude, longitude, title, address, foursquare_id=None,
foursquare_type=None, google_place_id=None,
google_place_type=None)
Bases: Dictionaryable
Represents the content of a venue message to be sent as the result of an inline query.
Telegram Documentation: https://core.telegram.org/bots/api#inputvenuemessagecontent
Parameters
• latitude (float) – Latitude of the venue in degrees
• longitude (float) – Longitude of the venue in degrees
• title (str) – Name of the venue
• address (str) – Address of the venue
• foursquare_id (str) – Optional. Foursquare identifier of the venue, if known
• foursquare_type (str) – Optional. Foursquare type of the venue, if known. (For example,
“arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
• google_place_id (str) – Optional. Google Places identifier of the venue
• google_place_type (str) – Optional. Google Places type of the venue. (See supported
types.)
Returns
Instance of the class
Return type
telebot.types.InputVenueMessageContent
class telebot.types.Invoice(title, description, start_parameter, currency, total_amount, **kwargs)
Bases: JsonDeserializable
This object contains basic information about an invoice.
Telegram Documentation: https://core.telegram.org/bots/api#invoice
Parameters

74 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• title (str) – Product name

• description (str) – Product description
• start_parameter (str) – Unique bot deep-linking parameter that can be used to generate
this invoice
• currency (str) – Three-letter ISO 4217 currency code
• total_amount (int) – Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp pa-
rameter in currencies.json, it shows the number of digits past the decimal point for each
currency (2 for the majority of currencies).
Returns
Instance of the class
Return type
telebot.types.Invoice
class telebot.types.JsonDeserializable
Bases: object
Subclasses of this class are guaranteed to be able to be created from a json-style dict or json formatted string.
All subclasses of this class must override de_json.
class telebot.types.JsonSerializable
Bases: object
Subclasses of this class are guaranteed to be able to be converted to JSON format. All subclasses of this class
must override to_json.
class telebot.types.KeyboardButton(text: str, request_contact: bool | None = None, request_location: bool |
None = None, request_poll: KeyboardButtonPollType | None = None,
web_app: WebAppInfo | None = None, request_user:
KeyboardButtonRequestUser | None = None, request_chat:
KeyboardButtonRequestChat | None = None, request_users:
KeyboardButtonRequestUsers | None = None)
Bases: Dictionaryable, JsonSerializable
This object represents one button of the reply keyboard. For simple text buttons String can be used instead of this
object to specify text of the button. Optional fields web_app, request_contact, request_location, and request_poll
are mutually exclusive.
Telegram Documentation: https://core.telegram.org/bots/api#keyboardbutton
Parameters
• text (str) – Text of the button. If none of the optional fields are used, it will be sent as a
message when the button is pressed
• request_contact (bool) – Optional. If True, the user’s phone number will be sent as a
contact when the button is pressed. Available in private chats only.
• request_location (bool) – Optional. If True, the user’s current location will be sent
when the button is pressed. Available in private chats only.
• request_poll (telebot.types.KeyboardButtonPollType) – Optional. If specified,
the user will be asked to create a poll and send it to the bot when the button is pressed.
Available in private chats only.

1.3. Content 75
pyTelegramBotAPI, Release 4.25.0

• web_app (telebot.types.WebAppInfo) – Optional. If specified, the described Web

App will be launched when the button is pressed. The Web App will be able to send a
“web_app_data” service message. Available in private chats only.
• request_user (telebot.types.KeyboardButtonRequestUser) – deprecated
• request_users (telebot.types.KeyboardButtonRequestUsers) – Optional. If
specified, pressing the button will open a list of suitable users. Identifiers of selected users
will be sent to the bot in a “users_shared” service message. Available in private chats only.
• request_chat (telebot.types.KeyboardButtonRequestChat) – Optional. If speci-
fied, pressing the button will open a list of suitable chats. Tapping on a chat will send its
identifier to the bot in a “chat_shared” service message. Available in private chats only.
Returns
Instance of the class
Return type
telebot.types.KeyboardButton
class telebot.types.KeyboardButtonPollType(type=None)
Bases: Dictionaryable
This object represents type of a poll, which is allowed to be created and sent when the corresponding button is
pressed.
Telegram Documentation: https://core.telegram.org/bots/api#keyboardbuttonpolltype
Parameters
type (str) – Optional. If quiz is passed, the user will be allowed to create only polls in the quiz
mode. If regular is passed, only regular polls will be allowed. Otherwise, the user will be allowed
to create a poll of any type.
Returns
Instance of the class
Return type
telebot.types.KeyboardButtonPollType
class telebot.types.KeyboardButtonRequestChat(request_id: int, chat_is_channel: bool, chat_is_forum:
bool | None = None, chat_has_username: bool | None =
None, chat_is_created: bool | None = None,
user_administrator_rights: ChatAdministratorRights |
None = None, bot_administrator_rights:
ChatAdministratorRights | None = None,
bot_is_member: bool | None = None, request_title: bool
| None = None, request_photo: bool | None = None,
request_username: bool | None = None)
Bases: Dictionaryable
This object defines the criteria used to request a suitable chat. The identifier of the selected chat will be shared
with the bot when the corresponding button is pressed.
Telegram documentation: https://core.telegram.org/bots/api#keyboardbuttonrequestchat
Parameters
• request_id (int) – Signed 32-bit identifier of the request, which will be received back in
the ChatShared object. Must be unique within the message
• chat_is_channel (bool) – Pass True to request a channel chat, pass False to request a
group or a supergroup chat.

76 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• chat_is_forum (bool) – Optional. Pass True to request a forum supergroup, pass False to
request a non-forum chat. If not specified, no additional restrictions are applied.
• chat_has_username (bool) – Optional. Pass True to request a supergroup or a channel
with a username, pass False to request a chat without a username. If not specified, no addi-
tional restrictions are applied.
• chat_is_created (bool) – Optional. Pass True to request a chat owned by the user. Oth-
erwise, no additional restrictions are applied.
• user_administrator_rights (telebot.types.ChatAdministratorRights) – Op-
tional. A JSON-serialized object listing the required administrator rights of the user in the
chat. The rights must be a superset of bot_administrator_rights. If not specified, no addi-
tional restrictions are applied.
• bot_administrator_rights (telebot.types.ChatAdministratorRights) – Op-
tional. A JSON-serialized object listing the required administrator rights of the bot in the
chat. The rights must be a subset of user_administrator_rights. If not specified, no additional
restrictions are applied.
• bot_is_member (bool) – Optional. Pass True to request a chat where the bot is a member.
Otherwise, no additional restrictions are applied.
• request_title (bool) – Optional. Request title
• request_photo (bool) – Optional. Request photo
• request_username (bool) – Optional. Request username
Returns
Instance of the class
Return type
telebot.types.KeyboardButtonRequestChat
class telebot.types.KeyboardButtonRequestUser(request_id: int, user_is_bot: bool | None = None,
user_is_premium: bool | None = None, max_quantity:
int | None = None)
Bases: KeyboardButtonRequestUsers
Deprecated. Use KeyboardButtonRequestUsers instead.
class telebot.types.KeyboardButtonRequestUsers(request_id: int, user_is_bot: bool | None = None,
user_is_premium: bool | None = None, max_quantity:
int | None = None, request_name: bool | None = None,
request_username: bool | None = None, request_photo:
bool | None = None)
Bases: Dictionaryable
This object defines the criteria used to request a suitable user. The identifier of the selected user will be shared
with the bot when the corresponding button is pressed.
Telegram documentation: https://core.telegram.org/bots/api#keyboardbuttonrequestusers
Parameters
• request_id (int) – Signed 32-bit identifier of the request, which will be received back in
the UsersShared object. Must be unique within the message
• user_is_bot (bool) – Optional. Pass True to request a bot, pass False to request a regular
user. If not specified, no additional restrictions are applied.

1.3. Content 77
pyTelegramBotAPI, Release 4.25.0

• user_is_premium (bool) – Optional. Pass True to request a premium user, pass False to
request a non-premium user. If not specified, no additional restrictions are applied.
• max_quantity (int) – Optional. The maximum number of users to be selected; 1-10.
Defaults to 1.
• request_name (bool) – Optional. Request name
• request_username (bool) – Optional. Request username
• request_photo (bool) – Optional. Request photo
Returns
Instance of the class
Return type
telebot.types.KeyboardButtonRequestUsers
class telebot.types.LabeledPrice(label, amount)
Bases: JsonSerializable, Dictionaryable
This object represents a portion of the price for goods or services.
Telegram Documentation: https://core.telegram.org/bots/api#labeledprice
Parameters
• label (str) – Portion label
• amount (int) – Price of the product in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp pa-
rameter in currencies.json, it shows the number of digits past the decimal point for each
currency (2 for the majority of currencies).
Returns
Instance of the class
Return type
telebot.types.LabeledPrice
class telebot.types.LinkPreviewOptions(is_disabled: bool | None = None, url: str | None = None,
prefer_small_media: bool | None = None, prefer_large_media:
bool | None = None, show_above_text: bool | None = None,
**kwargs)
Bases: JsonDeserializable, Dictionaryable, JsonSerializable
Describes the options used for link preview generation.
Telegram documentation: https://core.telegram.org/bots/api#linkpreviewoptions
Parameters
• is_disabled (bool) – Optional. True, if the link preview is disabled
• url (str) – Optional. URL to use for the link preview. If empty, then the first URL found
in the message text will be used
• prefer_small_media (bool) – Optional. True, if the media in the link preview is supposed
to be shrunk; ignored if the URL isn’t explicitly specified or media size change isn’t supported
for the preview
• prefer_large_media (bool) – Optional. True, if the media in the link preview is sup-
posed to be enlarged; ignored if the URL isn’t explicitly specified or media size change isn’t
supported for the preview

78 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• show_above_text (bool) – Optional. True, if the link preview must be shown above the
message text; otherwise, the link preview will be shown below the message text
Returns
Instance of the class
Return type
LinkPreviewOptions
class telebot.types.Location(longitude, latitude, horizontal_accuracy=None, live_period=None,
heading=None, proximity_alert_radius=None, **kwargs)
Bases: JsonDeserializable, JsonSerializable, Dictionaryable
This object represents a point on the map.
Telegram Documentation: https://core.telegram.org/bots/api#location
Parameters
• longitude (float) – Longitude as defined by sender
• latitude (float) – Latitude as defined by sender
• horizontal_accuracy (float number) – Optional. The radius of uncertainty for the lo-
cation, measured in meters; 0-1500
• live_period (int) – Optional. Time relative to the message sending date, during which
the location can be updated; in seconds. For active live locations only.
• heading (int) – Optional. The direction in which user is moving, in degrees; 1-360. For
active live locations only.
• proximity_alert_radius (int) – Optional. The maximum distance for proximity alerts
about approaching another chat member, in meters. For sent live locations only.
Returns
Instance of the class
Return type
telebot.types.Location
class telebot.types.LoginUrl(url: str, forward_text: str | None = None, bot_username: str | None = None,
request_write_access: bool | None = None, **kwargs)
Bases: Dictionaryable, JsonSerializable, JsonDeserializable
This object represents a parameter of the inline keyboard button used to automatically authorize a user. Serves as
a great replacement for the Telegram Login Widget when the user is coming from Telegram. All the user needs
to do is tap/click a button and confirm that they want to log in:
Telegram Documentation: https://core.telegram.org/bots/api#loginurl
Parameters
• url (str) – An HTTPS URL to be opened with user authorization data added to the query
string when the button is pressed. If the user refuses to provide authorization data, the orig-
inal URL without information about the user will be opened. The data added is the same
as described in Receiving authorization data. NOTE: You must always check the hash of
the received data to verify the authentication and the integrity of the data as described in
Checking authorization.
• forward_text (str) – Optional. New text of the button in forwarded messages.

1.3. Content 79
pyTelegramBotAPI, Release 4.25.0

• bot_username (str) – Optional. Username of a bot, which will be used for user autho-
rization. See Setting up a bot for more details. If not specified, the current bot’s username
will be assumed. The url’s domain must be the same as the domain linked with the bot. See
Linking your domain to the bot for more details.
• request_write_access (bool) – Optional. Pass True to request the permission for your
bot to send messages to the user.
Returns
Instance of the class
Return type
telebot.types.LoginUrl
class telebot.types.MaskPosition(point, x_shift, y_shift, scale, **kwargs)
Bases: Dictionaryable, JsonDeserializable, JsonSerializable
This object describes the position on faces where a mask should be placed by default.
Telegram Documentation: https://core.telegram.org/bots/api#maskposition
Parameters
• point (str) – The part of the face relative to which the mask should be placed. One of
“forehead”, “eyes”, “mouth”, or “chin”.
• x_shift (float number) – Shift by X-axis measured in widths of the mask scaled to the
face size, from left to right. For example, choosing -1.0 will place mask just to the left of the
default mask position.
• y_shift (float number) – Shift by Y-axis measured in heights of the mask scaled to the
face size, from top to bottom. For example, 1.0 will place the mask just below the default
mask position.
• scale (float number) – Mask scaling coefficient. For example, 2.0 means double size.
Returns
Instance of the class
Return type
telebot.types.MaskPosition
class telebot.types.MenuButton
Bases: JsonDeserializable, JsonSerializable, Dictionaryable
This object describes the bot’s menu button in a private chat. It should be one of
• MenuButtonCommands
• MenuButtonWebApp
• MenuButtonDefault
If a menu button other than MenuButtonDefault is set for a private chat, then it is applied in the chat. Otherwise
the default menu button is applied. By default, the menu button opens the list of bot commands.
class telebot.types.MenuButtonCommands(type: str = None, **kwargs)
Bases: MenuButton
Represents a menu button, which opens the bot’s list of commands.
Telegram Documentation: https://core.telegram.org/bots/api#menubuttoncommands
Parameters
type (str) – Type of the button, must be commands

80 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
telebot.types.MenuButtonCommands
class telebot.types.MenuButtonDefault(type: str = None, **kwargs)
Bases: MenuButton
Describes that no specific value for the menu button was set.
Telegram Documentation: https://core.telegram.org/bots/api#menubuttondefault
Parameters
type (str) – Type of the button, must be default
Returns
Instance of the class
Return type
telebot.types.MenuButtonDefault
class telebot.types.MenuButtonWebApp(type: str, text: str, web_app: WebAppInfo, **kwargs)
Bases: MenuButton
Represents a menu button, which launches a Web App.
Telegram Documentation: https://core.telegram.org/bots/api#menubuttonwebapp
Parameters
• type (str) – Type of the button, must be web_app
• text (str) – Text on the button
• web_app (telebot.types.WebAppInfo) – Description of the Web App that will be
launched when the user presses the button. The Web App will be able to send an arbitrary
message on behalf of the user using the method answerWebAppQuery. Alternatively, a t.me
link to a Web App of the bot can be specified in the object instead of the Web App’s URL,
in which case the Web App will be opened as if the user pressed the link.
Returns
Instance of the class
Return type
telebot.types.MenuButtonWebApp
class telebot.types.Message(message_id, from_user, date, chat, content_type, options, json_string)
Bases: JsonDeserializable
This object represents a message.
Telegram Documentation: https://core.telegram.org/bots/api#message
Parameters
• message_id (int) – Unique message identifier inside this chat
• message_thread_id (int) – Optional. Unique identifier of a message thread to which the
message belongs; for supergroups only
• from_user (telebot.types.User) – Optional. Sender of the message; empty for mes-
sages sent to channels. For backward compatibility, the field contains a fake sender user in
non-channel chats, if the message was sent on behalf of a chat.

1.3. Content 81
pyTelegramBotAPI, Release 4.25.0

• sender_chat (telebot.types.Chat) – Optional. Sender of the message, sent on behalf

of a chat. For example, the channel itself for channel posts, the supergroup itself for mes-
sages from anonymous group administrators, the linked channel for messages automatically
forwarded to the discussion group. For backward compatibility, the field from contains a
fake sender user in non-channel chats, if the message was sent on behalf of a chat.
• sender_boost_count (int) – Optional. If the sender of the message boosted the chat, the
number of boosts added by the user
• info (sender_business_bot) – Optional. Information about the business bot that sent
the message
• date (int) – Date the message was sent in Unix time
• business_connection_id (str) – Optional. Unique identifier of the business connection
from which the message was received. If non-empty, the message belongs to a chat of the
corresponding business account that is independent from any potential bot chat which might
share the same identifier.
• chat (telebot.types.Chat) – Conversation the message belongs to
• is_topic_message (bool) – Optional. True, if the message is sent to a forum topic
• is_automatic_forward (bool) – Optional. bool, if the message is a channel post that
was automatically forwarded to the connected discussion group
• reply_to_message (telebot.types.Message) – Optional. For replies, the original mes-
sage. Note that the Message object in this field will not contain further reply_to_message
fields even if it itself is a reply.
• external_reply (telebot.types.ExternalReplyInfo) – Optional. Information
about the message that is being replied to, which may come from another chat or forum
topic
• quote (telebot.types.TextQuote) – Optional. For replies that quote part of the original
message, the quoted part of the message
• reply_to_story (telebot.types.Story) – Optional. For replies to a story, the original
story
• via_bot (telebot.types.User) – Optional. Bot through which the message was sent
• edit_date (int) – Optional. Date the message was last edited in Unix time
• has_protected_content (bool) – Optional. bool, if the message can’t be forwarded
• is_from_offline (bool) – Optional. True, if the message was sent by an implicit action,
for example, as an away or a greeting business message, or as a scheduled message
• media_group_id (str) – Optional. The unique identifier of a media message group this
message belongs to
• author_signature (str) – Optional. Signature of the post author for messages in chan-
nels, or the custom title of an anonymous group administrator
• text (str) – Optional. For text messages, the actual UTF-8 text of the message
• entities (list of telebot.types.MessageEntity) – Optional. For text messages, spe-
cial entities like usernames, URLs, bot commands, etc. that appear in the text
• link_preview_options (telebot.types.LinkPreviewOptions) – Optional. Options
used for link preview generation for the message, if it is a text message and link preview
options were changed

82 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• effect_id (str) – Optional. Unique identifier of the message effect added to the message
• animation (telebot.types.Animation) – Optional. Message is an animation, informa-
tion about the animation. For backward compatibility, when this field is set, the document
field will also be set
• audio (telebot.types.Audio) – Optional. Message is an audio file, information about
the file
• document (telebot.types.Document) – Optional. Message is a general file, information
about the file
• paid_media (telebot.types.PaidMediaInfo) – Optional. Message contains paid me-
dia; information about the paid media
• photo (list of telebot.types.PhotoSize) – Optional. Message is a photo, available
sizes of the photo
• sticker (telebot.types.Sticker) – Optional. Message is a sticker, information about
the sticker
• story (telebot.types.Story) – Optional. Message is a forwarded story
• video (telebot.types.Video) – Optional. Message is a video, information about the
video
• video_note (telebot.types.VideoNote) – Optional. Message is a video note, informa-
tion about the video message
• voice (telebot.types.Voice) – Optional. Message is a voice message, information
about the file
• caption (str) – Optional. Caption for the animation, audio, document, photo, video or
voice
• caption_entities (list of telebot.types.MessageEntity) – Optional. For mes-
sages with a caption, special entities like usernames, URLs, bot commands, etc. that appear
in the caption
• show_caption_above_media (bool) – Optional. True, if the caption must be shown above
the message media
• has_media_spoiler (bool) – Optional. True, if the message media is covered by a spoiler
animation
• contact (telebot.types.Contact) – Optional. Message is a shared contact, information
about the contact
• dice (telebot.types.Dice) – Optional. Message is a dice with random value
• game (telebot.types.Game) – Optional. Message is a game, information about the game.
More about games »
• poll (telebot.types.Poll) – Optional. Message is a native poll, information about the
poll
• venue (telebot.types.Venue) – Optional. Message is a venue, information about the
venue. For backward compatibility, when this field is set, the location field will also be set
• location (telebot.types.Location) – Optional. Message is a shared location, infor-
mation about the location

1.3. Content 83
pyTelegramBotAPI, Release 4.25.0

• new_chat_members (list of telebot.types.User) – Optional. New members that were

added to the group or supergroup and information about them (the bot itself may be one of
these members)
• left_chat_member (telebot.types.User) – Optional. A member was removed from
the group, information about them (this member may be the bot itself)
• new_chat_title (str) – Optional. A chat title was changed to this value
• new_chat_photo (list of telebot.types.PhotoSize) – Optional. A chat photo was
change to this value
• delete_chat_photo (bool) – Optional. Service message: the chat photo was deleted
• group_chat_created (bool) – Optional. Service message: the group has been created
• supergroup_chat_created (bool) – Optional. Service message: the supergroup has been
created. This field can’t be received in a message coming through updates, because bot can’t
be a member of a supergroup when it is created. It can only be found in reply_to_message
if someone replies to a very first message in a directly created supergroup.
• channel_chat_created (bool) – Optional. Service message: the channel has been cre-
ated. This field can’t be received in a message coming through updates, because bot can’t
be a member of a channel when it is created. It can only be found in reply_to_message if
someone replies to a very first message in a channel.
• message_auto_delete_timer_changed (telebot.types.
MessageAutoDeleteTimerChanged) – Optional. Service message: auto-delete timer
settings changed in the chat
• migrate_to_chat_id (int) – Optional. The group has been migrated to a supergroup
with the specified identifier. This number may have more than 32 significant bits and some
programming languages may have difficulty/silent defects in interpreting it. But it has at
most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for
storing this identifier.
• migrate_from_chat_id (int) – Optional. The supergroup has been migrated from a
group with the specified identifier. This number may have more than 32 significant bits
and some programming languages may have difficulty/silent defects in interpreting it. But it
has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are
safe for storing this identifier.
• pinned_message (telebot.types.Message or telebot.types.
InaccessibleMessage) – Optional. Specified message was pinned. Note that the
Message object in this field will not contain further reply_to_message fields even if it is
itself a reply.
• invoice (telebot.types.Invoice) – Optional. Message is an invoice for a payment,
information about the invoice. More about payments »
• successful_payment (telebot.types.SuccessfulPayment) – Optional. Message is
a service message about a successful payment, information about the payment. More about
payments »
• refunded_payment (telebot.types.RefundedPayment) – Optional. Message is a ser-
vice message about a refunded payment, information about the payment. More about pay-
ments »
• users_shared (telebot.types.UsersShared) – Optional. Service message: a user was
shared with the bot

84 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• chat_shared (telebot.types.ChatShared) – Optional. Service message: a chat was

shared with the bot
• connected_website (str) – Optional. The domain name of the website on which the user
has logged in. More about Telegram Login »
• write_access_allowed (telebot.types.WriteAccessAllowed) – Optional. Service
message: the user allowed the bot added to the attachment menu to write messages
• passport_data (telebot.types.PassportData) – Optional. Telegram Passport data
• proximity_alert_triggered (telebot.types.ProximityAlertTriggered) – Op-
tional. Service message. A user in the chat triggered another user’s proximity alert while
sharing Live Location.
• boost_added (telebot.types.ChatBoostAdded) – Optional. Service message: user
boosted the chat
• chat_background_set (telebot.types.ChatBackground) – Optional. Service mes-
sage: chat background set
• forum_topic_created (telebot.types.ForumTopicCreated) – Optional. Service
message: forum topic created
• forum_topic_edited (telebot.types.ForumTopicEdited) – Optional. Service mes-
sage: forum topic edited
• forum_topic_closed (telebot.types.ForumTopicClosed) – Optional. Service mes-
sage: forum topic closed
• forum_topic_reopened (telebot.types.ForumTopicReopened) – Optional. Service
message: forum topic reopened
• general_forum_topic_hidden (telebot.types.GeneralForumTopicHidden) – Op-
tional. Service message: the ‘General’ forum topic hidden
• general_forum_topic_unhidden (telebot.types.GeneralForumTopicUnhidden)
– Optional. Service message: the ‘General’ forum topic unhidden
• giveaway_created (telebot.types.GiveawayCreated) – Optional. Service message:
a giveaway has been created
• giveaway (telebot.types.Giveaway) – Optional. The message is a scheduled giveaway
message
• giveaway_winners (telebot.types.GiveawayWinners) – Optional. Service message:
giveaway winners(public winners)
• giveaway_completed (telebot.types.GiveawayCompleted) – Optional. Service
message: giveaway completed, without public winners
• video_chat_scheduled (telebot.types.VideoChatScheduled) – Optional. Service
message: video chat scheduled
• video_chat_started (telebot.types.VideoChatStarted) – Optional. Service mes-
sage: video chat started
• video_chat_ended (telebot.types.VideoChatEnded) – Optional. Service message:
video chat ended
• video_chat_participants_invited (telebot.types.
VideoChatParticipantsInvited) – Optional. Service message: new participants
invited to a video chat

1.3. Content 85
pyTelegramBotAPI, Release 4.25.0

• web_app_data (telebot.types.WebAppData) – Optional. Service message: data sent

by a Web App
• reply_markup (telebot.types.InlineKeyboardMarkup) – Optional. Inline keyboard
attached to the message. login_url buttons are represented as ordinary url buttons.
Forward_origin
Optional. For forwarded messages, information about the original message;
Returns
Instance of the class
Return type
telebot.types.Message
property any_entities: List[MessageEntity] | None

property any_text: str | None

property forward_date

property forward_from

property forward_from_chat

property forward_from_message_id

property forward_sender_name

property forward_signature

property html_caption: str | None

Returns html-rendered caption.
property html_text: str | None
Returns html-rendered text.
property new_chat_member

classmethod parse_chat(chat) → User | GroupChat

Parses chat.
classmethod parse_entities(message_entity_array) → List[MessageEntity]
Parses message entity array.
classmethod parse_photo(photo_size_array) → List[PhotoSize]
Parses photo array.
property user_shared

property voice_chat_ended

property voice_chat_participants_invited

property voice_chat_scheduled

property voice_chat_started

86 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.MessageAutoDeleteTimerChanged(message_auto_delete_time, **kwargs)

Bases: JsonDeserializable
This object represents a service message about a change in auto-delete timer settings.
Telegram Documentation: https://core.telegram.org/bots/api#messageautodeletetimerchanged
Parameters
message_auto_delete_time (int) – New auto-delete time for messages in the chat; in seconds
Returns
Instance of the class
Return type
telebot.types.MessageAutoDeleteTimerChanged
class telebot.types.MessageEntity(type, offset, length, url=None, user=None, language=None,
custom_emoji_id=None, **kwargs)
Bases: Dictionaryable, JsonSerializable, JsonDeserializable
This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc.
Telegram Documentation: https://core.telegram.org/bots/api#messageentity
Parameters
• type (str) – Type of the entity. Currently, can be “mention” (@username), “hashtag”
(#hashtag or #hashtag@chatusername), “cashtag” ($USD or $USD@chatusername),
“bot_command” (/start@jobs_bot), “url” (https://telegram.org), “email” (do-not-
reply@telegram.org), “phone_number” (+1-212-555-0123), “bold” (bold text), “italic”
(italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler”
(spoiler message), “blockquote” (block quotation), “expandable_blockquote” (collapsed-by-
default block quotation), “code” (monowidth string), “pre” (monowidth block), “text_link”
(for clickable text URLs), “text_mention” (for users without usernames), “custom_emoji”
(for inline custom emoji stickers)
• offset (int) – Offset in UTF-16 code units to the start of the entity
• length (int) – Length of the entity in UTF-16 code units
• url (str) – Optional. For “text_link” only, URL that will be opened after user taps on the
text
• user (telebot.types.User) – Optional. For “text_mention” only, the mentioned user
• language (str) – Optional. For “pre” only, the programming language of the entity text
• custom_emoji_id (str) – Optional. For “custom_emoji” only, unique identifier of the
custom emoji. Use get_custom_emoji_stickers to get full information about the sticker.
Returns
Instance of the class
Return type
telebot.types.MessageEntity
static to_list_of_dicts(entity_list) → List[Dict] | None
Converts a list of MessageEntity objects to a list of dictionaries.
class telebot.types.MessageID(message_id, **kwargs)
Bases: JsonDeserializable
This object represents a unique message identifier.

1.3. Content 87
pyTelegramBotAPI, Release 4.25.0

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

Parameters
message_id (int) – Unique message identifier
Returns
Instance of the class
Return type
telebot.types.MessageId
class telebot.types.MessageOrigin(type: str, date: int)
Bases: JsonDeserializable
This object describes the origin of a message.
Telegram documentation: https://core.telegram.org/bots/api#messageorigin
Parameters
• type (str) – Type of the message origin
• date (int) – Date the message was sent originally in Unix time
• sender_user (User) – User that sent the message originally (for MessageOriginUser)
• sender_user_name (str) – Name of the user that sent the message originally (for Mes-
sageOriginHiddenUser)
• sender_chat (Chat) – Chat that sent the message originally (for MessageOriginChat)
• author_signature (str) – Optional. Author signature for certain cases
Returns
Instance of the class
Return type
MessageOrigin
class telebot.types.MessageOriginChannel(date: int, chat: Chat, message_id: int, author_signature: str |
None = None)
Bases: MessageOrigin
The message was originally sent to a channel chat.
Parameters
• chat (Chat) – Channel chat to which the message was originally sent
• message_id (int) – Unique message identifier inside the chat
• author_signature (str) – Optional. Signature of the original post author
class telebot.types.MessageOriginChat(date: int, sender_chat: Chat, author_signature: str | None = None)
Bases: MessageOrigin
The message was originally sent on behalf of a chat to a group chat.
Parameters
• sender_chat (Chat) – Chat that sent the message originally
• author_signature (str) – Optional. For messages originally sent by an anonymous chat
administrator, original message author signature

88 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

class telebot.types.MessageOriginHiddenUser(date: int, sender_user_name: str)

Bases: MessageOrigin
The message was originally sent by an unknown user.
Parameters
sender_user_name (str) – Name of the user that sent the message originally
class telebot.types.MessageOriginUser(date: int, sender_user: User)
Bases: MessageOrigin
The message was originally sent by a known user.
Parameters
sender_user (User) – User that sent the message originally
class telebot.types.MessageReactionCountUpdated(chat: Chat, message_id: int, date: int, reactions:
List[ReactionCount], **kwargs)
Bases: JsonDeserializable
This object represents a service message about a change in the list of the current user’s reactions to a message.
Telegram documentation: https://core.telegram.org/bots/api#messagereactioncountupdated
Parameters
• chat (telebot.types.Chat) – The chat containing the message
• message_id (int) – Unique message identifier inside the chat
• date (int) – Date of the change in Unix time
• reactions (list of ReactionCount) – List of reactions that are present on the message
Returns
Instance of the class
Return type
MessageReactionCountUpdated
class telebot.types.MessageReactionUpdated(chat: Chat, message_id: int, date: int, old_reaction:
List[ReactionType], new_reaction: List[ReactionType],
user: User | None = None, actor_chat: Chat | None = None,
**kwargs)
Bases: JsonDeserializable
This object represents a service message about a change in the list of the current user’s reactions to a message.
Telegram documentation: https://core.telegram.org/bots/api#messagereactionupdated
Parameters
• chat (telebot.types.Chat) – The chat containing the message the user reacted to
• message_id (int) – Unique identifier of the message inside the chat
• user (telebot.types.User) – Optional. The user that changed the reaction, if the user
isn’t anonymous
• actor_chat (telebot.types.Chat) – Optional. The chat on behalf of which the reaction
was changed, if the user is anonymous
• date (int) – Date of the change in Unix time

1.3. Content 89
pyTelegramBotAPI, Release 4.25.0

• old_reaction (list of ReactionType) – Previous list of reaction types that were set by
the user
• new_reaction (list of ReactionType) – New list of reaction types that have been set by
the user
Returns
Instance of the class
Return type
MessageReactionUpdated
class telebot.types.OrderInfo(name=None, phone_number=None, email=None, shipping_address=None,
**kwargs)
Bases: JsonDeserializable
This object represents information about an order.
Telegram Documentation: https://core.telegram.org/bots/api#orderinfo
Parameters
• name (str) – Optional. User name
• phone_number (str) – Optional. User’s phone number
• email (str) – Optional. User email
• shipping_address (telebot.types.ShippingAddress) – Optional. User shipping ad-
dress
Returns
Instance of the class
Return type
telebot.types.OrderInfo
class telebot.types.PaidMedia
Bases: JsonDeserializable
This object describes paid media. Currently, it can be one of
PaidMediaPreview PaidMediaPhoto PaidMediaVideo
Telegram documentation: https://core.telegram.org/bots/api#paidmedia
Returns
Instance of the class
Return type
PaidMediaPreview or PaidMediaPhoto or PaidMediaVideo
class telebot.types.PaidMediaInfo(star_count, paid_media, **kwargs)
Bases: JsonDeserializable
Describes the paid media added to a message.
Telegram documentation: https://core.telegram.org/bots/api#paidmediainfo
Parameters
• star_count (int) – The number of Telegram Stars that must be paid to buy access to the
media
• paid_media (list of PaidMedia) – Information about the paid media

90 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
PaidMediaInfo
class telebot.types.PaidMediaPhoto(type, photo, **kwargs)
Bases: PaidMedia
The paid media is a photo.
Telegram documentation: https://core.telegram.org/bots/api#paidmediaphoto
Parameters
• type (str) – Type of the paid media, always “photo”
• photo (list of PhotoSize) – The photo
Returns
Instance of the class
Return type
PaidMediaPhoto
class telebot.types.PaidMediaPreview(type, width=None, height=None, duration=None, **kwargs)
Bases: PaidMedia
The paid media isn’t available before the payment.
Telegram documentation: https://core.telegram.org/bots/api#paidmediapreview
Parameters
• type (str) – Type of the paid media, always “preview”
• width (int) – Optional. Media width as defined by the sender
• height (int) – Optional. Media height as defined by the sender
• duration (int) – Optional. Duration of the media in seconds as defined by the sender
Returns
Instance of the class
Return type
PaidMediaPreview
class telebot.types.PaidMediaPurchased(from_user, paid_media_payload, **kwargs)
Bases: JsonDeserializable
This object contains information about a paid media purchase.
Telegram documentation: https://core.telegram.org/bots/api#paidmediapurchased
Parameters
• from_user (User) – User who purchased the media
• paid_media_payload (str) – Bot-specified paid media payload
Returns
Instance of the class
Return type
PaidMediaPurchased

1.3. Content 91
pyTelegramBotAPI, Release 4.25.0

class telebot.types.PaidMediaVideo(type, video, **kwargs)

Bases: PaidMedia
The paid media is a video.
Telegram documentation: https://core.telegram.org/bots/api#paidmediavideo
Parameters
• type (str) – Type of the paid media, always “video”
• video (Video) – The video
Returns
Instance of the class
Return type
PaidMediaVideo
class telebot.types.PhotoSize(file_id, file_unique_id, width, height, file_size=None, **kwargs)
Bases: JsonDeserializable
This object represents one size of a photo or a file / sticker thumbnail.
Telegram Documentation: https://core.telegram.org/bots/api#photosize
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• width (int) – Photo width
• height (int) – Photo height
• file_size (int) – Optional. File size in bytes
Returns
Instance of the class
Return type
telebot.types.PhotoSize
class telebot.types.Poll(question: str, options: List[PollOption], poll_id: str = None, total_voter_count: int
= None, is_closed: bool = None, is_anonymous: bool = None, type: str = None,
allows_multiple_answers: bool = None, correct_option_id: int = None,
explanation: str = None, explanation_entities: List[MessageEntity] = None,
open_period: int = None, close_date: int = None, poll_type: str = None,
question_entities: List[MessageEntity] = None, **kwargs)
Bases: JsonDeserializable
This object contains information about a poll.
Telegram Documentation: https://core.telegram.org/bots/api#poll
Parameters
• id (str) – Unique poll identifier
• question (str) – Poll question, 1-300 characters
• options (list of telebot.types.PollOption) – List of poll options
• total_voter_count (int) – Total number of users that voted in the poll

92 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• is_closed (bool) – True, if the poll is closed

• is_anonymous (bool) – True, if the poll is anonymous
• type (str) – Poll type, currently can be “regular” or “quiz”
• allows_multiple_answers (bool) – True, if the poll allows multiple answers
• correct_option_id (int) – Optional. 0-based identifier of the correct answer option.
Available only for polls in the quiz mode, which are closed, or was sent (not forwarded) by
the bot or to the private chat with the bot.
• explanation (str) – Optional. Text that is shown when a user chooses an incorrect answer
or taps on the lamp icon in a quiz-style poll, 0-200 characters
• explanation_entities (list of telebot.types.MessageEntity) – Optional. Spe-
cial entities like usernames, URLs, bot commands, etc. that appear in the explanation
• open_period (int) – Optional. Amount of time in seconds the poll will be active after
creation
• close_date (int) – Optional. Point in time (Unix timestamp) when the poll will be auto-
matically closed
• question_entities (list of telebot.types.MessageEntity) – Optional. Special
entities that appear in the question. Currently, only custom emoji entities are allowed in poll
questions
Returns
Instance of the class
Return type
telebot.types.Poll
add(option)
Add an option to the poll.
Parameters
option (telebot.types.PollOption or str) – Option to add
class telebot.types.PollAnswer(poll_id: str, option_ids: List[int], user: User | None = None, voter_chat:
Chat | None = None, **kwargs)
Bases: JsonSerializable, JsonDeserializable, Dictionaryable
This object represents an answer of a user in a non-anonymous poll.
Telegram Documentation: https://core.telegram.org/bots/api#pollanswer
Parameters
• poll_id (str) – Unique poll identifier
• voter_chat (telebot.types.Chat) – Optional. The chat that changed the answer to the
poll, if the voter is anonymous
• user (telebot.types.User) – Optional. The user, who changed the answer to the poll
• option_ids (list of int) – 0-based identifiers of answer options, chosen by the user. May
be empty if the user retracted their vote.
Returns
Instance of the class
Return type
telebot.types.PollAnswer

1.3. Content 93
pyTelegramBotAPI, Release 4.25.0

class telebot.types.PollOption(text, voter_count=0, text_entities=None, **kwargs)

Bases: JsonDeserializable
This object contains information about one answer option in a poll.
Telegram Documentation: https://core.telegram.org/bots/api#polloption
Parameters
• text (str) – Option text, 1-100 characters
• voter_count (int) – Number of users that voted for this option
• text_entities (list of telebot.types.MessageEntity) – Optional. Special entities
that appear in the option text. Currently, only custom emoji entities are allowed in poll option
texts
Returns
Instance of the class
Return type
telebot.types.PollOption
class telebot.types.PreCheckoutQuery(id, from_user, currency, total_amount, invoice_payload,
shipping_option_id=None, order_info=None, **kwargs)
Bases: JsonDeserializable
This object contains information about an incoming pre-checkout query.
Telegram Documentation: https://core.telegram.org/bots/api#precheckoutquery
Parameters
• id (str) – Unique query identifier
• from (telebot.types.User) – User who sent the query
• currency (str) – Three-letter ISO 4217 currency code
• total_amount (int) – Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp pa-
rameter in currencies.json, it shows the number of digits past the decimal point for each
currency (2 for the majority of currencies).
• invoice_payload (str) – Bot specified invoice payload
• shipping_option_id (str) – Optional. Identifier of the shipping option chosen by the
user
• order_info (telebot.types.OrderInfo) – Optional. Order information provided by
the user
Returns
Instance of the class
Return type
telebot.types.PreCheckoutQuery
class telebot.types.PreparedInlineMessage(id, expiration_date, **kwargs)
Bases: JsonDeserializable
Describes an inline message to be sent by a user of a Mini App.
Telegram documentation: https://core.telegram.org/bots/api#preparedinlinemessage
Parameters

94 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

• id (str) – Unique identifier of the prepared message

• expiration_date (int) – Expiration date of the prepared message, in Unix time. Expired
prepared messages can no longer be used
Returns
Instance of the class
Return type
PreparedInlineMessage
class telebot.types.ProximityAlertTriggered(traveler, watcher, distance, **kwargs)
Bases: JsonDeserializable
This object represents the content of a service message, sent whenever a user in the chat triggers a proximity
alert set by another user.
Telegram Documentation: https://core.telegram.org/bots/api#proximityalerttriggered
Parameters
• traveler (telebot.types.User) – User that triggered the alert
• watcher (telebot.types.User) – User that set the alert
• distance (int) – The distance between the users
Returns
Instance of the class
Return type
telebot.types.ProximityAlertTriggered
class telebot.types.ReactionCount(type: ReactionType, total_count: int, **kwargs)
Bases: JsonDeserializable
This object represents a reaction added to a message along with the number of times it was added.
Telegram documentation: https://core.telegram.org/bots/api#reactioncount
Parameters
• type (ReactionType) – Type of the reaction
• total_count (int) – Number of times the reaction was added
Returns
Instance of the class
Return type
ReactionCount
class telebot.types.ReactionType(type: str)
Bases: JsonDeserializable, Dictionaryable, JsonSerializable
This object represents a reaction type.
Telegram documentation: https://core.telegram.org/bots/api#reactiontype
Parameters
type (str) – Type of the reaction
Returns
Instance of the class

1.3. Content 95
pyTelegramBotAPI, Release 4.25.0

Return type
ReactionType
class telebot.types.ReactionTypeCustomEmoji(custom_emoji_id: str, **kwargs)
Bases: ReactionType
This object represents a custom emoji reaction type.
Telegram documentation: https://core.telegram.org/bots/api#reactiontypecustomemoji
Parameters
• type (str) – Type of the reaction, must be custom_emoji
• custom_emoji_id (str) – Identifier of the custom emoji
Returns
Instance of the class
Return type
ReactionTypeCustomEmoji
class telebot.types.ReactionTypeEmoji(emoji: str, **kwargs)
Bases: ReactionType
This object represents an emoji reaction type.
Telegram documentation: https://core.telegram.org/bots/api#reactiontypeemoji
Parameters
• type (str) – Type of the reaction, must be emoji
• emoji (str) – Reaction emoji. List is available on the API doc.
Returns
Instance of the class
Return type
ReactionTypeEmoji
class telebot.types.ReactionTypePaid(**kwargs)
Bases: ReactionType
This object represents a paid reaction type.
Telegram documentation: https://core.telegram.org/bots/api#reactiontypepaid
Parameters
type (str) – Type of the reaction, must be paid
Returns
Instance of the class
Return type
ReactionTypePaid
class telebot.types.RefundedPayment(currency, total_amount, invoice_payload,
telegram_payment_charge_id, provider_payment_charge_id=None,
**kwargs)
Bases: JsonDeserializable
This object contains basic information about a refunded payment.
Telegram documentation: https://core.telegram.org/bots/api#refundedpayment

96 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

Parameters
• currency (str) – Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram
Stars. Currently, always “XTR”
• total_amount (int) – Total refunded price in the smallest units of the currency (integer,
not float/double). For example, for a price of US$ 1.45, total_amount = 145. See the exp
parameter in currencies.json, it shows the number of digits past the decimal point for each
currency (2 for the majority of currencies).
• invoice_payload (str) – Bot-specified invoice payload
• telegram_payment_charge_id (str) – Telegram payment identifier
• provider_payment_charge_id (str) – Optional. Provider payment identifier
Returns
Instance of the class
Return type
RefundedPayment
class telebot.types.ReplyKeyboardMarkup(resize_keyboard: bool | None = None, one_time_keyboard: bool
| None = None, selective: bool | None = None, row_width: int =
3, input_field_placeholder: str | None = None, is_persistent:
bool | None = None)
Bases: JsonSerializable
This object represents a custom keyboard with reply options (see Introduction to bots for details and examples).

Listing 3: Example on creating ReplyKeyboardMarkup object

from telebot.types import ReplyKeyboardMarkup, KeyboardButton

markup = ReplyKeyboardMarkup(resize_keyboard=True)
markup.add(KeyboardButton('Text'))
# or:
markup.add('Text')

# display this markup:

bot.send_message(chat_id, 'Text', reply_markup=markup)

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

Parameters
• keyboard (list of list of telebot.types.KeyboardButton) – list of button rows,
each represented by an list of telebot.types.KeyboardButton objects
• resize_keyboard (bool) – Optional. Requests clients to resize the keyboard vertically for
optimal fit (e.g., make the keyboard smaller if there are just two rows of buttons). Defaults to
false, in which case the custom keyboard is always of the same height as the app’s standard
keyboard.
• one_time_keyboard (bool) – Optional. Requests clients to hide the keyboard as soon as
it’s been used. The keyboard will still be available, but clients will automatically display the
usual letter-keyboard in the chat - the user can press a special button in the input field to see
the custom keyboard again. Defaults to false.
• input_field_placeholder (str) – Optional. The placeholder to be shown in the input
field when the keyboard is active; 1-64 characters

1.3. Content 97
pyTelegramBotAPI, Release 4.25.0

• selective (bool) – Optional. Use this parameter if you want to show the keyboard to
specific users only. Targets: 1) users that are @mentioned in the text of the Message object;
2) if the bot’s message is a reply to a message in the same chat and forum topic, sender of
the original message. Example: A user requests to change the bot’s language, bot replies to
the request with a keyboard to select the new language. Other users in the group don’t see
the keyboard.
• is_persistent – Optional. Use this parameter if you want to show the keyboard to specific
users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the
bot’s message is a reply (has reply_to_message_id), sender of the original message.
Example: A user requests to change the bot’s language, bot replies to the request with a
keyboard to select the new language. Other users in the group don’t see the keyboard.
Returns
Instance of the class
Return type
telebot.types.ReplyKeyboardMarkup
add(*args, row_width=None) → ReplyKeyboardMarkup
This function adds strings to the keyboard, while not exceeding row_width. E.g. ReplyKeyboard-
Markup#add(“A”, “B”, “C”) yields the json result {keyboard: [[“A”], [“B”], [“C”]]} when row_width is
set to 1. When row_width is set to 2, the following is the result of this function: {keyboard: [[“A”, “B”],
[“C”]]} See https://core.telegram.org/bots/api#replykeyboardmarkup
Parameters
• args (str or telebot.types.KeyboardButton) – KeyboardButton to append to the
keyboard
• row_width (int) – width of row
Returns
self, to allow function chaining.
Return type
telebot.types.ReplyKeyboardMarkup
max_row_keys = 12

row(*args) → ReplyKeyboardMarkup
Adds a list of KeyboardButton to the keyboard. This function does not consider row_width. ReplyKey-
boardMarkup#row(“A”)#row(“B”, “C”)#to_json() outputs ‘{keyboard: [[“A”], [“B”, “C”]]}’ See https:
//core.telegram.org/bots/api#replykeyboardmarkup
Parameters
args (str) – strings
Returns
self, to allow function chaining.
Return type
telebot.types.ReplyKeyboardMarkup
class telebot.types.ReplyKeyboardRemove(selective: bool | None = None)
Bases: JsonSerializable
Upon receiving a message with this object, Telegram clients will remove the current custom keyboard and display
the default letter-keyboard. By default, custom keyboards are displayed until a new keyboard is sent by a bot.
An exception is made for one-time keyboards that are hidden immediately after the user presses a button (see
ReplyKeyboardMarkup).

98 Chapter 1. TeleBot
pyTelegramBotAPI, Release 4.25.0

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

Parameters
• remove_keyboard (bool) – Requests clients to remove the custom keyboard (user will not
be able to summon this keyboard; if you want to hide the keyboard from sight but keep it
accessible, use one_time_keyboard in ReplyKeyboardMarkup) Note that this parameter is
set to True by default by the library. You cannot modify it.
• selective (bool) – Optional. Use this parameter if you want to remove the keyboard for
specific users only. Targets: 1) users that are @mentioned in the text of the Message object;
2) if the bot’s message is a reply (has reply_to_message_id), sender of the original mes-
sage.Example: A user votes in a poll, bot returns confirmation message in reply to the vote
and removes the keyboard for that user, while still showing the keyboard with poll options to
users who haven’t voted yet.
Returns
Instance of the class
Return type
telebot.types.ReplyKeyboardRemove
class telebot.types.ReplyParameters(message_id: int, chat_id: int | str | None = None,
allow_sending_without_reply: bool | None = None, quote: str | None
= None, quote_parse_mode: str | None = None, quote_entities:
List[MessageEntity] | None = None, quote_position: int | None =
None, **kwargs)
Bases: JsonDeserializable, Dictionaryable, JsonSerializable
Describes reply parameters for the message that is being sent.
Telegram documentation: https://core.telegram.org/bots/api#replyparameters
Parameters
• message_id (int) – Identifier of the message that will be replied to in the current chat, or
in the chat chat_id if it is specified
• chat_id (int or str) – Optional. If the message to be replied to is from a different chat,
unique identifier for the chat or username of the channel (in the format @channelusername)
• allow_sending_without_reply (bool) – Optional. Pass True if the message should be
sent even if the specified message to be replied to is not found; can be used only for replies
in the same chat and forum topic.
• quote (str) – Optional. Quoted part of the message to be replied to; 0-1024 characters
after entities parsing. The quote must be an exact substring of the message to be replied
to, including bold, italic, underline, strikethrough, spoiler, and custom_emoji entities. The
message will fail to send if the quote isn’t found in the original message.
• quote_parse_mode (str) – Optional. Mode for parsing entities in the quote. See format-
ting options for more details.
• quote_entities (list of MessageEntity) – Optional. A JSON-serialized list of special
entities that appear in the quote. It can be specified instead of quote_parse_mode.
• quote_position (int) – Optional. Position of the quote in the original message in UTF-16
code units
Returns
Instance of the class

1.3. Content 99
pyTelegramBotAPI, Release 4.25.0

Return type
ReplyParameters
class telebot.types.RevenueWithdrawalState
Bases: JsonDeserializable
This object describes the state of a revenue withdrawal operation. Currently, it can be one of
RevenueWithdrawalStatePending RevenueWithdrawalStateSucceeded RevenueWithdrawalStateFailed
Telegram documentation: https://core.telegram.org/bots/api#revenuewithdrawalstate
Parameters
type (str) – Type of the state, always “pending” or “succeeded” or “failed”
Returns
Instance of the class
Return type
RevenueWithdrawalStatePending or RevenueWithdrawalStateSucceeded or
RevenueWithdrawalStateFailed
class telebot.types.RevenueWithdrawalStateFailed(type, **kwargs)
Bases: RevenueWithdrawalState
The withdrawal failed and the transaction was refunded.
Telegram documentation: https://core.telegram.org/bots/api#revenuewithdrawalstatefailed
Parameters
type (str) – Type of the state, always “failed”
Returns
Instance of the class
Return type
RevenueWithdrawalStateFailed
class telebot.types.RevenueWithdrawalStatePending(type, **kwargs)
Bases: RevenueWithdrawalState
The withdrawal is in progress.
Telegram documentation: https://core.telegram.org/bots/api#revenuewithdrawalstatepending
Parameters
type (str) – Type of the state, always “pending”
Returns
Instance of the class
Return type
RevenueWithdrawalStatePending
class telebot.types.RevenueWithdrawalStateSucceeded(type, date, url, **kwargs)
Bases: RevenueWithdrawalState
The withdrawal succeeded.
Telegram documentation: https://core.telegram.org/bots/api#revenuewithdrawalstatesucceeded
Parameters
• type (str) – Type of the state, always “succeeded”
• date (int) – Date the withdrawal was completed in Unix time

100 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• url (str) – An HTTPS URL that can be used to see transaction details
Returns
Instance of the class
Return type
RevenueWithdrawalStateSucceeded
class telebot.types.SentWebAppMessage(inline_message_id=None, **kwargs)
Bases: JsonDeserializable, Dictionaryable
Describes an inline message sent by a Web App on behalf of a user.
Telegram Documentation: https://core.telegram.org/bots/api#sentwebappmessage
Parameters
inline_message_id (str) – Optional. Identifier of the sent inline message. Available only if
there is an inline keyboard attached to the message.
Returns
Instance of the class
Return type
telebot.types.SentWebAppMessage
class telebot.types.SharedUser(user_id, first_name=None, last_name=None, username=None,
photo=None, **kwargs)
Bases: JsonDeserializable
This object contains information about a user that was shared with the bot using a KeyboardButtonRequestUser
button.
Telegram documentation: https://core.telegram.org/bots/api#shareduser
Parameters
• user_id (int) – Identifier of the shared user. This number may have more than 32 signifi-
cant bits and some programming languages may have difficulty/silent defects in interpreting
it. But it has at most 52 significant bits, so 64-bit integers or double-precision float types are
safe for storing these identifiers. The bot may not have access to the user and could be unable
to use this identifier, unless the user is already known to the bot by some other means.
• first_name (str) – Optional. First name of the user, if the name was requested by the bot
• last_name (str) – Optional. Last name of the user, if the name was requested by the bot
• username (str) – Optional. Username of the user, if the username was requested by the bot
• photo (list of PhotoSize) – Optional. Available sizes of the chat photo, if the photo was
requested by the bot
Returns
Instance of the class
Return type
SharedUser
class telebot.types.ShippingAddress(country_code, state, city, street_line1, street_line2, post_code,
**kwargs)
Bases: JsonDeserializable
This object represents a shipping address.
Telegram Documentation: https://core.telegram.org/bots/api#shippingaddress

1.3. Content 101

pyTelegramBotAPI, Release 4.25.0

Parameters
• country_code (str) – Two-letter ISO 3166-1 alpha-2 country code
• state (str) – State, if applicable
• city (str) – City
• street_line1 (str) – First line for the address
• street_line2 (str) – Second line for the address
• post_code (str) – Address post code
Returns
Instance of the class
Return type
telebot.types.ShippingAddress
class telebot.types.ShippingOption(id, title)
Bases: JsonSerializable
This object represents one shipping option.
Telegram Documentation: https://core.telegram.org/bots/api#shippingoption
Parameters
• id (str) – Shipping option identifier
• title (str) – Option title
• prices (list of telebot.types.LabeledPrice) – List of price portions
Returns
Instance of the class
Return type
telebot.types.ShippingOption
add_price(*args) → ShippingOption
Add LabeledPrice to ShippingOption
Parameters
args (LabeledPrice) – LabeledPrices
Returns
None
class telebot.types.ShippingQuery(id, from_user, invoice_payload, shipping_address, **kwargs)
Bases: JsonDeserializable
This object contains information about an incoming shipping query.
Telegram Documentation: https://core.telegram.org/bots/api#shippingquery
Parameters
• id (str) – Unique query identifier
• from (telebot.types.User) – User who sent the query
• invoice_payload (str) – Bot specified invoice payload
• shipping_address (telebot.types.ShippingAddress) – User specified shipping ad-
dress

102 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
telebot.types.ShippingQuery
class telebot.types.StarTransaction(id, amount, date, source=None, receiver=None,
nanostar_amount=None, **kwargs)
Bases: JsonDeserializable
Describes a Telegram Star transaction.
Telegram documentation: https://core.telegram.org/bots/api#startransaction
Parameters
• id (str) – Unique identifier of the transaction. Coincides with the identifer
of the original transaction for refund transactions. Coincides with SuccessfulPay-
ment.telegram_payment_charge_id for successful incoming payments from users.
• amount (int) – Number of Telegram Stars transferred by the transaction
• nanostar_amount (int) – Optional. The number of 1/1000000000 shares of Telegram
Stars transferred by the transaction; from 0 to 999999999
• date (int) – Date the transaction was created in Unix time
• source (TransactionPartner) – Optional. Source of an incoming transaction (e.g., a user
purchasing goods or services, Fragment refunding a failed withdrawal). Only for incoming
transactions
• receiver (TransactionPartner) – Optional. Receiver of an outgoing transaction (e.g.,
a user for a purchase refund, Fragment for a withdrawal). Only for outgoing transactions
Returns
Instance of the class
Return type
StarTransaction
class telebot.types.StarTransactions(transactions, **kwargs)
Bases: JsonDeserializable
Contains a list of Telegram Star transactions.
Telegram documentation: https://core.telegram.org/bots/api#startransactions
Parameters
transactions (list of StarTransaction) – The list of transactions
Returns
Instance of the class
Return type
StarTransactions
class telebot.types.Sticker(file_id, file_unique_id, type, width, height, is_animated, is_video,
thumbnail=None, emoji=None, set_name=None, mask_position=None,
file_size=None, premium_animation=None, custom_emoji_id=None,
needs_repainting=None, **kwargs)
Bases: JsonDeserializable
This object represents a sticker.

1.3. Content 103

pyTelegramBotAPI, Release 4.25.0

Telegram Documentation: https://core.telegram.org/bots/api#sticker

Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• type (str) – Type of the sticker, currently one of “regular”, “mask”, “custom_emoji”.
The type of the sticker is independent from its format, which is determined by the fields
is_animated and is_video.
• width (int) – Sticker width
• height (int) – Sticker height
• is_animated (bool) – True, if the sticker is animated
• is_video (bool) – True, if the sticker is a video sticker
• thumbnail (telebot.types.PhotoSize) – Optional. Sticker thumbnail in the .WEBP or
.JPG format
• emoji (str) – Optional. Emoji associated with the sticker
• set_name (str) – Optional. Name of the sticker set to which the sticker belongs
• premium_animation (telebot.types.File) – Optional. Premium animation for the
sticker, if the sticker is premium
• mask_position (telebot.types.MaskPosition) – Optional. For mask stickers, the po-
sition where the mask should be placed
• custom_emoji_id (str) – Optional. For custom emoji stickers, unique identifier of the
custom emoji
• needs_repainting (bool) – Optional. True, if the sticker must be repainted to a text color
in messages, the color of the Telegram Premium badge in emoji status, white color on chat
photos, or another appropriate color in other places
• file_size (int) – Optional. File size in bytes
Returns
Instance of the class
Return type
telebot.types.Sticker
property thumb: PhotoSize | None

class telebot.types.StickerSet(name, title, sticker_type, stickers, thumbnail=None, **kwargs)

Bases: JsonDeserializable
This object represents a sticker set.
Telegram Documentation: https://core.telegram.org/bots/api#stickerset
Parameters
• name (str) – Sticker set name
• title (str) – Sticker set title
• sticker_type (str) – Type of stickers in the set, currently one of “regular”, “mask”, “cus-
tom_emoji”

104 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• stickers (list of telebot.types.Sticker) – List of all set stickers

• thumbnail (telebot.types.PhotoSize) – Optional. Sticker set thumbnail in the .WEBP,
.TGS, or .WEBM format
Returns
Instance of the class
Return type
telebot.types.StickerSet
property contains_masks: bool

property is_animated: bool

property is_video: bool

property thumb: PhotoSize | None

class telebot.types.Story(chat: Chat, id: int, **kwargs)

Bases: JsonDeserializable
This object represents a story.
Telegram documentation: https://core.telegram.org/bots/api#story
Parameters
• chat (telebot.types.Chat) – Chat that posted the story
• id (int) – Unique identifier for the story in the chat
Returns
Instance of the class
Return type
Story
class telebot.types.SuccessfulPayment(currency, total_amount, invoice_payload,
shipping_option_id=None, order_info=None,
telegram_payment_charge_id=None,
provider_payment_charge_id=None,
subscription_expiration_date=None, is_recurring=None,
is_first_recurring=None, **kwargs)
Bases: JsonDeserializable
This object contains basic information about a successful payment.
Telegram Documentation: https://core.telegram.org/bots/api#successfulpayment
Parameters
• currency (str) – Three-letter ISO 4217 currency code
• total_amount (int) – Total price in the smallest units of the currency (integer, not
float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp pa-
rameter in currencies.json, it shows the number of digits past the decimal point for each
currency (2 for the majority of currencies).
• invoice_payload (str) – Bot specified invoice payload
• subscription_expiration_date (int) – Optional. Expiration date of the subscription,
in Unix time; for recurring payments only

1.3. Content 105

pyTelegramBotAPI, Release 4.25.0

• is_recurring (bool) – Optional. True, if the payment is a recurring payment, false other-
wise
• is_first_recurring (bool) – Optional. True, if the payment is the first payment for a
subscription
• shipping_option_id (str) – Optional. Identifier of the shipping option chosen by the
user
• order_info (telebot.types.OrderInfo) – Optional. Order information provided by
the user
• telegram_payment_charge_id (str) – Telegram payment identifier
• provider_payment_charge_id (str) – Provider payment identifier
Returns
Instance of the class
Return type
telebot.types.SuccessfulPayment
class telebot.types.SwitchInlineQueryChosenChat(query: str | None = None, allow_user_chats: bool |
None = None, allow_bot_chats: bool | None = None,
allow_group_chats: bool | None = None,
allow_channel_chats: bool | None = None)
Bases: JsonDeserializable, Dictionaryable, JsonSerializable
Represents an inline button that switches the current user to inline mode in a chosen chat, with an optional default
inline query.
Telegram Documentation: https://core.telegram.org/bots/api#inlinekeyboardbutton
Parameters
• query (str) – Optional. The default inline query to be inserted in the input field. If left
empty, only the bot’s username will be inserted
• allow_user_chats (bool) – Optional. True, if private chats with users can be chosen
• allow_bot_chats (bool) – Optional. True, if private chats with bots can be chosen
• allow_group_chats (bool) – Optional. True, if group and supergroup chats can be chosen
• allow_channel_chats (bool) – Optional. True, if channel chats can be chosen
Returns
Instance of the class
Return type
SwitchInlineQueryChosenChat
class telebot.types.TextQuote(text: str, position: int, entities: List[MessageEntity] | None = None,
is_manual: bool | None = None, **kwargs)
Bases: JsonDeserializable
This object contains information about the quoted part of a message that is replied to by the given message.
Telegram documentation: https://core.telegram.org/bots/api#textquote
Parameters
• text (str) – Text of the quoted part of a message that is replied to by the given message

106 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• entities (list of MessageEntity) – Optional. Special entities that appear in the quote.
Currently, only bold, italic, underline, strikethrough, spoiler, and custom_emoji entities are
kept in quotes.
• position (int) – Approximate quote position in the original message in UTF-16 code units
as specified by the sender
• is_manual (bool) – Optional. True, if the quote was chosen manually by the message
sender. Otherwise, the quote was added automatically by the server.
Returns
Instance of the class
Return type
TextQuote
property html_text
Returns html-rendered text.
class telebot.types.TransactionPartner
Bases: JsonDeserializable
This object describes the source of a transaction, or its recipient for outgoing transactions. Currently, it
can be one of
TransactionPartnerFragment TransactionPartnerUser TransactionPartnerOther
Telegram documentation: https://core.telegram.org/bots/api#transactionpartner
Parameters
type (str) – Type of the transaction partner
Returns
Instance of the class
Return type
TransactionPartnerFragment or TransactionPartnerUser or
TransactionPartnerOther
class telebot.types.TransactionPartnerAffiliateProgram(type, commission_per_mille,
sponsor_user=None, **kwargs)
Bases: TransactionPartner
Describes the affiliate program that issued the affiliate commission received via this transaction.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartneraffiliateprogram
Parameters
• type (str) – Type of the transaction partner, always “affiliate_program”
• sponsor_user (User) – Optional. Information about the bot that sponsored the affiliate
program
• commission_per_mille (int) – The number of Telegram Stars received by the bot for
each 1000 Telegram Stars received by the affiliate program sponsor from referred users
Returns
Instance of the class
Return type
TransactionPartnerAffiliateProgram

1.3. Content 107

pyTelegramBotAPI, Release 4.25.0

class telebot.types.TransactionPartnerFragment(type, withdrawal_state=None, **kwargs)

Bases: TransactionPartner
Describes a withdrawal transaction with Fragment.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartnerfragment
Parameters
• type (str) – Type of the transaction partner, always “fragment”
• withdrawal_state (RevenueWithdrawalState) – Optional. State of the transaction if
the transaction is outgoing
Returns
Instance of the class
Return type
TransactionPartnerFragment
class telebot.types.TransactionPartnerOther(type, **kwargs)
Bases: TransactionPartner
Describes a transaction with an unknown source or recipient.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartnerother
Parameters
type (str) – Type of the transaction partner, always “other”
Returns
Instance of the class
Return type
TransactionPartnerOther
class telebot.types.TransactionPartnerTelegramAds(type, **kwargs)
Bases: TransactionPartner
Describes a transaction with Telegram Ads.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartnertelegramads
Parameters
type (str) – Type of the transaction partner, always “telegram_ads”
Returns
Instance of the class
Return type
TransactionPartnerTelegramAds
class telebot.types.TransactionPartnerTelegramApi(type, request_count, **kwargs)
Bases: TransactionPartner
Describes a transaction with payment for paid broadcasting.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartnertelegramapi
Parameters
• type (str) – Type of the transaction partner, always “telegram_api”
• request_count (int) – The number of successful requests that exceeded regular limits and
were therefore billed

108 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
TransactionPartnerTelegramApi
class telebot.types.TransactionPartnerUser(type, user, affiliate=None, invoice_payload=None,
paid_media: List[PaidMedia] | None = None,
subscription_period=None, gift: Gift | None = None,
**kwargs)
Bases: TransactionPartner
Describes a transaction with a user.
Telegram documentation: https://core.telegram.org/bots/api#transactionpartneruser
Parameters
• type (str) – Type of the transaction partner, always “user”
• user (User) – Information about the user
• affiliate (AffiliateInfo) – Optional. Information about the affiliate that received a
commission via this transaction
• invoice_payload (str) – Optional, Bot-specified invoice payload
• subscription_period (int) – Optional. The duration of the paid subscription
• paid_media (list of PaidMedia) – Optional. Information about the paid media bought
by the user
• gift (Gift) – Optional. The gift sent to the user by the bot
Returns
Instance of the class
Return type
TransactionPartnerUser
class telebot.types.Update(update_id, message, edited_message, channel_post, edited_channel_post,
inline_query, chosen_inline_result, callback_query, shipping_query,
pre_checkout_query, poll, poll_answer, my_chat_member, chat_member,
chat_join_request, message_reaction, message_reaction_count,
removed_chat_boost, chat_boost, business_connection, business_message,
edited_business_message, deleted_business_messages, purchased_paid_media)
Bases: JsonDeserializable
This object represents an incoming update.At most one of the optional parameters can be present in any given
update.
Telegram Documentation: https://core.telegram.org/bots/api#update
Parameters
• update_id (int) – The update’s unique identifier. Update identifiers start from a certain
positive number and increase sequentially. This ID becomes especially handy if you’re using
webhooks, since it allows you to ignore repeated updates or to restore the correct update
sequence, should they get out of order. If there are no new updates for at least a week, then
identifier of the next update will be chosen randomly instead of sequentially.
• message (telebot.types.Message) – Optional. New incoming message of any kind -
text, photo, sticker, etc.

1.3. Content 109

pyTelegramBotAPI, Release 4.25.0

• edited_message (telebot.types.Message) – Optional. New version of a message that

is known to the bot and was edited
• channel_post (telebot.types.Message) – Optional. New incoming channel post of
any kind - text, photo, sticker, etc.
• edited_channel_post (telebot.types.Message) – Optional. New version of a chan-
nel post that is known to the bot and was edited
• message_reaction (telebot.types.MessageReactionUpdated) – Optional. A reac-
tion to a message was changed by a user. The bot must be an administrator in the chat and
must explicitly specify “message_reaction” in the list of allowed_updates to receive these
updates. The update isn’t received for reactions set by bots.
• message_reaction_count (telebot.types.MessageReactionCountUpdated) – Op-
tional. Reactions to a message with anonymous reactions were changed. The bot must be an
administrator in the chat and must explicitly specify “message_reaction_count” in the list of
allowed_updates to receive these updates.
• inline_query (telebot.types.InlineQuery) – Optional. New incoming inline query
• chosen_inline_result (telebot.types.ChosenInlineResult) – Optional. The re-
sult of an inline query that was chosen by a user and sent to their chat partner. Please see
our documentation on the feedback collecting for details on how to enable these updates for
your bot.
• callback_query (telebot.types.CallbackQuery) – Optional. New incoming call-
back query
• shipping_query (telebot.types.ShippingQuery) – Optional. New incoming ship-
ping query. Only for invoices with flexible price
• pre_checkout_query (telebot.types.PreCheckoutQuery) – Optional. New incom-
ing pre-checkout query. Contains full information about checkout
• poll (telebot.types.Poll) – Optional. New poll state. Bots receive only updates about
stopped polls and polls, which are sent by the bot
• poll_answer (telebot.types.PollAnswer) – Optional. A user changed their answer in
a non-anonymous poll. Bots receive new votes only in polls that were sent by the bot itself.
• my_chat_member (telebot.types.ChatMemberUpdated) – Optional. The bot’s chat
member status was updated in a chat. For private chats, this update is received only when
the bot is blocked or unblocked by the user.
• chat_member (telebot.types.ChatMemberUpdated) – Optional. A chat member’s sta-
tus was updated in a chat. The bot must be an administrator in the chat and must explicitly
specify “chat_member” in the list of allowed_updates to receive these updates.
• chat_join_request (telebot.types.ChatJoinRequest) – Optional. A request to join
the chat has been sent. The bot must have the can_invite_users administrator right in the chat
to receive these updates.
• chat_boost (telebot.types.ChatBoostUpdated) – Optional. A chat boost was added
or changed. The bot must be an administrator in the chat to receive these updates.
• removed_chat_boost (telebot.types.RemovedChatBoost) – Optional. A chat boost
was removed. The bot must be an administrator in the chat to receive these updates.
• business_connection (telebot.types.BusinessConnection) – Optional. The bot
was connected to or disconnected from a business account, or a user edited an existing con-
nection with the bot

110 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• business_message (telebot.types.Message) – Optional. New non-service message

from a connected business account
• edited_business_message (telebot.types.Message) – Optional. New version of a
non-service message from a connected business account that is known to the bot and was
edited
• deleted_business_messages (telebot.types.BusinessMessagesDeleted) – Op-
tional. Service message: the chat connected to the business account was deleted
Purchased_paid_media
Optional. A user purchased paid media with a non-empty payload sent by the bot in a non-channel
chat
Returns
Instance of the class
Return type
telebot.types.Update
class telebot.types.User(id, is_bot, first_name, last_name=None, username=None, language_code=None,
can_join_groups=None, can_read_all_group_messages=None,
supports_inline_queries=None, is_premium=None,
added_to_attachment_menu=None, can_connect_to_business=None,
has_main_web_app=None, **kwargs)
Bases: JsonDeserializable, Dictionaryable, JsonSerializable
This object represents a Telegram user or bot.
Telegram Documentation: https://core.telegram.org/bots/api#user
Parameters
• id (int) – Unique identifier for this user or bot. This number may have more than 32 signifi-
cant bits and some programming languages may have difficulty/silent defects in interpreting
it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are
safe for storing this identifier.
• is_bot (bool) – True, if this user is a bot
• first_name (str) – User’s or bot’s first name
• last_name (str) – Optional. User’s or bot’s last name
• username (str) – Optional. User’s or bot’s username
• language_code (str) – Optional. IETF language tag of the user’s language
• is_premium (bool) – Optional. bool, if this user is a Telegram Premium user
• added_to_attachment_menu (bool) – Optional. bool, if this user added the bot to the
attachment menu
• can_join_groups (bool) – Optional. True, if the bot can be invited to groups. Returned
only in getMe.
• can_read_all_group_messages (bool) – Optional. True, if privacy mode is disabled for
the bot. Returned only in getMe.
• supports_inline_queries (bool) – Optional. True, if the bot supports inline queries.
Returned only in getMe.
• can_connect_to_business (bool) – Optional. True, if the bot can be connected to a
Telegram Business account to receive its messages. Returned only in getMe.

1.3. Content 111

pyTelegramBotAPI, Release 4.25.0

• has_main_web_app (bool) – Optional. True, if the bot has a main Web App. Returned
only in getMe.
Returns
Instance of the class
Return type
telebot.types.User
property full_name: str
User’s full name
Type
return
class telebot.types.UserChatBoosts(boosts, **kwargs)
Bases: JsonDeserializable
This object represents a list of boosts added to a chat by a user.
Telegram documentation: https://core.telegram.org/bots/api#userchatboosts
Parameters
boosts (list of ChatBoost) – The list of boosts added to the chat by the user
Returns
Instance of the class
Return type
UserChatBoosts
class telebot.types.UserProfilePhotos(total_count, photos=None, **kwargs)
Bases: JsonDeserializable
This object represent a user’s profile pictures.
Telegram Documentation: https://core.telegram.org/bots/api#userprofilephotos
Parameters
• total_count (int) – Total number of profile pictures the target user has
• photos (list of list of telebot.types.PhotoSize) – Requested profile pictures (in
up to 4 sizes each)
Returns
Instance of the class
Return type
telebot.types.UserProfilePhotos
class telebot.types.UsersShared(request_id: int, users: List[SharedUser], **kwargs)
Bases: JsonDeserializable
This object contains information about the users whose identifiers were shared with the bot using a Keyboard-
ButtonRequestUsers button.
Telegram documentation: https://core.telegram.org/bots/api#usersshared
Parameters
• request_id (int) – Identifier of the request
• users (list of types.SharedUser) – Information about users shared with the bot

112 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Instance of the class
Return type
UsersShared
property user_id: None

property user_ids: List[SharedUser]

class telebot.types.Venue(location, title, address, foursquare_id=None, foursquare_type=None,

google_place_id=None, google_place_type=None, **kwargs)
Bases: JsonDeserializable
This object represents a venue.
Telegram Documentation: https://core.telegram.org/bots/api#venue
Parameters
• location (telebot.types.Location) – Venue location. Can’t be a live location
• title (str) – Name of the venue
• address (str) – Address of the venue
• foursquare_id (str) – Optional. Foursquare identifier of the venue
• foursquare_type (str) – Optional. Foursquare type of the venue. (For example,
“arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
• google_place_id (str) – Optional. Google Places identifier of the venue
• google_place_type (str) – Optional. Google Places type of the venue. (See supported
types.)
Returns
Instance of the class
Return type
telebot.types.Venue
class telebot.types.Video(file_id, file_unique_id, width, height, duration, thumbnail=None, file_name=None,
mime_type=None, file_size=None, **kwargs)
Bases: JsonDeserializable
This object represents a video file.
Telegram Documentation: https://core.telegram.org/bots/api#video
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• width (int) – Video width as defined by sender
• height (int) – Video height as defined by sender
• duration (int) – Duration of the video in seconds as defined by sender
• thumbnail (telebot.types.PhotoSize) – Optional. Video thumbnail
• file_name (str) – Optional. Original filename as defined by sender

1.3. Content 113

pyTelegramBotAPI, Release 4.25.0

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

• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.
Returns
Instance of the class
Return type
telebot.types.Video
property thumb: PhotoSize | None

class telebot.types.VideoChatEnded(duration, **kwargs)

Bases: JsonDeserializable
This object represents a service message about a video chat ended in the chat.
Telegram Documentation: https://core.telegram.org/bots/api#videochatended
Parameters
duration (int) – Video chat duration in seconds
Returns
Instance of the class
Return type
telebot.types.VideoChatEnded
class telebot.types.VideoChatParticipantsInvited(users=None, **kwargs)
Bases: JsonDeserializable
This object represents a service message about new members invited to a video chat.
Telegram Documentation: https://core.telegram.org/bots/api#videochatparticipantsinvited
Parameters
users (list of telebot.types.User) – New members that were invited to the video chat
Returns
Instance of the class
Return type
telebot.types.VideoChatParticipantsInvited
class telebot.types.VideoChatScheduled(start_date, **kwargs)
Bases: JsonDeserializable
This object represents a service message about a video chat scheduled in the chat.
Telegram Documentation: https://core.telegram.org/bots/api#videochatscheduled
Parameters
start_date (int) – Point in time (Unix timestamp) when the video chat is supposed to be
started by a chat administrator
Returns
Instance of the class
Return type
telebot.types.VideoChatScheduled

114 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

class telebot.types.VideoChatStarted
Bases: JsonDeserializable
This object represents a service message about a video chat started in the chat. Currently holds no information.
class telebot.types.VideoNote(file_id, file_unique_id, length, duration, thumbnail=None, file_size=None,
**kwargs)
Bases: JsonDeserializable
This object represents a video message (available in Telegram apps as of v.4.0).
Telegram Documentation: https://core.telegram.org/bots/api#videonote
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• length (int) – Video width and height (diameter of the video message) as defined by sender
• duration (int) – Duration of the video in seconds as defined by sender
• thumbnail (telebot.types.PhotoSize) – Optional. Video thumbnail
• file_size (int) – Optional. File size in bytes
Returns
Instance of the class
Return type
telebot.types.VideoNote
property thumb: PhotoSize | None

class telebot.types.Voice(file_id, file_unique_id, duration, mime_type=None, file_size=None, **kwargs)

Bases: JsonDeserializable
This object represents a voice note.
Telegram Documentation: https://core.telegram.org/bots/api#voice
Parameters
• file_id (str) – Identifier for this file, which can be used to download or reuse the file
• file_unique_id (str) – Unique identifier for this file, which is supposed to be the same
over time and for different bots. Can’t be used to download or reuse the file.
• duration (int) – Duration of the audio in seconds as defined by sender
• mime_type (str) – Optional. MIME type of the file as defined by sender
• file_size (int) – Optional. File size in bytes. It can be bigger than 2^31 and some pro-
gramming languages may have difficulty/silent defects in interpreting it. But it has at most 52
significant bits, so a signed 64-bit integer or double-precision float type are safe for storing
this value.
Returns
Instance of the class
Return type
telebot.types.Voice

1.3. Content 115

pyTelegramBotAPI, Release 4.25.0

class telebot.types.VoiceChatEnded(*args, **kwargs)

Bases: VideoChatEnded
Deprecated, use VideoChatEnded instead.
class telebot.types.VoiceChatParticipantsInvited(*args, **kwargs)
Bases: VideoChatParticipantsInvited
Deprecated, use VideoChatParticipantsInvited instead.
class telebot.types.VoiceChatScheduled(*args, **kwargs)
Bases: VideoChatScheduled
Deprecated, use VideoChatScheduled instead.
class telebot.types.VoiceChatStarted
Bases: VideoChatStarted
Deprecated, use VideoChatStarted instead.
class telebot.types.WebAppData(data, button_text, **kwargs)
Bases: JsonDeserializable, Dictionaryable
Describes data sent from a Web App to the bot.
Telegram Documentation: https://core.telegram.org/bots/api#webappdata
Parameters
• data (str) – The data. Be aware that a bad client can send arbitrary data in this field.
• button_text (str) – Text of the web_app keyboard button from which the Web App was
opened. Be aware that a bad client can send arbitrary data in this field.
Returns
Instance of the class
Return type
telebot.types.WebAppData
class telebot.types.WebAppInfo(url, **kwargs)
Bases: JsonDeserializable, Dictionaryable
Describes a Web App.
Telegram Documentation: https://core.telegram.org/bots/api#webappinfo
Parameters
url (str) – An HTTPS URL of a Web App to be opened with additional data as specified in
Initializing Web Apps
Returns
Instance of the class
Return type
telebot.types.WebAppInfo
class telebot.types.WebhookInfo(url, has_custom_certificate, pending_update_count, ip_address=None,
last_error_date=None, last_error_message=None,
last_synchronization_error_date=None, max_connections=None,
allowed_updates=None, **kwargs)
Bases: JsonDeserializable
Describes the current status of a webhook.

116 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

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

Parameters
• url (str) – Webhook URL, may be empty if webhook is not set up
• has_custom_certificate (bool) – True, if a custom certificate was provided for webhook
certificate checks
• pending_update_count (int) – Number of updates awaiting delivery
• ip_address (str) – Optional. Currently used webhook IP address
• last_error_date (int) – Optional. Unix time for the most recent error that happened
when trying to deliver an update via webhook
• last_error_message (str) – Optional. Error message in human-readable format for the
most recent error that happened when trying to deliver an update via webhook
• last_synchronization_error_date (int) – Optional. Unix time of the most recent
error that happened when trying to synchronize available updates with Telegram datacenters
• max_connections (int) – Optional. The maximum allowed number of simultaneous
HTTPS connections to the webhook for update delivery
• allowed_updates (list of str) – Optional. A list of update types the bot is subscribed
to. Defaults to all update types except chat_member
Returns
Instance of the class
Return type
telebot.types.WebhookInfo
class telebot.types.WriteAccessAllowed(from_request: bool | None = None, web_app_name: str | None =
None, from_attachment_menu: bool | None = None, **kwargs)
Bases: JsonDeserializable
This object represents a service message about a user allowing a bot to write messages after adding it to the
attachment menu, launching a Web App from a link, or accepting an explicit request from a Web App sent by
the method requestWriteAccess.
Telegram documentation: https://core.telegram.org/bots/api#writeaccessallowed
Parameters
• from_request (bool) – Optional. True, if the access was granted after the user accepted
an explicit request from a Web App sent by the method requestWriteAccess
• web_app_name (str) – Optional. Name of the Web App which was launched from a link
• from_attachment_menu (bool) – Optional. True, if the access was granted when the bot
was added to the attachment or side menu
telebot.types.log_deprecation_warning(warning_message, logging_level=30)
Logs a deprecation warning message.

1.3.4 TeleBot version

TeleBot methods

1.3. Content 117

pyTelegramBotAPI, Release 4.25.0

class telebot.ExceptionHandler
Bases: object
Class for handling exceptions while Polling
handle(exception)

class telebot.Handler(callback, *args, **kwargs)

Bases: object
Class for (next step|reply) handlers.
telebot.REPLY_MARKUP_TYPES
telebot
Type
Module
alias of InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply
class telebot.TeleBot(token: str, parse_mode: str | None = None, threaded: bool | None = True,
skip_pending: bool | None = False, num_threads: int | None = 2, next_step_backend:
~telebot.handler_backends.HandlerBackend | None = None, reply_backend:
~telebot.handler_backends.HandlerBackend | None = None, exception_handler:
~telebot.ExceptionHandler | None = None, last_update_id: int | None = 0,
suppress_middleware_excepions: bool | None = False, state_storage:
~telebot.storage.base_storage.StateStorageBase | None =
<telebot.storage.memory_storage.StateMemoryStorage object>,
use_class_middlewares: bool | None = False, disable_web_page_preview: bool | None
= None, disable_notification: bool | None = None, protect_content: bool | None = None,
allow_sending_without_reply: bool | None = None, colorful_logs: bool | None = False,
validate_token: bool | None = True)
Bases: object
This is the main synchronous class for Bot.
It allows you to add handlers for different kind of updates.
Usage:

Listing 4: Creating instance of TeleBot

from telebot import TeleBot
bot = TeleBot('token') # get token from @BotFather
# now you can register other handlers/update listeners,
# and use bot methods.

See more examples in examples/ directory: https://github.com/eternnoir/pyTelegramBotAPI/tree/master/

examples

ò Note

Install coloredlogs module to specify colorful_logs=True

Parameters
• token (str) – Token of a bot, should be obtained from @BotFather
• parse_mode (str, optional) – Default parse mode, defaults to None

118 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• threaded (bool, optional) – Threaded or not, defaults to True

• skip_pending (bool, optional) – Skips pending updates, defaults to False
• num_threads (int, optional) – Number of maximum parallel threads, defaults to 2
• next_step_backend (telebot.handler_backends.HandlerBackend, optional) –
Next step backend class, defaults to None
• reply_backend (telebot.handler_backends.HandlerBackend, optional) – Reply
step handler class, defaults to None
• exception_handler (telebot.ExceptionHandler, optional) – Exception handler to
handle errors, defaults to None
• last_update_id (int, optional) – Last update’s id, defaults to 0
• suppress_middleware_excepions (bool, optional) – Supress middleware exceptions,
defaults to False
• state_storage (telebot.storage.StateStorageBase, optional) – Storage for states,
defaults to StateMemoryStorage()
• use_class_middlewares (bool, optional) – Use class middlewares, defaults to False
• disable_web_page_preview (bool, optional) – Default value for dis-
able_web_page_preview, defaults to None
• disable_notification (bool, optional) – Default value for disable_notification, defaults
to None
• protect_content (bool, optional) – Default value for protect_content, defaults to None
• allow_sending_without_reply (bool, optional) – Default value for al-
low_sending_without_reply, defaults to None
• colorful_logs (bool, optional) – Outputs colorful logs
• validate_token (bool, optional) – Validate token, defaults to True;
Raises
• ImportError – If coloredlogs module is not installed and colorful_logs is True
• ValueError – If token is invalid

add_custom_filter(custom_filter: SimpleCustomFilter | AdvancedCustomFilter)

Create custom filter.

Listing 5: Example on checking the text of a message

class TextMatchFilter(AdvancedCustomFilter):
key = 'text'

def check(self, message, text):

return text == message.text

Parameters
• custom_filter – Class with check(message) method.
• custom_filter – Custom filter class with key.

1.3. Content 119

pyTelegramBotAPI, Release 4.25.0

add_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None, **kwargs) → None
Add data to states.
Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
• kwargs – Data to add
Returns
None
add_sticker_to_set(user_id: int, name: str, emojis: List[str] | str, png_sticker: str | Any | None = None,
tgs_sticker: str | Any | None = None, webm_sticker: str | Any | None = None,
mask_position: MaskPosition | None = None, sticker: InputSticker | None = None) →
bool
Use this method to add a new sticker to a set created by the bot. The format of the added sticker must match
the format of the other stickers in the set. Emoji sticker sets can have up to 200 stickers. Animated and
video sticker sets can have up to 50 stickers. Static sticker sets can have up to 120 stickers. Returns True
on success.
Telegram documentation: https://core.telegram.org/bots/api#addstickertoset

ò Note

**_sticker, mask_position, emojis parameters are deprecated, use stickers instead

Parameters
• user_id (int) – User identifier of created sticker set owner
• name (str) – Sticker set name
• emojis (str) – One or more emoji corresponding to the sticker
• png_sticker (str or filelike object) – PNG image with the sticker, must be up to
512 kilobytes in size, dimensions must not exceed 512px, and either width or height must
be exactly 512px. Pass a file_id as a String to send a file that already exists on the Telegram
servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload
a new one using multipart/form-data.
• tgs_sticker (str or filelike object) – TGS animation with the sticker, uploaded
using multipart/form-data.
• webm_sticker (str or filelike object) – WebM animation with the sticker, uploaded
using multipart/form-data.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces
• sticker (telebot.types.InputSticker) – A JSON-serialized object for sticker to be
added to the sticker set

120 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
On success, True is returned.
Return type
bool

answer_callback_query(callback_query_id: int, text: str | None = None, show_alert: bool | None = None,
url: str | None = None, cache_time: int | None = None) → bool
Use this method to send answers to callback queries sent from inline keyboards. The answer will be dis-
played to the user as a notification at the top of the chat screen or as an alert.
Telegram documentation: https://core.telegram.org/bots/api#answercallbackquery
Parameters
• callback_query_id (int) – Unique identifier for the query to be answered
• text (str) – Text of the notification. If not specified, nothing will be shown to the user,
0-200 characters
• show_alert (bool) – If True, an alert will be shown by the client instead of a notification
at the top of the chat screen. Defaults to false.
• url (str) – URL that will be opened by the user’s client. If you have created a Game and
accepted the conditions via @BotFather, specify the URL that opens your game - note that
this will only work if the query comes from a callback_game button.
• cache_time – The maximum amount of time in seconds that the result of the callback
query may be cached client-side. Telegram apps will support caching starting in version
3.14. Defaults to 0.
Returns
On success, True is returned.
Return type
bool
answer_inline_query(inline_query_id: str, results: List[Any], cache_time: int | None = None,
is_personal: bool | None = None, next_offset: str | None = None, switch_pm_text:
str | None = None, switch_pm_parameter: str | None = None, button:
InlineQueryResultsButton | None = None) → bool
Use this method to send answers to an inline query. On success, True is returned. No more than 50 results
per query are allowed.
Telegram documentation: https://core.telegram.org/bots/api#answerinlinequery
Parameters
• inline_query_id (str) – Unique identifier for the answered query
• results (list of types.InlineQueryResult) – Array of results for the inline query
• cache_time (int) – The maximum amount of time in seconds that the result of the inline
query may be cached on the server.
• is_personal (bool) – Pass True, if results may be cached on the server side only for the
user that sent the query.
• next_offset (str) – Pass the offset that a client should send in the next query with the
same text to receive more results.

1.3. Content 121

pyTelegramBotAPI, Release 4.25.0

• switch_pm_parameter (str) – Deep-linking parameter for the /start message sent to the
bot when user presses the switch button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are
allowed. Example: An inline bot that sends YouTube videos can ask the user to connect
the bot to their YouTube account to adapt search results accordingly. To do this, it displays
a ‘Connect your YouTube account’ button above the results, or even before showing any.
The user presses the button, switches to a private chat with the bot and, in doing so, passes
a start parameter that instructs the bot to return an OAuth link. Once done, the bot can offer
a switch_inline button so that the user can easily return to the chat where they wanted to
use the bot’s inline capabilities.
• switch_pm_text (str) – Parameter for the start message sent to the bot when user presses
the switch button
• button (types.InlineQueryResultsButton) – A JSON-serialized object describing
a button to be shown above inline query results
Returns
On success, True is returned.
Return type
bool
answer_pre_checkout_query(pre_checkout_query_id: str, ok: bool, error_message: str | None = None)
→ bool
Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in
the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout
queries. On success, True is returned.

ò Note

The Bot API must receive an answer within 10 seconds after the pre-checkout query was sent.

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

Parameters
• pre_checkout_query_id (int) – Unique identifier for the query to be answered
• ok (bool) – Specify True if everything is alright (goods are available, etc.) and the bot is
ready to proceed with the order. Use False if there are any problems.
• error_message (str) – Required if ok is False. Error message in human readable form
that explains the reason for failure to proceed with the checkout (e.g. “Sorry, somebody just
bought the last of our amazing black T-shirts while you were busy filling out your payment
details. Please choose a different color or garment!”). Telegram will display this message
to the user.
Returns
On success, True is returned.
Return type
bool
answer_shipping_query(shipping_query_id: str, ok: bool, shipping_options: List[ShippingOption] | None
= None, error_message: str | None = None) → bool
Asks for an answer to a shipping question.
Telegram documentation: https://core.telegram.org/bots/api#answershippingquery

122 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Parameters
• shipping_query_id (str) – Unique identifier for the query to be answered
• ok (bool) – Specify True if delivery to the specified address is possible and False if there
are any problems (for example, if delivery to the specified address is not possible)
• shipping_options (list of ShippingOption) – Required if ok is True. A JSON-
serialized array of available shipping options.
• error_message (str) – Required if ok is False. Error message in human readable form
that explains why it is impossible to complete the order (e.g. “Sorry, delivery to your
desired address is unavailable’). Telegram will display this message to the user.
Returns
On success, True is returned.
Return type
bool
answer_web_app_query(web_app_query_id: str, result: InlineQueryResultBase) → SentWebAppMessage
Use this method to set the result of an interaction with a Web App and send a corresponding message on
behalf of the user to the chat from which the query originated. On success, a SentWebAppMessage object
is returned.
Telegram Documentation: https://core.telegram.org/bots/api#answerwebappquery
Parameters
• web_app_query_id (str) – Unique identifier for the query to be answered
• result (telebot.types.InlineQueryResultBase) – A JSON-serialized object de-
scribing the message to be sent
Returns
On success, a SentWebAppMessage object is returned.
Return type
telebot.types.SentWebAppMessage
approve_chat_join_request(chat_id: str | int, user_id: int | str) → bool
Use this method to approve a chat join request. The bot must be an administrator in the chat for this to work
and must have the can_invite_users administrator right. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#approvechatjoinrequest
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int or str) – Unique identifier of the target user
Returns
True on success.
Return type
bool
ban_chat_member(chat_id: int | str, user_id: int, until_date: int | datetime | None = None, revoke_messages:
bool | None = None) → bool
Use this method to ban a user in a group, a supergroup or a channel. In the case of supergroups and channels,
the user will not be able to return to the chat on their own using invite links, etc., unless unbanned first.
Returns True on success.

1.3. Content 123

pyTelegramBotAPI, Release 4.25.0

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

Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @channelusername)
• user_id (int) – Unique identifier of the target user
• until_date (int or datetime) – Date when the user will be unbanned, unix time. If
user is banned for more than 366 days or less than 30 seconds from the current time they
are considered to be banned forever
• revoke_messages (bool) – Pass True to delete all messages from the chat for the user
that is being removed. If False, the user will be able to see messages in the group that were
sent before the user was removed. Always True for supergroups and channels.
Returns
Returns True on success.
Return type
bool
ban_chat_sender_chat(chat_id: int | str, sender_chat_id: int | str) → bool
Use this method to ban a channel chat in a supergroup or a channel. The owner of the chat will not be able
to send messages and join live streams on behalf of the chat, unless it is unbanned first. The bot must be
an administrator in the supergroup or channel for this to work and must have the appropriate administrator
rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#banchatsenderchat
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sender_chat_id (int or str) – Unique identifier of the target sender chat
Returns
True on success.
Return type
bool
business_connection_handler(func=None, **kwargs)
Handles new incoming business connection state.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
business_message_handler(commands: List[str] | None = None, regexp: str | None = None, func:
Callable | None = None, content_types: List[str] | None = None, **kwargs)
Handles New incoming message of any kind(for business accounts, see bot api 7.2 for more) - text, photo,
sticker, etc. As a parameter to the decorator function, it passes telebot.types.Message object. All
message handlers are tested in the order they were added.
Example:

124 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Listing 6: Usage of business_message_handler

bot = TeleBot('TOKEN')

# Handles all messages which text matches regexp.

@bot.business_message_handler(regexp='someregexp')
def command_help(message):
bot.send_message(message.chat.id, 'Did someone call for help?')

# Handle all sent documents of type 'text/plain'.

@bot.business_message_handler(func=lambda message: message.document.mime_type␣
˓→== 'text/plain',

content_types=['document'])
def command_handle_document(message):
bot.send_message(message.chat.id, 'Document received, sir!')

# Handle all other messages.

@bot.business_message_handler(func=lambda message: True, content_types=['audio',
˓→ 'photo', 'voice', 'video', 'document',

'text', 'location', 'contact', 'sticker'])

def default_command(message):
bot.send_message(message.chat.id, "This is the default command handler.")

Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (lambda) – Optional lambda function. The lambda receives the message to test as
the first parameter. It must return True if the command should handle the message.
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function

callback_query_handler(func=None, **kwargs)
Handles new incoming callback query. As a parameter to the decorator function, it passes telebot.
types.CallbackQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
channel_post_handler(commands=None, regexp=None, func=None, content_types=None, **kwargs)
Handles new incoming channel post of any kind - text, photo, sticker, etc. As a parameter to the decorator
function, it passes telebot.types.Message object.
Parameters

1.3. Content 125

pyTelegramBotAPI, Release 4.25.0

• commands (list of str) – Optional list of strings (commands to handle).

• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_boost_handler(func=None, **kwargs)
Handles new incoming chat boost state. it passes telebot.types.ChatBoostUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_join_request_handler(func=None, **kwargs)
Handles a request to join the chat has been sent. The bot must have the can_invite_users administrator right
in the chat to receive these updates. As a parameter to the decorator function, it passes telebot.types.
ChatJoinRequest object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_member_handler(func=None, **kwargs)
Handles update in a status of a user in a chat. The bot must be an administrator in the chat and must
explicitly specify “chat_member” in the list of allowed_updates to receive these updates. As a parameter
to the decorator function, it passes telebot.types.ChatMemberUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chosen_inline_handler(func, **kwargs)
Handles the result of an inline query that was chosen by a user and sent to their chat partner. Please see
our documentation on the feedback collecting for details on how to enable these updates for your bot. As a
parameter to the decorator function, it passes telebot.types.ChosenInlineResult object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

126 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
None
clear_reply_handlers(message: Message) → None
Clears all callback functions registered by register_for_reply() and register_for_reply_by_message_id().
Parameters
message (telebot.types.Message) – The message for which we want to clear reply han-
dlers
Returns
None
clear_reply_handlers_by_message_id(message_id: int) → None
Clears all callback functions registered by register_for_reply() and register_for_reply_by_message_id().
Parameters
message_id (int) – The message id for which we want to clear reply handlers
Returns
None
clear_step_handler(message: Message) → None
Clears all callback functions registered by register_next_step_handler().
Parameters
message (telebot.types.Message) – The message for which we want to handle new mes-
sage after that in same chat.
Returns
None
clear_step_handler_by_chat_id(chat_id: int | str) → None
Clears all callback functions registered by register_next_step_handler().
Parameters
chat_id (int or str) – The chat for which we want to clear next step handlers
Returns
None
close() → bool
Use this method to close the bot instance before moving it from one local server to another. You need to
delete the webhook before calling this method to ensure that the bot isn’t launched again after server restart.
The method will return error 429 in the first 10 minutes after the bot is launched. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#close
Returns
bool
close_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to close an open topic in a forum supergroup chat. The bot must be an administrator in the
chat for this to work and must have the can_manage_topics administrator rights, unless it is the creator of
the topic. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#closeforumtopic
Aram chat_id
Unique identifier for the target chat or username of the target channel (in the format @chan-
nelusername)

1.3. Content 127

pyTelegramBotAPI, Release 4.25.0

Parameters
message_thread_id (int) – Identifier of the topic to close
Returns
On success, True is returned.
Return type
bool
close_general_forum_topic(chat_id: int | str) → bool
Use this method to close the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#closegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
copy_message(chat_id: int | str, from_chat_id: int | str, message_id: int, caption: str | None = None,
parse_mode: str | None = None, caption_entities: List[MessageEntity] | None = None,
disable_notification: bool | None = None, protect_content: bool | None = None,
reply_to_message_id: int | None = None, allow_sending_without_reply: bool | None = None,
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, timeout: int | None = None, message_thread_id: int | None =
None, reply_parameters: ReplyParameters | None = None, show_caption_above_media: bool
| None = None, allow_paid_broadcast: bool | None = None) → MessageID
Use this method to copy messages of any kind. Service messages, paid media messages, giveaway mes-
sages, giveaway winners messages, and invoice messages can’t be copied. A quiz poll can be copied only
if the value of the field correct_option_id is known to the bot. The method is analogous to the method for-
wardMessage, but the copied message doesn’t have a link to the original message. Returns the MessageId
of the sent message on success.
Telegram documentation: https://core.telegram.org/bots/api#copymessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_id (int) – Message identifier in the chat specified in from_chat_id
• caption (str) – New caption for media, 0-1024 characters after entities parsing. If not
specified, the original caption is kept
• parse_mode (str) – Mode for parsing entities in the new caption.
• caption_entities (Array of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the new caption, which can be specified instead of
parse_mode
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.

128 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• allow_sending_without_reply (bool) – deprecated.

• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Additional parameters for
replies to messages
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the MessageId of the sent message is returned.
Return type
telebot.types.MessageID
copy_messages(chat_id: str | int, from_chat_id: str | int, message_ids: List[int], disable_notification: bool |
None = None, message_thread_id: int | None = None, protect_content: bool | None = None,
remove_caption: bool | None = None) → List[MessageID]
Use this method to copy messages of any kind. If some of the specified messages can’t be found or copied,
they are skipped. Service messages, paid media messages, giveaway messages, giveaway winners mes-
sages, and invoice messages can’t be copied. A quiz poll can be copied only if the value of the field
correct_option_id is known to the bot. The method is analogous to the method forwardMessages, but the
copied messages don’t have a link to the original message. Album grouping is kept for copied messages.
On success, an array of MessageId of the sent messages is returned.
Telegram documentation: https://core.telegram.org/bots/api#copymessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_ids (list of int) – Message identifiers in the chat specified in from_chat_id
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound
• message_thread_id (int) – Identifier of a message thread, in which the messages will
be sent
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
• remove_caption (bool) – Pass True to copy the messages without their captions

1.3. Content 129

pyTelegramBotAPI, Release 4.25.0

Returns
On success, an array of MessageId of the sent messages is returned.
Return type
list of telebot.types.MessageID
create_chat_invite_link(chat_id: int | str, name: str | None = None, expire_date: int | datetime | None =
None, member_limit: int | None = None, creates_join_request: bool | None =
None) → ChatInviteLink
Use this method to create an additional invite link for a chat. The bot must be an administrator in the chat for
this to work and must have the appropriate administrator rights. The link can be revoked using the method
revokeChatInviteLink. Returns the new invite link as ChatInviteLink object.
Telegram documentation: https://core.telegram.org/bots/api#createchatinvitelink
Parameters
• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• expire_date (int or datetime) – Point in time (Unix timestamp) when the link will
expire
• member_limit (int) – Maximum number of users that can be members of the chat simul-
taneously
• creates_join_request (bool) – True, if users joining the chat via the link need to be
approved by chat administrators. If True, member_limit can’t be specified
Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
create_chat_subscription_invite_link(chat_id: int | str, subscription_period: int,
subscription_price: int, name: str | None = None) →
ChatInviteLink
Use this method to create a subscription invite link for a channel chat. The bot must have the
can_invite_users administrator rights. The link can be edited using the method editChatSubscriptionIn-
viteLink or revoked using the method revokeChatInviteLink. Returns the new invite link as a ChatIn-
viteLink object.
Telegram documentation: https://core.telegram.org/bots/api#createchatsubscriptioninvitelink
Parameters
• chat_id (int or str) – Unique identifier for the target channel chat or username of the
target channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• subscription_period (int) – The number of seconds the subscription will be active
for before the next payment. Currently, it must always be 2592000 (30 days).
• subscription_price (int) – The amount of Telegram Stars a user must pay initially
and after each subsequent subscription period to be a member of the chat; 1-2500
Returns
Returns the new invite link as a ChatInviteLink object.

130 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.ChatInviteLink
create_forum_topic(chat_id: int, name: str, icon_color: int | None = None, icon_custom_emoji_id: str |
None = None) → ForumTopic
Use this method to create a topic in a forum supergroup chat. The bot must be an administrator in the chat
for this to work and must have the can_manage_topics administrator rights. Returns information about the
created topic as a ForumTopic object.
Telegram documentation: https://core.telegram.org/bots/api#createforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Name of the topic, 1-128 characters
• icon_color (int) – Color of the topic icon in RGB format. Currently, must be one of
0x6FB9F0, 0xFFD67E, 0xCB86DB, 0x8EEE98, 0xFF93B2, or 0xFB6F5F
• icon_custom_emoji_id (str) – Custom emoji for the topic icon. Must be an emoji of
type “tgs” and must be exactly 1 character long
Returns
On success, information about the created topic is returned as a ForumTopic object.
Return type
telebot.types.ForumTopic
create_invoice_link(title: str, description: str, payload: str, provider_token: str | None, currency: str,
prices: List[LabeledPrice], max_tip_amount: int | None = None,
suggested_tip_amounts: List[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, subscription_period: int | None = None, business_connection_id: str
| None = None) → str
Use this method to create a link for an invoice. Returns the created invoice link as String on success.
Telegram documentation: https://core.telegram.org/bots/api#createinvoicelink
Parameters
• business_connection_id (str) – Unique identifier of the business connection on behalf
of which the link will be created
• title (str) – Product name, 1-32 characters
• description (str) – Product description, 1-255 characters
• payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to
the user, use for your internal processes.
• provider_token (str) – Payments provider token, obtained via @Botfather; Pass None
to omit the parameter to use “XTR” currency
• currency (str) – Three-letter ISO 4217 currency code, see https://core.telegram.org/
bots/payments#supported-currencies

1.3. Content 131

pyTelegramBotAPI, Release 4.25.0

• prices (list of types.LabeledPrice) – Price breakdown, a list of components (e.g.

product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• subscription_period (int) – The number of seconds the subscription will be active
for before the next payment. The currency must be set to “XTR” (Telegram Stars) if the
parameter is used. Currently, it must always be 2592000 (30 days) if specified.
• max_tip_amount (int) – The maximum accepted amount for tips in the smallest units of
the currency
• suggested_tip_amounts (list of int) – A JSON-serialized array of suggested
amounts of tips in the smallest units of the currency. At most 4 suggested tip amounts
can be specified. The suggested tip amounts must be positive, passed in a strictly increased
order and must not exceed max_tip_amount.
• provider_data (str) – A JSON-serialized data about the invoice, which will be shared
with the payment provider. A detailed description of required fields should be provided by
the payment provider.
• photo_url (str) – URL of the product photo for the invoice. Can be a photo of the goods
or a photo of the invoice. People like it better when they see a photo of what they are paying
for.
• photo_size (int) – Photo size in bytes
• photo_width (int) – Photo width
• photo_height (int) – Photo height
• need_name (bool) – Pass True, if you require the user’s full name to complete the order
• need_phone_number (bool) – Pass True, if you require the user’s phone number to com-
plete the order
• need_email (bool) – Pass True, if you require the user’s email to complete the order
• need_shipping_address (bool) – Pass True, if you require the user’s shipping address
to complete the order
• send_phone_number_to_provider (bool) – Pass True, if user’s phone number should
be sent to provider
• send_email_to_provider (bool) – Pass True, if user’s email address should be sent to
provider
• is_flexible (bool) – Pass True, if the final price depends on the shipping method
Returns
Created invoice link as String on success.
Return type
str
create_new_sticker_set(user_id: int, name: str, title: str, emojis: List[str] | None = None, png_sticker:
Any | str = None, tgs_sticker: Any | str = None, webm_sticker: Any | str = None,
contains_masks: bool | None = None, sticker_type: str | None = None,
mask_position: MaskPosition | None = None, needs_repainting: bool | None =
None, stickers: List[InputSticker] = None, sticker_format: str | None = None) →
bool
Use this method to create new sticker set owned by a user. The bot will be able to edit the created sticker
set. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#createnewstickerset

132 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

ò Note

Fields *_sticker are deprecated, pass a list of stickers to stickers parameter instead.

Parameters
• user_id (int) – User identifier of created sticker set owner
• name (str) – Short name of sticker set, to be used in t.me/addstickers/ URLs (e.g., animals).
Can contain only English letters, digits and underscores. Must begin with a letter, can’t con-
tain consecutive underscores and must end in “_by_<bot_username>”. <bot_username>
is case insensitive. 1-64 characters.
• title (str) – Sticker set title, 1-64 characters
• emojis (str) – One or more emoji corresponding to the sticker
• png_sticker (str) – PNG image with the sticker, must be up to 512 kilobytes in size,
dimensions must not exceed 512px, and either width or height must be exactly 512px. Pass
a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP
URL as a String for Telegram to get a file from the Internet, or upload a new one using
multipart/form-data.
• tgs_sticker (str) – TGS animation with the sticker, uploaded using multipart/form-
data.
• webm_sticker (str) – WebM animation with the sticker, uploaded using multipart/form-
data.
• contains_masks (bool) – Pass True, if a set of mask stickers should be created. Depre-
cated since Bot API 6.2, use sticker_type instead.
• sticker_type (str) – Type of stickers in the set, pass “regular”, “mask”, or “cus-
tom_emoji”. By default, a regular sticker set is created.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces
• needs_repainting (bool) – Pass True if stickers in the sticker set must be repainted to
the color of text when used in messages, the accent color if used as emoji status, white on
chat photos, or another appropriate color based on context; for custom emoji sticker sets
only
• stickers (list of telebot.types.InputSticker) – List of stickers to be added to
the set
• sticker_format (str) – deprecated
Returns
On success, True is returned.
Return type
bool

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

Use this method to decline a chat join request. The bot must be an administrator in the chat for this to work
and must have the can_invite_users administrator right. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#declinechatjoinrequest
Parameters

1.3. Content 133

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int or str) – Unique identifier of the target user
Returns
True on success.
Return type
bool
delete_chat_photo(chat_id: int | str) → bool
Use this method to delete a chat photo. Photos can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights. Returns True on
success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are
Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#deletechatphoto
Parameters
chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
Returns
True on success.
Return type
bool
delete_chat_sticker_set(chat_id: int | str) → bool
Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the chat
for this to work and must have the appropriate admin rights. Use the field can_set_sticker_set optionally
returned in getChat requests to check if the bot can use this method. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletechatstickerset
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group (in the format @supergroupusername)
Returns
Returns True on success.
Return type
bool
delete_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to delete a topic in a forum supergroup chat. The bot must be an administrator in the chat
for this to work and must have the can_manage_topics administrator rights, unless it is the creator of the
topic. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deleteforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to delete
Returns
On success, True is returned.

134 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
bool
delete_message(chat_id: int | str, message_id: int, timeout: int | None = None) → bool
Use this method to delete a message, including service messages, with the following limitations: - A mes-
sage can only be deleted if it was sent less than 48 hours ago. - A dice message in a private chat can only be
deleted if it was sent more than 24 hours ago. - Bots can delete outgoing messages in private chats, groups,
and supergroups. - Bots can delete incoming messages in private chats. - Bots granted can_post_messages
permissions can delete outgoing messages in channels. - If the bot is an administrator of a group, it can
delete any message there. - If the bot has can_delete_messages permission in a supergroup or a channel, it
can delete any message there. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Identifier of the message to delete
• timeout (int) – Timeout in seconds for the request.
Returns
Returns True on success.
Return type
bool
delete_messages(chat_id: int | str, message_ids: List[int])
Use this method to delete multiple messages simultaneously. If some of the specified messages can’t be
found, they are skipped. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_ids (list of int) – Identifiers of the messages to be deleted
Returns
Returns True on success.
delete_my_commands(scope: BotCommandScope | None = None, language_code: str | None = None) →
bool
Use this method to delete the list of the bot’s commands for the given scope and user language. After
deletion, higher level commands will be shown to affected users. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemycommands
Parameters
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands
Returns
True on success.

1.3. Content 135

pyTelegramBotAPI, Release 4.25.0

Return type
bool
delete_state(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → bool
Fully deletes the storage record of a user in chat.

. Warning

This does NOT set state to None, but deletes the object from storage.

Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
Returns
True on success
Return type
bool

delete_sticker_from_set(sticker: str) → bool

Use this method to delete a sticker from a set created by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletestickerfromset
Parameters
sticker – File identifier of the sticker
Returns
On success, True is returned.
Return type
bool
delete_sticker_set(name: str) → bool
Use this method to delete a sticker set. Returns True on success.
Parameters
name (str) – Sticker set name
Returns
Returns True on success.
Return type
bool
delete_webhook(drop_pending_updates: bool | None = None, timeout: int | None = None) → bool
Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True
on success.
Telegram documentation: https://core.telegram.org/bots/api#deletewebhook
Parameters
• drop_pending_updates – Pass True to drop all pending updates, defaults to None
• timeout (int, optional) – Request connection timeout, defaults to None

136 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Returns True on success.
Return type
bool
deleted_business_messages_handler(func=None, **kwargs)
Handles new incoming deleted messages state.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
disable_save_next_step_handlers()
Disable saving next step handlers (by default saving disable)
This function is left to keep backward compatibility whose purpose was to disable file saving capability
for handlers. For the same purpose, MemoryHandlerBackend is reassigned as a new next_step_backend
backend instead of FileHandlerBackend.
disable_save_reply_handlers()
Disable saving next step handlers (by default saving disable)
This function is left to keep backward compatibility whose purpose was to disable file saving capability for
handlers. For the same purpose, MemoryHandlerBackend is reassigned as a new reply_backend backend
instead of FileHandlerBackend.
download_file(file_path: str) → bytes
Downloads file.
Parameters
file_path (str) – Path where the file should be downloaded.
Returns
bytes
Return type
bytes
edit_chat_invite_link(chat_id: int | str, invite_link: str | None = None, name: str | None = None,
expire_date: int | datetime | None = None, member_limit: int | None = None,
creates_join_request: bool | None = None) → ChatInviteLink
Use this method to edit a non-primary invite link created by the bot. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#editchatinvitelink
Parameters
• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• invite_link (str) – The invite link to edit
• expire_date (int or datetime) – Point in time (Unix timestamp) when the link will
expire

1.3. Content 137

pyTelegramBotAPI, Release 4.25.0

• member_limit (int) – Maximum number of users that can be members of the chat simul-
taneously
• creates_join_request (bool) – True, if users joining the chat via the link need to be
approved by chat administrators. If True, member_limit can’t be specified
Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
edit_chat_subscription_invite_link(chat_id: int | str, invite_link: str, name: str | None = None) →
ChatInviteLink
Use this method to edit a subscription invite link created by the bot. The bot must have the can_invite_users
administrator rights. Returns the edited invite link as a ChatInviteLink object.
Telegram documentation: https://core.telegram.org/bots/api#editchatsubscriptioninvitelink
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• invite_link (str) – The invite link to edit
• name (str) – Invite link name; 0-32 characters
Returns
Returns the edited invite link as a ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
edit_forum_topic(chat_id: int | str, message_thread_id: int, name: str | None = None,
icon_custom_emoji_id: str | None = None) → bool
Use this method to edit name and icon of a topic in a forum supergroup chat. The bot must be an admin-
istrator in the chat for this to work and must have can_manage_topics administrator rights, unless it is the
creator of the topic. Returns True on success.
Telegram Documentation: https://core.telegram.org/bots/api#editforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to edit
• name (str) – Optional, New name of the topic, 1-128 characters. If not specififed or empty,
the current name of the topic will be kept
• icon_custom_emoji_id (str) – Optional, New unique identifier of the custom emoji
shown as the topic icon. Use getForumTopicIconStickers to get all allowed custom emoji
identifiers. Pass an empty string to remove the icon. If not specified, the current icon will
be kept
Returns
On success, True is returned.
Return type
bool

138 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

edit_general_forum_topic(chat_id: int | str, name: str) → bool

Use this method to edit the name of the ‘General’ topic in a forum supergroup chat. The bot must be an
administrator in the chat for this to work and must have can_manage_topics administrator rights. Returns
True on success.
Telegram documentation: https://core.telegram.org/bots/api#editgeneralforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – New topic name, 1-128 characters
edit_message_caption(caption: str, chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None, reply_markup:
InlineKeyboardMarkup | None = None, show_caption_above_media: bool | None
= None, business_connection_id: str | None = None, timeout: int | None = None)
→ Message | bool
Use this method to edit captions of messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagecaption
Parameters
• caption (str) – New caption of the message
• chat_id (int | str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel
• message_id (int) – Required if inline_message_id is not specified.
• inline_message_id (str) – Required if inline_message_id is not specified. Identifier of
the inline message.
• parse_mode (str) – New caption of the message, 0-1024 characters after entities parsing
• caption_entities (list of types.MessageEntity) – A JSON-serialized array of ob-
jects that describe how the caption should be parsed.
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for an inline key-
board.
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• business_connection_id (str) – Identifier of the business connection to use for the
message
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message | bool

1.3. Content 139

pyTelegramBotAPI, Release 4.25.0

edit_message_live_location(latitude: float, longitude: float, chat_id: int | str | None = None,

message_id: int | None = None, inline_message_id: str | None = None,
reply_markup: InlineKeyboardMarkup | None = None, timeout: int | None
= None, horizontal_accuracy: float | None = None, heading: int | None =
None, proximity_alert_radius: int | None = None, live_period: int | None =
None, business_connection_id: str | None = None) → Message

Use this method to edit live location messages. A location can be edited until its live_period expires
or editing is explicitly
disabled by a call to stopMessageLiveLocation. On success, if the edited message is not an inline
message, the edited Message is returned, otherwise True is returned.
Telegram documentation: https://core.telegram.org/bots/api#editmessagelivelocation
Parameters
• latitude (float) – Latitude of new location
• longitude (float) – Longitude of new location
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the mes-
sage to edit
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – A JSON-serialized object for a new inline keyboard.
• timeout (int) – Timeout in seconds for the request.
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• horizontal_accuracy (float) – The radius of uncertainty for the location, measured
in meters; 0-1500
• heading (int) – Direction in which the user is moving, in degrees. Must be between 1
and 360 if specified.
• proximity_alert_radius (int) – The maximum distance for proximity alerts about
approaching another chat member, in meters. Must be between 1 and 100000 if specified.
• live_period (int) – New period in seconds during which the location can be updated,
starting from the message send date. If 0x7FFFFFFF is specified, then the location can be
updated forever. Otherwise, the new value must not exceed the current live_period by more
than a day, and the live location expiration date must remain within the next 90 days. If not
specified, then live_period remains unchanged
• business_connection_id (str) – Identifier of a business connection
Returns
On success, if the edited message is not an inline message, the edited Message is returned,
otherwise True is returned.
Return type
telebot.types.Message or bool
edit_message_media(media: Any, chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup: InlineKeyboardMarkup | None
= None, business_connection_id: str | None = None, timeout: int | None = None) →
Message | bool

140 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Use this method to edit animation, audio, document, photo, or video messages, or to add media to text
messages. If a message is part of a message album, then it can be edited only to an audio for audio albums,
only to a document for document albums and to a photo or a video otherwise. When an inline message
is edited, a new file can’t be uploaded; use a previously uploaded file via its file_id or specify a URL. On
success, if the edited message is not an inline message, the edited Message is returned, otherwise True is
returned. Note that business messages that were not sent by the bot and do not contain an inline keyboard
can only be edited within 48 hours from the time they were sent.
Telegram documentation: https://core.telegram.org/bots/api#editmessagemedia
Parameters
• media (InputMedia) – A JSON-serialized object for a new media content of the message
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• reply_markup (telebot.types.InlineKeyboardMarkup or
ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply) – A JSON-
serialized object for an inline keyboard.
• business_connection_id (str) – Unique identifier of the business connection
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool
edit_message_reply_markup(chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None, business_connection_id: str | None
= None, timeout: int | None = None) → Message | bool
Use this method to edit only the reply markup of messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagereplymarkup
Parameters
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or
ReplyKeyboardRemove or ForceReply) – A JSON-serialized object for an inline
keyboard.
• business_connection_id (str) – Unique identifier of the business connection

1.3. Content 141

pyTelegramBotAPI, Release 4.25.0

• timeout (int) – Timeout in seconds for the request.

Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool
edit_message_text(text: str, chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, parse_mode: str | None = None, entities:
List[MessageEntity] | None = None, disable_web_page_preview: bool | None = None,
reply_markup: InlineKeyboardMarkup | None = None, link_preview_options:
LinkPreviewOptions | None = None, business_connection_id: str | None = None,
timeout: int | None = None) → Message | bool
Use this method to edit text and game messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagetext
Parameters
• text (str) – New text of the message, 1-4096 characters after entities parsing
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• parse_mode (str) – Mode for parsing entities in the message text.
• entities (List of telebot.types.MessageEntity) – List of special entities that ap-
pear in the message text, which can be specified instead of parse_mode
• disable_web_page_preview (bool) – deprecated.
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for an inline key-
board.
• link_preview_options (LinkPreviewOptions) – A JSON-serialized object for op-
tions used to automatically generate previews for links.
• business_connection_id (str) – Unique identifier of the business connection
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool
edit_user_star_subscription(user_id: int, telegram_payment_charge_id: str, is_canceled: bool) →
bool
Allows the bot to cancel or re-enable extension of a subscription paid in Telegram Stars. Returns True on
success.
Telegram documentation: https://core.telegram.org/bots/api#edituserstarsubscription
Parameters

142 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• user_id (int) – Identifier of the user whose subscription will be edited

• telegram_payment_charge_id (str) – Telegram payment identifier for the subscription
• is_canceled (bool) – Pass True to cancel extension of the user subscription; the sub-
scription must be active up to the end of the current subscription period. Pass False to
allow the user to re-enable a subscription that was previously canceled by the bot.
Returns
On success, True is returned.
Return type
bool
edited_business_message_handler(commands=None, regexp=None, func=None, content_types=None,
**kwargs)
Handles new version of a message(business accounts) that is known to the bot and was edited. As a param-
eter to the decorator function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
None
edited_channel_post_handler(commands=None, regexp=None, func=None, content_types=None,
**kwargs)
Handles new version of a channel post that is known to the bot and was edited. As a parameter to the
decorator function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
edited_message_handler(commands=None, regexp=None, func=None, content_types=None,
chat_types=None, **kwargs)
Handles new version of a message that is known to the bot and was edited. As a parameter to the decorator
function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.

1.3. Content 143

pyTelegramBotAPI, Release 4.25.0

• func (function) – Function executed as a filter

• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• chat_types (list of str) – list of chat types
• kwargs – Optional keyword arguments(custom filters)
Returns
None
enable_save_next_step_handlers(delay: int | None = 120, filename: str | None =
'./.handler-saves/step.save')
Enable saving next step handlers (by default saving disabled)
This function explicitly assigns FileHandlerBackend (instead of Saver) just to keep backward compatibility
whose purpose was to enable file saving capability for handlers. And the same implementation is now
available with FileHandlerBackend
Parameters
• delay (int, optional) – Delay between changes in handlers and saving, defaults to 120
• filename (str, optional) – Filename of save file, defaults to “./.handler-saves/step.save”
Returns
None
enable_save_reply_handlers(delay=120, filename='./.handler-saves/reply.save')
Enable saving reply handlers (by default saving disable)
This function explicitly assigns FileHandlerBackend (instead of Saver) just to keep backward compatibility
whose purpose was to enable file saving capability for handlers. And the same implementation is now
available with FileHandlerBackend
Parameters
• delay (int, optional) – Delay between changes in handlers and saving, defaults to 120
• filename (str, optional) – Filename of save file, defaults to “./.handler-saves/reply.save”
enable_saving_states(filename: str | None = './.state-save/states.pkl')
Enable saving states (by default saving disabled)

ò Note

It is recommended to pass a StatePickleStorage instance as state_storage to TeleBot class.

Parameters
filename (str, optional) – Filename of saving file, defaults to “./.state-save/states.pkl”

export_chat_invite_link(chat_id: int | str) → str

Use this method to export an invite link to a supergroup or a channel. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#exportchatinvitelink
Parameters
chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)

144 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
exported invite link as String on success.
Return type
str
forward_message(chat_id: int | str, from_chat_id: int | str, message_id: int, disable_notification: bool |
None = None, protect_content: bool | None = None, timeout: int | None = None,
message_thread_id: int | None = None) → Message
Use this method to forward messages of any kind.
Telegram documentation: https://core.telegram.org/bots/api#forwardmessage
Parameters
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_id (int) – Message identifier in the chat specified in from_chat_id
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
forward_messages(chat_id: str | int, from_chat_id: str | int, message_ids: List[int], disable_notification:
bool | None = None, message_thread_id: int | None = None, protect_content: bool |
None = None) → List[MessageID]
Use this method to forward multiple messages of any kind. If some of the specified messages can’t be found
or forwarded, they are skipped. Service messages and messages with protected content can’t be forwarded.
Album grouping is kept for forwarded messages. On success, an array of MessageId of the sent messages
is returned.
Telegram documentation: https://core.telegram.org/bots/api#forwardmessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_ids (list) – Message identifiers in the chat specified in from_chat_id
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound

1.3. Content 145

pyTelegramBotAPI, Release 4.25.0

• message_thread_id (int) – Identifier of a message thread, in which the messages will

be sent
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
Returns
On success, the sent Message is returned.
Return type
telebot.types.MessageID
get_available_gifts() → Gifts
Returns the list of gifts that can be sent by the bot to users. Requires no parameters. Returns a Gifts object.
Telegram documentation: https://core.telegram.org/bots/api#getavailablegifts
Returns
On success, a Gifts object is returned.
Return type
telebot.types.Gifts
get_business_connection(business_connection_id: str) → BusinessConnection
Use this method to get information about the connection of the bot with a business account. Returns a
BusinessConnection object on success.
Telegram documentation: https://core.telegram.org/bots/api#getbusinessconnection
Parameters
business_connection_id (str) – Unique identifier of the business connection
Returns
Returns a BusinessConnection object on success.
Return type
telebot.types.BusinessConnection
get_chat(chat_id: int | str) → ChatFullInfo
Use this method to get up to date information about the chat (current name of the user for one-on-one
conversations, current username of a user, group or channel, etc.). Returns a Chat object on success.
Telegram documentation: https://core.telegram.org/bots/api#getchat
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
Chat information
Return type
telebot.types.ChatFullInfo
get_chat_administrators(chat_id: int | str) → List[ChatMember]
Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember
objects that contains information about all chat administrators except other bots.
Telegram documentation: https://core.telegram.org/bots/api#getchatadministrators
Parameters
chat_id – Unique identifier for the target chat or username of the target supergroup or channel
(in the format @channelusername)

146 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
List made of ChatMember objects.
Return type
list of telebot.types.ChatMember
get_chat_member(chat_id: int | str, user_id: int) → ChatMember
Use this method to get information about a member of a chat. Returns a ChatMember object on success.
Telegram documentation: https://core.telegram.org/bots/api#getchatmember
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int) – Unique identifier of the target user
Returns
Returns ChatMember object on success.
Return type
telebot.types.ChatMember
get_chat_member_count(chat_id: int | str) → int
Use this method to get the number of members in a chat.
Telegram documentation: https://core.telegram.org/bots/api#getchatmembercount
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
Number of members in the chat.
Return type
int
get_chat_members_count(**kwargs)

get_chat_menu_button(chat_id: int | str = None) → MenuButton

Use this method to get the current value of the bot’s menu button in a private chat, or the default menu
button. Returns MenuButton on success.
Telegram Documentation: https://core.telegram.org/bots/api#getchatmenubutton
Parameters
chat_id (int or str) – Unique identifier for the target private chat. If not specified, default
bot’s menu button will be returned.
Returns
types.MenuButton
Return type
telebot.types.MenuButton
get_custom_emoji_stickers(custom_emoji_ids: List[str]) → List[Sticker]
Use this method to get information about custom emoji stickers by their identifiers. Returns an Array of
Sticker objects.

1.3. Content 147

pyTelegramBotAPI, Release 4.25.0

Parameters
custom_emoji_ids (list of str) – List of custom emoji identifiers. At most 200 custom
emoji identifiers can be specified.
Returns
Returns an Array of Sticker objects.
Return type
list of telebot.types.Sticker
get_file(file_id: str | None) → File
Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can
download files of up to 20MB in size. On success, a File object is returned. It is guaranteed that the link
will be valid for at least 1 hour. When the link expires, a new one can be requested by calling get_file again.
Telegram documentation: https://core.telegram.org/bots/api#getfile
Parameters
file_id (str) – File identifier
Returns
telebot.types.File
get_file_url(file_id: str | None) → str
Get a valid URL for downloading a file.
Parameters
file_id (str) – File identifier to get download URL for.
Returns
URL for downloading the file.
Return type
str
get_forum_topic_icon_stickers() → List[Sticker]
Use this method to get custom emoji stickers, which can be used as a forum topic icon by any user. Requires
no parameters. Returns an Array of Sticker objects.
Telegram documentation: https://core.telegram.org/bots/api#getforumtopiciconstickers
Returns
On success, a list of StickerSet objects is returned.
Return type
List[telebot.types.StickerSet]
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]
Use this method to get data for high score tables. Will return the score of the specified user and several of
their neighbors in a game. On success, returns an Array of GameHighScore objects.
This method will currently return scores for the target user, plus two of their closest neighbors on each side.
Will also return the top three users if the user and their neighbors are not among them. Please note that this
behavior is subject to change.
Telegram documentation: https://core.telegram.org/bots/api#getgamehighscores
Parameters
• user_id (int) – User identifier

148 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier

for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
Returns
On success, returns an Array of GameHighScore objects.
Return type
List[types.GameHighScore]
get_me() → User
A simple method for testing your bot’s authentication token. Requires no parameters. Returns basic infor-
mation about the bot in form of a User object.
Telegram documentation: https://core.telegram.org/bots/api#getme
get_my_commands(scope: BotCommandScope | None = None, language_code: str | None = None) →
List[BotCommand]
Use this method to get the current list of the bot’s commands. Returns List of BotCommand on success.
Telegram documentation: https://core.telegram.org/bots/api#getmycommands
Parameters
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands
Returns
List of BotCommand on success.
Return type
list of telebot.types.BotCommand
get_my_default_administrator_rights(for_channels: bool | None = None) →
ChatAdministratorRights
Use this method to get the current default administrator rights of the bot. Returns ChatAdministratorRights
on success.
Telegram documentation: https://core.telegram.org/bots/api#getmydefaultadministratorrights
Parameters
for_channels (bool) – Pass True to get the default administrator rights of the bot in chan-
nels. Otherwise, the default administrator rights of the bot for groups and supergroups will
be returned.
Returns
Returns ChatAdministratorRights on success.
Return type
telebot.types.ChatAdministratorRights

1.3. Content 149

pyTelegramBotAPI, Release 4.25.0

get_my_description(language_code: str | None = None)

Use this method to get the current bot description for the given user language. Returns BotDescription on
success.
Telegram documentation: https://core.telegram.org/bots/api#getmydescription
Parameters
language_code (str) – A two-letter ISO 639-1 language code or an empty string
Returns
telebot.types.BotDescription
get_my_name(language_code: str | None = None)
Use this method to get the current bot name for the given user language. Returns BotName on success.
Telegram documentation: https://core.telegram.org/bots/api#getmyname
Parameters
language_code (str) – Optional. A two-letter ISO 639-1 language code or an empty string
Returns
telebot.types.BotName
get_my_short_description(language_code: str | None = None)
Use this method to get the current bot short description for the given user language. Returns BotShortDe-
scription on success.
Telegram documentation: https://core.telegram.org/bots/api#getmyshortdescription
Parameters
language_code (str) – A two-letter ISO 639-1 language code or an empty string
Returns
telebot.types.BotShortDescription
get_star_transactions(offset: int | None = None, limit: int | None = None) → StarTransactions
Returns the bot’s Telegram Star transactions in chronological order. On success, returns a StarTransactions
object.
Telegram documentation: https://core.telegram.org/bots/api#getstartransactions
Parameters
• offset (int) – Number of transactions to skip in the response
• limit (int) – The maximum number of transactions to be retrieved. Values between 1-
100 are accepted. Defaults to 100.
Returns
On success, returns a StarTransactions object.
Return type
types.StarTransactions
get_state(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → str
Gets current state of a user. Not recommended to use this method. But it is ok for debugging.

150 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

. Warning

Even if you are using telebot.types.State, this method will return a string. When comparing(not
recommended), you should compare this string with telebot.types.State.name

Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
state of a user
Return type
int or str or telebot.types.State

get_sticker_set(name: str) → StickerSet

Use this method to get a sticker set. On success, a StickerSet object is returned.
Telegram documentation: https://core.telegram.org/bots/api#getstickerset
Parameters
name (str) – Sticker set name
Returns
On success, a StickerSet object is returned.
Return type
telebot.types.StickerSet
get_updates(offset: int | None = None, limit: int | None = None, timeout: int | None = 20, allowed_updates:
List[str] | None = None, long_polling_timeout: int = 20) → List[Update]
Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is
returned.
Telegram documentation: https://core.telegram.org/bots/api#getupdates
Parameters
• offset (int, optional) – Identifier of the first update to be returned. Must be greater
by one than the highest among the identifiers of previously received updates. By default,
updates starting with the earliest unconfirmed update are returned. An update is considered
confirmed as soon as getUpdates is called with an offset higher than its update_id. The
negative offset can be specified to retrieve updates starting from -offset update from the
end of the updates queue. All previous updates will forgotten.
• limit (int, optional) – Limits the number of updates to be retrieved. Values between
1-100 are accepted. Defaults to 100.
• timeout (int, optional) – Request connection timeout
• allowed_updates (list, optional) – Array of string. List the types of updates you want
your bot to receive.

1.3. Content 151

pyTelegramBotAPI, Release 4.25.0

• long_polling_timeout (int, optional) – Timeout in seconds for long polling.

Returns
An Array of Update objects is returned.
Return type
list of telebot.types.Update
get_user_chat_boosts(chat_id: int | str, user_id: int) → UserChatBoosts
Use this method to get the list of boosts added to a chat by a user. Requires administrator rights in the chat.
Returns a UserChatBoosts object.
Telegram documentation: https://core.telegram.org/bots/api#getuserchatboosts
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• user_id (int) – Unique identifier of the target user
Returns
On success, a UserChatBoosts object is returned.
Return type
telebot.types.UserChatBoosts
get_user_profile_photos(user_id: int, offset: int | None = None, limit: int | None = None) →
UserProfilePhotos
Use this method to get a list of profile pictures for a user. Returns a telebot.types.UserProfilePhotos
object.
Telegram documentation: https://core.telegram.org/bots/api#getuserprofilephotos
Parameters
• user_id (int) – Unique identifier of the target user
• offset (int) – Sequential number of the first photo to be returned. By default, all photos
are returned.
• limit (int) – Limits the number of photos to be retrieved. Values between 1-100 are
accepted. Defaults to 100.
Returns
UserProfilePhotos
Return type
telebot.types.UserProfilePhotos
get_webhook_info(timeout: int | None = None) → WebhookInfo
Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo
object. If the bot is using getUpdates, will return an object with the url field empty.
Telegram documentation: https://core.telegram.org/bots/api#getwebhookinfo
Parameters
timeout (int, optional) – Request connection timeout
Returns
On success, returns a WebhookInfo object.
Return type
telebot.types.WebhookInfo

152 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

hide_general_forum_topic(chat_id: int | str) → bool

Use this method to hide the ‘General’ topic in a forum supergroup chat. The bot must be an administrator in
the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#hidegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
infinity_polling(timeout: int | None = 20, skip_pending: bool | None = False, long_polling_timeout: int |
None = 20, logger_level: int | None = 40, allowed_updates: List[str] | None = None,
restart_on_change: bool | None = False, path_to_watch: str | None = None, *args,
**kwargs)
Wrap polling with infinite loop and exception handling to avoid bot stops polling.

ò Note

Install watchdog and psutil before using restart_on_change option.

Parameters
• timeout (int) – Request connection timeout.
• long_polling_timeout (int) – Timeout in seconds for long polling (see API docs)
• skip_pending (bool) – skip old updates
• logger_level (int.) – Custom (different from logger itself) logging level for infin-
ity_polling logging. Use logger levels from logging as a value. None/NOTSET = no error
logging
• allowed_updates (list of str) – A list of the update types you want your bot to re-
ceive. For example, specify [“message”, “edited_channel_post”, “callback_query”] to only
receive updates of these types. See util.update_types for a complete list of available update
types. Specify an empty list to receive all update types except chat_member (default). If not
specified, the previous setting will be used. Please note that this parameter doesn’t affect
updates created before the call to the get_updates, so unwanted updates may be received
for a short period of time.
• restart_on_change (bool) – Restart a file on file(s) change. Defaults to False
• path_to_watch (str) – Path to watch for changes. Defaults to current directory
Returns

inline_handler(func, **kwargs)
Handles new incoming inline query. As a parameter to the decorator function, it passes telebot.types.
InlineQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None

1.3. Content 153

pyTelegramBotAPI, Release 4.25.0

kick_chat_member(**kwargs)

leave_chat(chat_id: int | str) → bool

Use this method for your bot to leave a group, supergroup or channel. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#leavechat
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
bool
load_next_step_handlers(filename='./.handler-saves/step.save', del_file_after_loading=True)
Load next step handlers from save file
This function is left to keep backward compatibility whose purpose was to load handlers from file with
the help of FileHandlerBackend and is only recommended to use if next_step_backend was assigned as
FileHandlerBackend before entering this function
Parameters
• filename (str, optional) – Filename of the file where handlers was saved, defaults to
“./.handler-saves/step.save”
• del_file_after_loading (bool, optional) – If True is passed, after the loading file will
be deleted, defaults to True
load_reply_handlers(filename='./.handler-saves/reply.save', del_file_after_loading=True)
Load reply handlers from save file
This function is left to keep backward compatibility whose purpose was to load handlers from file with the
help of FileHandlerBackend and is only recommended to use if reply_backend was assigned as FileHan-
dlerBackend before entering this function
Parameters
• filename (str, optional) – Filename of the file where handlers was saved, defaults to
“./.handler-saves/reply.save”
• del_file_after_loading (bool, optional) – If True is passed, after the loading file will
be deleted, defaults to True, defaults to True
log_out() → bool
Use this method to log out from the cloud Bot API server before launching the bot locally. You MUST log
out the bot before running it locally, otherwise there is no guarantee that the bot will receive updates. After
a successful call, you can immediately log in on a local server, but will not be able to log in back to the
cloud Bot API server for 10 minutes. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#logout
Returns
True on success.
Return type
bool
message_handler(commands: List[str] | None = None, regexp: str | None = None, func: Callable | None =
None, content_types: List[str] | None = None, chat_types: List[str] | None = None,
**kwargs)

154 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Handles New incoming message of any kind - text, photo, sticker, etc. As a parameter to the decorator
function, it passes telebot.types.Message object. All message handlers are tested in the order they
were added.
Example:

Listing 7: Usage of message_handler

bot = TeleBot('TOKEN')

# Handles all messages which text matches regexp.

@bot.message_handler(regexp='someregexp')
def command_help(message):
bot.send_message(message.chat.id, 'Did someone call for help?')

# Handles messages in private chat

@bot.message_handler(chat_types=['private']) # You can add more chat types
def command_help(message):
bot.send_message(message.chat.id, 'Private chat detected, sir!')

# Handle all sent documents of type 'text/plain'.

@bot.message_handler(func=lambda message: message.document.mime_type == 'text/
˓→plain',

content_types=['document'])
def command_handle_document(message):
bot.send_message(message.chat.id, 'Document received, sir!')

# Handle all other messages.

@bot.message_handler(func=lambda message: True, content_types=['audio', 'photo',
˓→ 'voice', 'video', 'document',

'text', 'location', 'contact', 'sticker'])

def default_command(message):
bot.send_message(message.chat.id, "This is the default command handler.")

Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (lambda) – Optional lambda function. The lambda receives the message to test as
the first parameter. It must return True if the command should handle the message.
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• chat_types (list of str) – list of chat types
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function

message_reaction_count_handler(func=None, **kwargs)
Handles new incoming message reaction count. As a parameter to the decorator function, it passes
telebot.types.MessageReactionCountUpdated object.

1.3. Content 155

pyTelegramBotAPI, Release 4.25.0

Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
message_reaction_handler(func=None, **kwargs)
Handles new incoming message reaction. As a parameter to the decorator function, it passes telebot.
types.MessageReactionUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
middleware_handler(update_types: List[str] | None = None)
Function-based middleware handler decorator.
This decorator can be used to decorate functions that must be handled as middlewares before entering any
other message handlers But, be careful and check type of the update inside the handler if more than one
update_type is given
Example:

Listing 8: Usage of middleware_handler

bot = TeleBot('TOKEN')

# Print post message text before entering to any post_channel handlers

@bot.middleware_handler(update_types=['channel_post', 'edited_channel_post'])
def print_channel_post_text(bot_instance, channel_post):
print(channel_post.text)

# Print update id before entering to any handlers

@bot.middleware_handler()
def print_channel_post_text(bot_instance, update):
print(update.update_id)

Parameters
update_types (list of str) – Optional list of update types that can be passed into the
middleware handler.
Returns
function

my_chat_member_handler(func=None, **kwargs)
Handles update in a status of a bot. For private chats, this update is received only when the bot is
blocked or unblocked by the user. As a parameter to the decorator function, it passes telebot.types.
ChatMemberUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

156 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
None
pin_chat_message(chat_id: int | str, message_id: int, disable_notification: bool | None = False,
business_connection_id: str | None = None) → bool
Use this method to pin a message in a supergroup. The bot must be an administrator in the chat for this to
work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#pinchatmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Identifier of a message to pin
• disable_notification (bool) – Pass True, if it is not necessary to send a notification
to all group members about the new pinned message
• business_connection_id (str) – Unique identifier of the business connection
Returns
True on success.
Return type
bool
poll_answer_handler(func=None, **kwargs)
Handles change of user’s answer in a non-anonymous poll(when user changes the vote). Bots receive new
votes only in polls that were sent by the bot itself. As a parameter to the decorator function, it passes
telebot.types.PollAnswer object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
poll_handler(func, **kwargs)
Handles new state of a poll. Bots receive only updates about stopped polls and polls, which are sent by the
bot As a parameter to the decorator function, it passes telebot.types.Poll object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
polling(non_stop: bool | None = False, skip_pending: bool | None = False, interval: int | None = 0, timeout:
int | None = 20, long_polling_timeout: int | None = 20, logger_level: int | None = 40,
allowed_updates: List[str] | None = None, none_stop: bool | None = None, restart_on_change: bool
| None = False, path_to_watch: str | None = None)
This function creates a new Thread that calls an internal __retrieve_updates function. This allows the bot
to retrieve Updates automatically and notify listeners and message handlers accordingly.
Warning: Do not call this function more than once!

1.3. Content 157

pyTelegramBotAPI, Release 4.25.0

Always gets updates.

Deprecated since version 4.1.1: Use infinity_polling() instead.

ò Note

Install watchdog and psutil before using restart_on_change option.

Parameters
• interval (int) – Delay between two update retrivals
• non_stop (bool) – Do not stop polling when an ApiException occurs.
• timeout (int) – Request connection timeout
• skip_pending (bool) – skip old updates
• long_polling_timeout (int) – Timeout in seconds for long polling (see API docs)
• logger_level (int) – Custom (different from logger itself) logging level for infin-
ity_polling logging. Use logger levels from logging as a value. None/NOTSET = no error
logging
• allowed_updates (list of str) – A list of the update types you want your bot to re-
ceive. For example, specify [“message”, “edited_channel_post”, “callback_query”] to only
receive updates of these types. See util.update_types for a complete list of available update
types. Specify an empty list to receive all update types except chat_member (default). If
not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the
get_updates, so unwanted updates may be received for a short period of time.
• none_stop (bool) – deprecated.
• restart_on_change (bool) – Restart a file on file(s) change. Defaults to False
• path_to_watch (str) – Path to watch for changes. Defaults to None
Returns

pre_checkout_query_handler(func, **kwargs)
New incoming pre-checkout query. Contains full information about checkout. As a parameter to the deco-
rator function, it passes telebot.types.PreCheckoutQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
process_new_updates(updates: List[Update])
Processes new updates. Just pass list of subclasses of Update to this method.
Parameters
updates (list of telebot.types.Update) – List of telebot.types.Update objects.
Return None

158 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

promote_chat_member(chat_id: int | str, user_id: int, can_change_info: bool | None = None,

can_post_messages: bool | None = None, can_edit_messages: bool | None = None,
can_delete_messages: bool | None = None, can_invite_users: bool | None = None,
can_restrict_members: bool | None = None, can_pin_messages: bool | None =
None, can_promote_members: bool | None = None, is_anonymous: bool | None =
None, can_manage_chat: bool | None = None, can_manage_video_chats: bool |
None = None, can_manage_voice_chats: bool | None = None, can_manage_topics:
bool | None = None, can_post_stories: bool | None = None, can_edit_stories: bool |
None = None, can_delete_stories: bool | None = None) → bool
Use this method to promote or demote a user in a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean parameters
to demote a user.
Telegram documentation: https://core.telegram.org/bots/api#promotechatmember
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel ( in the format @channelusername)
• user_id (int) – Unique identifier of the target user
• can_change_info (bool) – Pass True, if the administrator can change chat title, photo
and other settings
• can_post_messages (bool) – Pass True, if the administrator can create channel posts,
channels only
• can_edit_messages (bool) – Pass True, if the administrator can edit messages of other
users, channels only
• can_delete_messages (bool) – Pass True, if the administrator can delete messages of
other users
• can_invite_users (bool) – Pass True, if the administrator can invite new users to the
chat
• can_restrict_members (bool) – Pass True, if the administrator can restrict, ban or un-
ban chat members
• can_pin_messages (bool) – Pass True, if the administrator can pin messages, super-
groups only
• can_promote_members (bool) – Pass True, if the administrator can add new adminis-
trators with a subset of his own privileges or demote administrators that he has promoted,
directly or indirectly (promoted by administrators that were appointed by him)
• is_anonymous (bool) – Pass True, if the administrator’s presence in the chat is hidden
• can_manage_chat (bool) – Pass True, if the administrator can access the chat event log,
chat statistics, message statistics in channels, see channel members, see anonymous ad-
ministrators in supergroups and ignore slow mode. Implied by any other administrator
privilege
• can_manage_video_chats (bool) – Pass True, if the administrator can manage voice
chats For now, bots can use this privilege only for passing to other administrators.
• can_manage_voice_chats (bool) – Deprecated, use can_manage_video_chats.
• can_manage_topics (bool) – Pass True if the user is allowed to create, rename, close,
and reopen forum topics, supergroups only
• can_post_stories (bool) – Pass True if the administrator can create the channel’s stories

1.3. Content 159

pyTelegramBotAPI, Release 4.25.0

• can_edit_stories (bool) – Pass True if the administrator can edit the channel’s stories
• can_delete_stories (bool) – Pass True if the administrator can delete the channel’s
stories
Returns
True on success.
Return type
bool
purchased_paid_media_handler(func=None, **kwargs)
Handles new incoming purchased paid media.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
refund_star_payment(user_id: int, telegram_payment_charge_id: str) → bool
Refunds a successful payment in Telegram Stars. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#refundstarpayment
Parameters
• user_id (int) – Identifier of the user whose payment will be refunded
• telegram_payment_charge_id (str) – Telegram payment identifier
Returns
On success, True is returned.
Return type
bool
register_business_connection_handler(callback: Callable, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers business connection handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_business_message_handler(callback: Callable, commands: List[str] | None = None, regexp:
str | None = None, func: Callable | None = None, content_types:
List[str] | None = None, pass_bot: bool | None = False,
**kwargs)
Registers business connection handler.
Parameters

160 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• callback (function) – function to be called

• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• pass_bot (bool) – True, if bot instance should be passed to handler
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_callback_query_handler(callback: Callable, func: Callable, pass_bot: bool | None = False,
**kwargs)
Registers callback query handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_channel_post_handler(callback: Callable, content_types: List[str] | None = None, commands:
List[str] | None = None, regexp: str | None = None, func: Callable |
None = None, pass_bot: bool | None = False, **kwargs)
Registers channel post message handler.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_boost_handler(callback: Callable, func: Callable | None = None, pass_bot: bool | None
= False, **kwargs)
Registers chat boost handler.

1.3. Content 161

pyTelegramBotAPI, Release 4.25.0

Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot – True if you need to pass TeleBot instance to handler(useful for separating
handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_join_request_handler(callback: Callable, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers chat join request handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_member_handler(callback: Callable, func: Callable | None = None, pass_bot: bool | None
= False, **kwargs)
Registers chat member handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
:return:None
register_chosen_inline_handler(callback: Callable, func: Callable, pass_bot: bool | None = False,
**kwargs)
Registers chosen inline handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None

162 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

register_deleted_business_messages_handler(callback: Callable, func: Callable | None = None,

pass_bot: bool | None = False, **kwargs)
Registers deleted business messages handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_edited_business_message_handler(callback: Callable, content_types: List[str] | None =
None, commands: List[str] | None = None, regexp: str |
None = None, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers edited message handler for business accounts.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_edited_channel_post_handler(callback: Callable, content_types: List[str] | None = None,
commands: List[str] | None = None, regexp: str | None =
None, func: Callable | None = None, pass_bot: bool | None =
False, **kwargs)
Registers edited channel post message handler.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter

1.3. Content 163

pyTelegramBotAPI, Release 4.25.0

• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_edited_message_handler(callback: Callable, content_types: List[str] | None = None,
commands: List[str] | None = None, regexp: str | None = None,
func: Callable | None = None, chat_types: List[str] | None = None,
pass_bot: bool | None = False, **kwargs)
Registers edited message handler.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• chat_types (bool) – True for private chat
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_for_reply(message: Message, callback: Callable, *args, **kwargs) → None
Registers a callback function to be notified when a reply to message arrives.
Warning: In case callback as lambda function, saving reply handlers will not work.
Parameters
• message (telebot.types.Message) – The message for which we are awaiting a reply.
• callback (Callable[[telebot.types.Message], None]) – The callback function
to be called when a reply arrives. Must accept one message parameter, which will contain
the replied message.
• args – Optional arguments for the callback function.
• kwargs – Optional keyword arguments for the callback function.
Returns
None
register_for_reply_by_message_id(message_id: int, callback: Callable, *args, **kwargs) → None
Registers a callback function to be notified when a reply to message arrives.
Warning: In case callback as lambda function, saving reply handlers will not work.
Parameters
• message_id (int) – The id of the message for which we are awaiting a reply.

164 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• callback (Callable[[telebot.types.Message], None]) – The callback function

to be called when a reply arrives. Must accept one message parameter, which will contain
the replied message.
• args – Optional arguments for the callback function.
• kwargs – Optional keyword arguments for the callback function.
Returns
None
register_inline_handler(callback: Callable, func: Callable, pass_bot: bool | None = False, **kwargs)
Registers inline handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_message_handler(callback: Callable, content_types: List[str] | None = None, commands:
List[str] | None = None, regexp: str | None = None, func: Callable | None =
None, chat_types: List[str] | None = None, pass_bot: bool | None = False,
**kwargs)
Registers message handler.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• chat_types (list of str) – List of chat types
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_message_reaction_count_handler(callback: Callable, func: Callable = None, pass_bot: bool
| None = False, **kwargs)
Registers message reaction count handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter

1.3. Content 165

pyTelegramBotAPI, Release 4.25.0

• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_message_reaction_handler(callback: Callable, func: Callable = None, pass_bot: bool | None
= False, **kwargs)
Registers message reaction handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_middleware_handler(callback, update_types=None)
Adds function-based middleware handler.
This function will register your decorator function. Function-based middlewares are executed before han-
dlers. But, be careful and check type of the update inside the handler if more than one update_type is
given
Example:
bot = TeleBot(‘TOKEN’)
bot.register_middleware_handler(print_channel_post_text, update_types=[‘channel_post’,
‘edited_channel_post’])
Parameters
• callback (function) – Function that will be used as a middleware handler.
• update_types (list of str) – Optional list of update types that can be passed into the
middleware handler.
Returns
None
register_my_chat_member_handler(callback: Callable, func: Callable | None = None, pass_bot: bool |
None = False, **kwargs)
Registers my chat member handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)

166 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
None
register_next_step_handler(message: Message, callback: Callable, *args, **kwargs) → None
Registers a callback function to be notified when new message arrives after message.
Warning: In case callback as lambda function, saving next step handlers will not work.
Parameters
• message (telebot.types.Message) – The message for which we want to handle new
message in the same chat.
• callback (Callable[[telebot.types.Message], None]) – The callback function
which next new message arrives.
• args – Args to pass in callback func
• kwargs – Args to pass in callback func
Returns
None
register_next_step_handler_by_chat_id(chat_id: int, callback: Callable, *args, **kwargs) → None
Registers a callback function to be notified when new message arrives in the given chat.
Warning: In case callback as lambda function, saving next step handlers will not work.
Parameters
• chat_id (int) – The chat (chat ID) for which we want to handle new message.
• callback (Callable[[telebot.types.Message], None]) – The callback function
which next new message arrives.
• args – Args to pass in callback func
• kwargs – Args to pass in callback func
Returns
None
register_poll_answer_handler(callback: Callable, func: Callable, pass_bot: bool | None = False,
**kwargs)
Registers poll answer handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_poll_handler(callback: Callable, func: Callable, pass_bot: bool | None = False, **kwargs)
Registers poll handler.
Parameters
• callback (function) – function to be called

1.3. Content 167

pyTelegramBotAPI, Release 4.25.0

• func (function) – Function executed as a filter

• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_pre_checkout_query_handler(callback: Callable, func: Callable, pass_bot: bool | None =
False, **kwargs)
Registers pre-checkout request handler.
Parameters
• callback (function) – function to be called
• func – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_purchased_paid_media_handler(callback: Callable, func: Callable, pass_bot: bool | None =
False, **kwargs)
Registers purchased paid media handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_removed_chat_boost_handler(callback: Callable, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers removed chat boost handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot – True if you need to pass TeleBot instance to handler(useful for separating
handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None

168 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

register_shipping_query_handler(callback: Callable, func: Callable, pass_bot: bool | None = False,

**kwargs)
Registers shipping query handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
remove_chat_verification(chat_id: int | str) → bool
Removes verification from a chat that is currently verified on behalf of the organization represented by the
bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#removechatverification
Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
Returns
Returns True on success.
Return type
bool
remove_user_verification(user_id: int) → bool
Removes verification from a user who is currently verified on behalf of the organization represented by the
bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#removeuserverification
Parameters
user_id (int) – Unique identifier of the target user
Returns
Returns True on success.
Return type
bool
remove_webhook() → bool
Deletes webhooks using set_webhook() function.
Returns
True on success.
Return type
bool
removed_chat_boost_handler(func=None, **kwargs)
Handles new incoming chat boost state. it passes telebot.types.ChatBoostRemoved object.
Parameters
• func (function) – Function executed as a filter

1.3. Content 169

pyTelegramBotAPI, Release 4.25.0

• kwargs – Optional keyword arguments(custom filters)

Returns
None
reopen_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an administrator in
the chat for this to work and must have the can_manage_topics administrator rights, unless it is the creator
of the topic. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#reopenforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to reopen
Returns
On success, True is returned.
Return type
bool
reopen_general_forum_topic(chat_id: int | str) → bool
Use this method to reopen the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#reopengeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
replace_sticker_in_set(user_id: int, name: str, old_sticker: str, sticker: InputSticker) → bool

Use this method to replace an existing sticker in a sticker set with a new one. The method is
equivalent to calling deleteStickerFromSet, then addStickerToSet,
then setStickerPositionInSet. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#replaceStickerInSet
Parameters
• user_id (int) – User identifier of the sticker set owner
• name (str) – Sticker set name
• old_sticker (str) – File identifier of the replaced sticker
• sticker (telebot.types.InputSticker) – A JSON-serialized object with informa-
tion about the added sticker. If exactly the same sticker had already been added to the set,
then the set remains unchanged.
Returns
Returns True on success.
Return type
bool
reply_to(message: Message, text: str, **kwargs) → Message
Convenience function for send_message(message.chat.id, text, re-
ply_parameters=(message.message_id. . . ), **kwargs)

170 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Parameters
• message (types.Message) – Instance of telebot.types.Message
• text (str) – Text of the message.
• kwargs – Additional keyword arguments which are passed to telebot.TeleBot.
send_message()
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
reset_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → bool
Reset data for a user in chat: sets the ‘data’ field to an empty dictionary.
Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
True on success
Return type
bool
restrict_chat_member(chat_id: int | str, user_id: int, until_date: int | datetime | None = None,
can_send_messages: bool | None = None, can_send_media_messages: bool | None
= None, can_send_polls: bool | None = None, can_send_other_messages: bool |
None = None, can_add_web_page_previews: bool | None = None,
can_change_info: bool | None = None, can_invite_users: bool | None = None,
can_pin_messages: bool | None = None, permissions: ChatPermissions | None =
None, use_independent_chat_permissions: bool | None = None) → bool
Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup
for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift
restrictions from a user.
Telegram documentation: https://core.telegram.org/bots/api#restrictchatmember

. Warning

Individual parameters are deprecated and will be removed, use ‘permissions’ instead.

Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @channelusername)
• user_id (int) – Unique identifier of the target user

1.3. Content 171

pyTelegramBotAPI, Release 4.25.0

• until_date (int or datetime, optional) – Date when restrictions will be lifted for the
user, unix time. If user is restricted for more than 366 days or less than 30 seconds from
the current time, they are considered to be restricted forever
• can_send_messages (bool) – deprecated
• can_send_media_messages (bool) – deprecated
• can_send_polls (bool) – deprecated
• can_send_other_messages (bool) – deprecated
• can_add_web_page_previews (bool) – deprecated
• can_change_info (bool) – deprecated
• can_invite_users (bool) – deprecated
• can_pin_messages (bool) – deprecated
• use_independent_chat_permissions (bool, optional) – Pass True if chat per-
missions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos, can_send_videos,
can_send_video_notes, and can_send_voice_notes permissions; the can_send_polls
permission will imply the can_send_messages permission.
• permissions (telebot.types.ChatPermissions) – ChatPermissions object defining
permissions.
Returns
True on success
Return type
bool

retrieve_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → Dict[str, Any] | None
Returns context manager with data for a user in chat.
Parameters
• user_id (int) – User identifier
• chat_id (int, optional) – Chat’s unique identifier, defaults to user_id
• bot_id (int, optional) – Bot’s identifier, defaults to current bot id
• business_connection_id (str, optional) – Business identifier
• message_thread_id (int, optional) – Identifier of the message thread
Returns
Context manager with data for a user in chat
Return type
Optional[Any]
revoke_chat_invite_link(chat_id: int | str, invite_link: str) → ChatInviteLink
Use this method to revoke an invite link created by the bot. Note: If the primary link is revoked, a new link
is automatically generated The bot must be an administrator in the chat for this to work and must have the
appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#revokechatinvitelink

172 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Parameters
• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• invite_link (str) – The invite link to revoke
Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
run_webhooks(listen: str | None = '127.0.0.1', port: int | None = 443, url_path: str | None = None,
certificate: str | None = None, certificate_key: str | None = None, webhook_url: str | None =
None, max_connections: int | None = None, allowed_updates: List | None = None,
ip_address: str | None = None, drop_pending_updates: bool | None = None, timeout: int |
None = None, secret_token: str | None = None, secret_token_length: int | None = 20)
This class sets webhooks and listens to a given url and port.
Requires fastapi, uvicorn, and latest version of starlette.
Parameters
• listen (str, optional) – IP address to listen to, defaults to “127.0.0.1”
• port (int, optional) – A port which will be used to listen to webhooks., defaults to 443
• url_path (str, optional) – Path to the webhook. Defaults to /token, defaults to None
• certificate (str, optional) – Path to the certificate file, defaults to None
• certificate_key (str, optional) – Path to the certificate key file, defaults to None
• webhook_url (str, optional) – Webhook URL to be set, defaults to None
• max_connections (int, optional) – Maximum allowed number of simultaneous HTTPS
connections to the webhook for update delivery, 1-100. Defaults to 40. Use lower values
to limit the load on your bot’s server, and higher values to increase your bot’s throughput.,
defaults to None
• allowed_updates (list, optional) – A JSON-serialized list of the update types you
want your bot to receive. For example, specify [“message”, “edited_channel_post”, “call-
back_query”] to only receive updates of these types. See Update for a complete list of
available update types. Specify an empty list to receive all updates regardless of type (de-
fault). If not specified, the previous setting will be used. defaults to None
• ip_address (str, optional) – The fixed IP address which will be used to send webhook
requests instead of the IP address resolved through DNS, defaults to None
• drop_pending_updates (bool, optional) – Pass True to drop all pending updates, de-
faults to None
• timeout (int, optional) – Request connection timeout, defaults to None
• secret_token (str, optional) – Secret token to be used to verify the webhook request,
defaults to None
• secret_token_length (int, optional) – Length of a secret token, defaults to 20
Raises
ImportError – If necessary libraries were not installed.

1.3. Content 173

pyTelegramBotAPI, Release 4.25.0

save_prepared_inline_message(user_id: int, result: InlineQueryResultBase, 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
Use this method to store a message that can be sent by a user of a Mini App. Returns a PreparedInlineMes-
sage object.
Telegram Documentation: https://core.telegram.org/bots/api#savepreparedinlinemessage
Parameters
• user_id (int) – Unique identifier of the target user that can use the prepared message
• result (telebot.types.InlineQueryResultBase) – A JSON-serialized object de-
scribing the message to be sent
• allow_user_chats (bool) – Pass True if the message can be sent to private chats with
users
• allow_bot_chats (bool) – Pass True if the message can be sent to private chats with
bots
• allow_group_chats (bool) – Pass True if the message can be sent to group and super-
group chats
• allow_channel_chats (bool) – Pass True if the message can be sent to channel chats
Returns
On success, a PreparedInlineMessage object is returned.
Return type
telebot.types.PreparedInlineMessage
send_animation(chat_id: int | str, animation: Any | str, duration: int | None = None, width: int | None =
None, height: int | None = None, thumbnail: str | Any | None = None, caption: str | None =
None, parse_mode: str | None = None, caption_entities: List[MessageEntity] | None =
None, disable_notification: bool | None = None, protect_content: bool | None = None,
reply_to_message_id: int | None = None, allow_sending_without_reply: bool | None =
None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None = None,
message_thread_id: int | None = None, has_spoiler: bool | None = None, thumb: str | Any |
None = None, reply_parameters: ReplyParameters | None = None, business_connection_id:
str | None = None, message_effect_id: str | None = None, show_caption_above_media:
bool | None = None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). On success,
the sent Message is returned. Bots can currently send animation files of up to 50 MB in size, this limit may
be changed in the future.
Telegram documentation: https://core.telegram.org/bots/api#sendanimation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• animation (str or telebot.types.InputFile) – Animation to send. Pass a file_id as
String to send an animation that exists on the Telegram servers (recommended), pass an
HTTP URL as a String for Telegram to get an animation from the Internet, or upload a new
animation using multipart/form-data.
• duration (int) – Duration of sent animation in seconds

174 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• width (int) – Animation width

• height (int) – Animation height
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.
• caption (str) – Animation caption (may also be used when resending animation by
file_id), 0-1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the animation caption
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• message_thread_id (int) – Identifier of a message thread, in which the video will be
sent
• has_spoiler (bool) – Pass True, if the animation should be sent as a spoiler
• thumb (str or telebot.types.InputFile) – deprecated.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

1.3. Content 175

pyTelegramBotAPI, Release 4.25.0

send_audio(chat_id: int | str, audio: Any | str, caption: str | None = None, duration: int | None = None,
performer: str | None = None, title: str | None = None, reply_to_message_id: int | None = None,
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, parse_mode: str | None = None, disable_notification: bool | None =
None, timeout: int | None = None, thumbnail: str | Any | None = None, caption_entities:
List[MessageEntity] | None = None, allow_sending_without_reply: bool | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None, thumb: str | Any |
None = None, reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None =
None) → Message
Use this method to send audio files, if you want Telegram clients to display them in the music player. Your
audio must be in the .MP3 or .M4A format. On success, the sent Message is returned. Bots can currently
send audio files of up to 50 MB in size, this limit may be changed in the future.
For sending voice messages, use the send_voice method instead.
Telegram documentation: https://core.telegram.org/bots/api#sendaudio
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• audio (str or telebot.types.InputFile) – Audio file to send. Pass a file_id as String
to send an audio file that exists on the Telegram servers (recommended), pass an HTTP
URL as a String for Telegram to get an audio file from the Internet, or upload a new one
using multipart/form-data. Audio must be in the .MP3 or .M4A format.
• caption (str) – Audio caption, 0-1024 characters after entities parsing
• duration (int) – Duration of the audio in seconds
• performer (str) – Performer
• title (str) – Track name
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply)
• parse_mode (str) – Mode for parsing entities in the audio caption. See formatting options
for more details.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>

176 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized

list of special entities that appear in the caption, which can be specified instead of
parse_mode
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• thumb (str or telebot.types.InputFile) – deprecated.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_chat_action(chat_id: int | str, action: str, timeout: int | None = None, message_thread_id: int | None
= None, business_connection_id: str | None = None) → bool
Use this method when you need to tell the user that something is happening on the bot’s side. The status is
set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).
Returns True on success.
Example: The ImageBot needs some time to process a request and upload the image. Instead of sending a
text message along the lines of “Retrieving image, please wait. . . ”, the bot may use sendChatAction with
action = upload_photo. The user will see a “sending photo” status for the bot.
Telegram documentation: https://core.telegram.org/bots/api#sendchataction
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• action (str) – Type of action to broadcast. Choose one, depending on what the user is
about to receive: typing for text messages, upload_photo for photos, record_video or up-
load_video for videos, record_voice or upload_voice for voice notes, upload_document for
general files, choose_sticker for stickers, find_location for location data, record_video_note
or upload_video_note for video notes.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – The thread identifier of a message from which the reply will
be sent(supergroups only)
• business_connection_id (str) – Identifier of a business connection
Returns
Returns True on success.

1.3. Content 177

pyTelegramBotAPI, Release 4.25.0

Return type
bool
send_contact(chat_id: int | str, phone_number: str, first_name: str, last_name: str | None = None, vcard:
str | None = None, disable_notification: bool | None = None, reply_to_message_id: int | None
= None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send phone contacts. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendcontact
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• phone_number (str) – Contact’s phone number
• first_name (str) – Contact’s first name
• last_name (str) – Contact’s last name
• vcard (str) – Additional data about the contact in the form of a vCard, 0-2048 bytes
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The thread identifier of a message from which the reply will
be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.

178 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.Message
send_dice(chat_id: int | str, emoji: str | None = None, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None
= None, allow_sending_without_reply: bool | None = None, protect_content: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send an animated emoji that will display a random value. On success, the sent Message
is returned.
Telegram documentation: https://core.telegram.org/bots/api#senddice
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• emoji (str) – Emoji on which the dice throw animation is based. Currently, must be one
of “”, “”, “”, “”, “”, or “”. Dice can have values 1-6 for “”, “” and “”, values 1-5 for “” and
“”, and values 1-64 for “”. Defaults to “”
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Additional parameters for
replies to messages
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

1.3. Content 179

pyTelegramBotAPI, Release 4.25.0

send_document(chat_id: int | str, document: Any | str, reply_to_message_id: int | None = None, caption: str
| None = None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, parse_mode: str | None = None,
disable_notification: bool | None = None, timeout: int | None = None, thumbnail: str | Any |
None = None, caption_entities: List[MessageEntity] | None = None,
allow_sending_without_reply: bool | None = None, visible_file_name: str | None = None,
disable_content_type_detection: bool | None = None, data: str | Any | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None, thumb: str |
Any | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send general files.
Telegram documentation: https://core.telegram.org/bots/api#senddocument
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• document (str or telebot.types.InputFile) – (document) File to send. Pass a file_id
as String to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL as a String for Telegram to get a file from the Internet, or upload a new one using
multipart/form-data
• caption (str) – Document caption (may also be used when resending documents by
file_id), 0-1024 characters after entities parsing
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• parse_mode (str) – Mode for parsing entities in the document caption
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – InputFile or String : Thumbnail of
the file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail’s width
and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-
data. Thumbnails can’t be reused and can be only uploaded as a new file, so you can
pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-
data under <file_attach_name>
• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• visible_file_name (str) – allows to define file name that will be visible in the Telegram
instead of original file name

180 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• disable_content_type_detection (bool) – Disables automatic server-side content

type detection for files uploaded using multipart/form-data
• data (str) – function typo miss compatibility: do not use it
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The thread to which the message will be sent
• thumb (str or telebot.types.InputFile) – deprecated.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_game(chat_id: int | str, game_short_name: str, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None
= None, allow_sending_without_reply: bool | None = None, protect_content: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Used to send the game.
Telegram documentation: https://core.telegram.org/bots/api#sendgame
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• game_short_name (str) – Short name of the game, serves as the unique identifier for the
game. Set up your games via @BotFather.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated. If the message is a reply, ID of the original
message
• allow_sending_without_reply (bool) – deprecated. Pass True, if the message should
be sent even if the specified replied-to message is not found
• reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or
ReplyKeyboardRemove or ForceReply) – Additional interface options. A JSON-
serialized object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• timeout (int) – Timeout in seconds for waiting for a response from the bot.

1.3. Content 181

pyTelegramBotAPI, Release 4.25.0

• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The identifier of a message thread, in which the game mes-
sage will be sent.
• reply_parameters (ReplyParameters) – Reply parameters
• business_connection_id (str) – Unique identifier of the business connection
• message_effect_id (str) – Unique identifier of the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message
send_gift(user_id: int, gift_id: str, text: str | None = None, text_parse_mode: str | None = None,
text_entities: List[MessageEntity] | None = None, pay_for_upgrade: bool | None = None) → bool
Sends a gift to the given user. The gift can’t be converted to Telegram Stars by the user. Returns True on
success.
Telegram documentation: https://core.telegram.org/bots/api#sendgift
Parameters
• user_id (int) – Unique identifier of the target user that will receive the gift
• gift_id (str) – Identifier of the gift
• pay_for_upgrade (bool) – Pass True to pay for the gift upgrade from the bot’s balance,
thereby making the upgrade free for the receiver
• text (str) – Text that will be shown along with the gift; 0-255 characters
• text_parse_mode (str) – Mode for parsing entities in the text. See formatting options for
more details. Entities other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”,
and “custom_emoji” are ignored.
• text_entities (list of types.MessageEntity) – A JSON-serialized list of special
entities that appear in the gift text. It can be specified instead of text_parse_mode. Entities
other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”, and “custom_emoji”
are ignored.
Returns
Returns True on success.
Return type
bool

182 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

send_invoice(chat_id: int | str, title: str, description: str, invoice_payload: str, provider_token: str | None,
currency: str, prices: List[LabeledPrice], start_parameter: 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, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, provider_data:
str | None = None, timeout: int | None = None, allow_sending_without_reply: bool | None =
None, max_tip_amount: int | None = None, suggested_tip_amounts: List[int] | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Sends invoice.
Telegram documentation: https://core.telegram.org/bots/api#sendinvoice
Parameters
• chat_id (int or str) – Unique identifier for the target private chat
• title (str) – Product name, 1-32 characters
• description (str) – Product description, 1-255 characters
• invoice_payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be
displayed to the user, use for your internal processes.
• provider_token (str) – Payments provider token, obtained via @Botfather; Pass None
to omit the parameter to use “XTR” currency
• currency (str) – Three-letter ISO 4217 currency code, see https://core.telegram.org/
bots/payments#supported-currencies
• prices (List[types.LabeledPrice]) – Price breakdown, a list of components (e.g. prod-
uct price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• start_parameter (str) – Unique deep-linking parameter that can be used to generate
this invoice when used as a start parameter
• photo_url (str) – URL of the product photo for the invoice. Can be a photo of the goods
or a marketing image for a service. People like it better when they see what they are paying
for.
• photo_size (int) – Photo size in bytes
• photo_width (int) – Photo width
• photo_height (int) – Photo height
• need_name (bool) – Pass True, if you require the user’s full name to complete the order
• need_phone_number (bool) – Pass True, if you require the user’s phone number to com-
plete the order
• need_email (bool) – Pass True, if you require the user’s email to complete the order
• need_shipping_address (bool) – Pass True, if you require the user’s shipping address
to complete the order
• is_flexible (bool) – Pass True, if the final price depends on the shipping method

1.3. Content 183

pyTelegramBotAPI, Release 4.25.0

• send_phone_number_to_provider (bool) – Pass True, if user’s phone number should

be sent to provider
• send_email_to_provider (bool) – Pass True, if user’s email address should be sent to
provider
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated. If the message is a reply, ID of the original
message
• allow_sending_without_reply (bool) – deprecated. Pass True, if the message should
be sent even if the specified replied-to message is not found
• reply_markup (str) – A JSON-serialized object for an inline keyboard. If empty, one
‘Pay total price’ button will be shown. If not empty, the first button must be a Pay button
• provider_data (str) – A JSON-serialized data about the invoice, which will be shared
with the payment provider. A detailed description of required fields should be provided by
the payment provider.
• timeout (int) – Timeout of a request, defaults to None
• max_tip_amount (int) – The maximum accepted amount for tips in the smallest units of
the currency
• suggested_tip_amounts (list of int) – A JSON-serialized array of suggested
amounts of tips in the smallest units of the currency. At most 4 suggested tip amounts
can be specified. The suggested tip amounts must be positive, passed in a strictly increased
order and must not exceed max_tip_amount.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The identifier of a message thread, in which the invoice
message will be sent
• reply_parameters (types.ReplyParameters) – Required if the message is a reply.
Additional interface options.
• message_effect_id (str) – The identifier of a message effect, which will be applied to
the sent message
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message
send_location(chat_id: int | str, latitude: float, longitude: float, live_period: int | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
disable_notification: bool | None = None, timeout: int | None = None, horizontal_accuracy:
float | None = None, heading: int | None = None, proximity_alert_radius: int | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message

184 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Use this method to send point on the map. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendlocation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• latitude (float) – Latitude of the location
• longitude (float) – Longitude of the location
• live_period (int) – Period in seconds during which the location will be updated (see
Live Locations, should be between 60 and 86400, or 0x7FFFFFFF for live locations that
can be edited indefinitely.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• horizontal_accuracy (float) – The radius of uncertainty for the location, measured
in meters; 0-1500
• heading (int) – For live locations, a direction in which the user is moving, in degrees.
Must be between 1 and 360 if specified.
• proximity_alert_radius (int) – For live locations, a maximum distance for proximity
alerts about approaching another chat member, in meters. Must be between 1 and 100000
if specified.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.

1.3. Content 185

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.Message
send_media_group(chat_id: int | str, media: List[InputMediaAudio | InputMediaDocument |
InputMediaPhoto | InputMediaVideo], disable_notification: bool | None = None,
protect_content: bool | None = None, reply_to_message_id: int | None = None, timeout:
int | None = None, allow_sending_without_reply: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None =
None, business_connection_id: str | None = None, message_effect_id: str | None =
None, allow_paid_broadcast: bool | None = None) → List[Message]
Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio
files can be only grouped in an album with messages of the same type. On success, an array of Messages
that were sent is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendmediagroup
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• media (list of types.InputMedia) – A JSON-serialized array describing messages to
be sent, must include 2-10 items
• disable_notification (bool) – Sends the messages silently. Users will receive a no-
tification with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the media group
will be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, an array of Messages that were sent is returned.
Return type
List[types.Message]

186 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

send_message(chat_id: int | str, text: str, parse_mode: str | None = None, entities: List[MessageEntity] |
None = None, disable_web_page_preview: bool | None = None, disable_notification: bool |
None = None, protect_content: bool | None = None, reply_to_message_id: int | None = None,
allow_sending_without_reply: bool | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout: int |
None = None, message_thread_id: int | None = None, reply_parameters: ReplyParameters |
None = None, link_preview_options: LinkPreviewOptions | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send text messages.
Warning: Do not send more than about 4096 characters each message, otherwise you’ll risk an HTTP 414
error. If you must send more than 4096 characters, use the split_string or smart_split function in util.py.
Telegram documentation: https://core.telegram.org/bots/api#sendmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• text (str) – Text of the message to be sent
• parse_mode (str) – Mode for parsing entities in the message text.
• entities (Array of telebot.types.MessageEntity) – List of special entities that ap-
pear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (bool) – deprecated.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• link_preview_options (telebot.types.LinkPreviewOptions) – Link preview op-
tions.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only

1.3. Content 187

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_paid_media(chat_id: int | str, star_count: int, media: List[InputPaidMedia], caption: str | None =
None, parse_mode: str | None = None, caption_entities: List[MessageEntity] | None =
None, show_caption_above_media: bool | None = None, disable_notification: bool | None
= None, protect_content: bool | None = None, reply_parameters: ReplyParameters | None
= None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, business_connection_id: str | None
= None, payload: str | None = None, allow_paid_broadcast: bool | None = None) →
Message
Use this method to send paid media to channel chats. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendpaidmedia
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• star_count (int) – The number of Telegram Stars that must be paid to buy access to the
media
• media (list of telebot.types.InputPaidMedia) – A JSON-serialized array describ-
ing the media to be sent; up to 10 items
• caption (str) – Media caption, 0-1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the media caption
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_parameters (telebot.types.ReplyParameters) – Description of the mes-
sage to reply to
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to
force a reply from the user
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• payload (str) – Bot-defined paid media payload, 0-128 bytes. This will not be displayed
to the user, use it for your internal processes.

188 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_photo(chat_id: int | str, photo: Any | str, caption: str | None = None, parse_mode: str | None = None,
caption_entities: List[MessageEntity] | None = None, disable_notification: bool | None = None,
protect_content: bool | None = None, reply_to_message_id: int | None = None,
allow_sending_without_reply: bool | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout: int |
None = None, message_thread_id: int | None = None, has_spoiler: bool | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, show_caption_above_media: bool | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send photos. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendphoto
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• photo (str or telebot.types.InputFile) – Photo to send. Pass a file_id as String
to send a photo that exists on the Telegram servers (recommended), pass an HTTP URL
as a String for Telegram to get a photo from the Internet, or upload a new photo using
multipart/form-data. The photo must be at most 10 MB in size. The photo’s width and
height must not exceed 10000 in total. Width and height ratio must be at most 20.
• caption (str) – Photo caption (may also be used when resending photos by file_id), 0-
1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the photo caption.
• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.

1.3. Content 189

pyTelegramBotAPI, Release 4.25.0

• message_thread_id (int) – Identifier of a message thread, in which the message will be

sent
• has_spoiler (bool) – Pass True, if the photo should be sent as a spoiler
• reply_parameters (telebot.types.ReplyParameters) – Additional parameters for
replies to messages
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_poll(chat_id: int | str, question: str, options: List[InputPollOption], is_anonymous: bool | None =
None, type: str | None = None, allows_multiple_answers: bool | None = None, correct_option_id:
int | None = None, explanation: str | None = None, explanation_parse_mode: str | None = None,
open_period: int | None = None, close_date: int | datetime | None = None, is_closed: bool | None
= None, disable_notification: bool | None = False, reply_to_message_id: int | None = None,
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, allow_sending_without_reply: bool | None = None, timeout: int |
None = None, explanation_entities: List[MessageEntity] | None = None, protect_content: bool |
None = None, message_thread_id: int | None = None, reply_parameters: ReplyParameters | None
= None, business_connection_id: str | None = None, question_parse_mode: str | None = None,
question_entities: List[MessageEntity] | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send a native poll. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendpoll
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• question (str) – Poll question, 1-300 characters
• options (list of InputPollOption) – A JSON-serialized list of 2-10 answer options
• is_anonymous (bool) – True, if the poll needs to be anonymous, defaults to True
• type (str) – Poll type, “quiz” or “regular”, defaults to “regular”
• allows_multiple_answers (bool) – True, if the poll allows multiple answers, ignored
for polls in quiz mode, defaults to False
• correct_option_id (int) – 0-based identifier of the correct answer option. Available
only for polls in quiz mode, defaults to None

190 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• explanation (str) – Text that is shown when a user chooses an incorrect answer or taps
on the lamp icon in a quiz-style poll, 0-200 characters with at most 2 line feeds after entities
parsing
• explanation_parse_mode (str) – Mode for parsing entities in the explanation. See
formatting options for more details.
• open_period (int) – Amount of time in seconds the poll will be active after creation,
5-600. Can’t be used together with close_date.
• close_date (int | datetime) – Point in time (Unix timestamp) when the poll will be
automatically closed.
• is_closed (bool) – Pass True, if the poll needs to be immediately closed. This can be
useful for poll preview.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated. If the message is a reply, ID of the original
message
• allow_sending_without_reply (bool) – deprecated. Pass True, if the message should
be sent even if the specified replied-to message is not found
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply) – Additional interface options. A JSON-
serialized object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• timeout (int) – Timeout in seconds for waiting for a response from the user.
• explanation_entities (list of MessageEntity) – A JSON-serialized list of special
entities that appear in the explanation, which can be specified instead of parse_mode
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The identifier of a message thread, in which the poll will be
sent
• reply_parameters (ReplyParameters) – reply parameters.
• business_connection_id (str) – Identifier of the business connection to use for the
poll
• question_parse_mode (str) – Mode for parsing entities in the question. See formatting
options for more details. Currently, only custom emoji entities are allowed
• question_entities (list of MessageEntity) – A JSON-serialized list of special en-
tities that appear in the poll question. It can be specified instead of question_parse_mode
• message_effect_id (str) – Unique identifier of the message effect to apply to the sent
message
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message

1.3. Content 191

pyTelegramBotAPI, Release 4.25.0

send_sticker(chat_id: int | str, sticker: Any | str, reply_to_message_id: int | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply |
None = None, disable_notification: bool | None = None, timeout: int | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None = None,
data: Any | str = None, message_thread_id: int | None = None, emoji: str | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None =
None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None) →
Message
Use this method to send static .WEBP, animated .TGS, or video .WEBM stickers. On success, the sent
Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendsticker
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sticker (str or telebot.types.InputFile) – Sticker to send. Pass a file_id as String
to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as
a String for Telegram to get a .webp file from the Internet, or upload a new one using
multipart/form-data.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – to disable the notification
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• data (str) – function typo miss compatibility: do not use it
• message_thread_id (int) – The thread to which the message will be sent
• emoji (str) – Emoji associated with the sticker; only for just uploaded stickers
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

192 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

send_venue(chat_id: int | str, latitude: float | None, longitude: float | None, title: str, address: str,
foursquare_id: str | None = None, foursquare_type: str | None = None, disable_notification:
bool | None = None, reply_to_message_id: int | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None
= None, timeout: int | None = None, allow_sending_without_reply: bool | None = None,
google_place_id: str | None = None, google_place_type: str | None = None, protect_content:
bool | None = None, message_thread_id: int | None = None, reply_parameters:
ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send information about a venue. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendvenue
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• latitude (float) – Latitude of the venue
• longitude (float) – Longitude of the venue
• title (str) – Name of the venue
• address (str) – Address of the venue
• foursquare_id (str) – Foursquare identifier of the venue
• foursquare_type (str) – Foursquare type of the venue, if known. (For example,
“arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• google_place_id (str) – Google Places identifier of the venue
• google_place_type (str) – Google Places type of the venue.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The thread identifier of a message from which the reply will
be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only

1.3. Content 193

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_video(chat_id: int | str, video: Any | str, duration: int | None = None, width: int | None = None, height:
int | None = None, thumbnail: str | Any | None = None, caption: str | None = None, parse_mode:
str | None = None, caption_entities: List[MessageEntity] | None = None, supports_streaming:
bool | None = None, disable_notification: bool | None = None, protect_content: bool | None =
None, reply_to_message_id: int | None = None, allow_sending_without_reply: bool | None =
None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove
| ForceReply | None = None, timeout: int | None = None, data: str | Any | None = None,
message_thread_id: int | None = None, has_spoiler: bool | None = None, thumb: str | Any |
None = None, reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, show_caption_above_media: bool | None
= None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as
Document).
Telegram documentation: https://core.telegram.org/bots/api#sendvideo
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• video (str or telebot.types.InputFile) – Video to send. You can either pass a
file_id as String to resend a video that is already on the Telegram servers, or upload a new
video file using multipart/form-data.
• duration (int) – Duration of sent video in seconds
• width (int) – Video width
• height (int) – Video height
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.
• caption (str) – Video caption (may also be used when resending videos by file_id), 0-
1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the video caption
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• supports_streaming (bool) – Pass True, if the uploaded video is suitable for streaming
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.

194 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• data (str) – function typo miss compatibility: do not use it
• message_thread_id (int) – Identifier of a message thread, in which the video will be
sent
• has_spoiler (bool) – Pass True, if the video should be sent as a spoiler
• thumb (str or telebot.types.InputFile) – deprecated.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters
• business_connection_id (str) – Identifier of a business connection
• message_effect_id (str) – Identifier of a message effect
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
send_video_note(chat_id: int | str, data: Any | str, duration: int | None = None, length: int | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
disable_notification: bool | None = None, timeout: int | None = None, thumbnail: str |
Any | None = None, allow_sending_without_reply: bool | None = None, protect_content:
bool | None = None, message_thread_id: int | None = None, thumb: str | Any | None =
None, reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None
= None) → Message
As of v.4.0, Telegram clients support rounded square MPEG4 videos of up to 1 minute long. Use this
method to send video messages. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendvideonote
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)

1.3. Content 195

pyTelegramBotAPI, Release 4.25.0

• data (str or telebot.types.InputFile) – Video note to send. Pass a file_id as String

to send a video note that exists on the Telegram servers (recommended) or upload a new
video using multipart/form-data. Sending video notes by a URL is currently unsupported
• duration (int) – Duration of sent video in seconds
• length (int) – Video width and height, i.e. diameter of the video message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the video note will
be sent
• thumb (str or telebot.types.InputFile) – deprecated.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect to be added to the
message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

196 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

send_voice(chat_id: int | str, voice: Any | str, caption: str | None = None, duration: int | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, parse_mode: str |
None = None, disable_notification: bool | None = None, timeout: int | None = None,
caption_entities: List[MessageEntity] | None = None, allow_sending_without_reply: bool |
None = None, protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice
message. For this to work, your audio must be in an .OGG file encoded with OPUS, or in .MP3 format,
or in .M4A format (other formats may be sent as Audio or Document). On success, the sent Message is
returned. Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the
future.
Telegram documentation: https://core.telegram.org/bots/api#sendvoice
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• voice (str or telebot.types.InputFile) – Audio file to send. Pass a file_id as String
to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a
String for Telegram to get a file from the Internet, or upload a new one using multipart/form-
data.
• caption (str) – Voice message caption, 0-1024 characters after entities parsing
• duration (int) – Duration of the voice message in seconds
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• parse_mode (str) – Mode for parsing entities in the voice message caption. See format-
ting options for more details.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – deprecated.
• allow_sending_without_reply (bool) – deprecated.
• timeout (int) – Timeout in seconds for the request.
• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent

1.3. Content 197

pyTelegramBotAPI, Release 4.25.0

• message_effect_id (str) – Unique identifier of the message effect to be added to the

message; for private chats only
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
set_chat_administrator_custom_title(chat_id: int | str, user_id: int, custom_title: str) → bool
Use this method to set a custom title for an administrator in a supergroup promoted by the bot. Returns
True on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatadministratorcustomtitle
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int) – Unique identifier of the target user
• custom_title (str) – New custom title for the administrator; 0-16 characters, emoji are
not allowed
Returns
True on success.
Return type
bool
set_chat_description(chat_id: int | str, description: str | None = None) → bool
Use this method to change the description of a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#setchatdescription
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• description (str) – Str: New chat description, 0-255 characters
Returns
True on success.
Return type
bool
set_chat_menu_button(chat_id: int | str = None, menu_button: MenuButton = None) → bool
Use this method to change the bot’s menu button in a private chat, or the default menu button. Returns True
on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatmenubutton
Parameters
• chat_id (int or str) – Unique identifier for the target private chat. If not specified,
default bot’s menu button will be changed.
• menu_button (telebot.types.MenuButton) – A JSON-serialized object for the new
bot’s menu button. Defaults to MenuButtonDefault

198 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
True on success.
Return type
bool
set_chat_permissions(chat_id: int | str, permissions: ChatPermissions,
use_independent_chat_permissions: bool | None = None) → bool
Use this method to set default chat permissions for all members. The bot must be an administrator in the
group or a supergroup for this to work and must have the can_restrict_members admin rights.
Telegram documentation: https://core.telegram.org/bots/api#setchatpermissions
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• permissions (telebot.types..ChatPermissions) – New default chat permissions
• use_independent_chat_permissions (bool) – Pass True if chat permis-
sions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos, can_send_videos,
can_send_video_notes, and can_send_voice_notes permissions; the can_send_polls
permission will imply the can_send_messages permission.
Returns
True on success
Return type
bool
set_chat_photo(chat_id: int | str, photo: Any) → bool
Use this method to set a new profile photo for the chat. Photos can’t be changed for private chats. The bot
must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns
True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members
Are Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#setchatphoto
Parameters
• chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
• photo (typing.Union[file_like, str]) – InputFile: New chat photo, uploaded using
multipart/form-data
Returns
True on success.
Return type
bool
set_chat_sticker_set(chat_id: int | str, sticker_set_name: str) → StickerSet
Use this method to 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 appropriate administrator rights. Use the field can_set_sticker_set
optionally returned in getChat requests to check if the bot can use this method. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatstickerset
Parameters

1.3. Content 199

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• sticker_set_name (str) – Name of the sticker set to be set as the group sticker set
Returns
StickerSet object
Return type
telebot.types.StickerSet
set_chat_title(chat_id: int | str, title: str) → bool
Use this method to change the title of a chat. Titles can’t be changed for private chats. The bot must be
an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on
success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are
Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#setchattitle
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• title (str) – New chat title, 1-255 characters
Returns
True on success.
Return type
bool
set_custom_emoji_sticker_set_thumbnail(name: str, custom_emoji_id: str | None = None) → bool
Use this method to set the thumbnail of a custom emoji sticker set. Returns True on success.
Parameters
• name (str) – Sticker set name
• custom_emoji_id (str) – Custom emoji identifier of a sticker from the sticker set; pass
an empty string to drop the thumbnail and use the first sticker as the thumbnail.
Returns
Returns True on success.
Return type
bool
set_game_score(user_id: int | str, score: int, force: bool | None = None, chat_id: int | str | None = None,
message_id: int | None = None, inline_message_id: str | None = None,
disable_edit_message: bool | None = None) → Message | bool
Sets the value of points in the game to a specific user.
Telegram documentation: https://core.telegram.org/bots/api#setgamescore
Parameters
• user_id (int or str) – User identifier
• score (int) – New score, must be non-negative
• force (bool) – Pass True, if the high score is allowed to decrease. This can be useful
when fixing mistakes or banning cheaters

200 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier

for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• disable_edit_message (bool) – Pass True, if the game message should not be automat-
ically edited to include the current scoreboard
Returns
On success, if the message was sent by the bot, returns the edited Message, otherwise returns
True.
Return type
types.Message or bool
set_message_reaction(chat_id: int | str, message_id: int, reaction: List[ReactionType] | None = None,
is_big: bool | None = None) → bool
Use this method to change the chosen reactions on a message. Service messages can’t be reacted to. Auto-
matically forwarded messages from a channel to its discussion group have the same available reactions as
messages in the channel. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmessagereaction
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup or channel (in the format @channelusername)
• message_id (int) – Identifier of the message to set reaction to
• reaction (list of telebot.types.ReactionType) – New list of reaction types to set
on the message. Currently, as non-premium users, bots can set up to one reaction per
message. A custom emoji reaction can be used if it is either already present on the message
or explicitly allowed by chat administrators.
• is_big (bool) – Pass True to set the reaction with a big animation
Returns
bool
set_my_commands(commands: List[BotCommand], scope: BotCommandScope | None = None,
language_code: str | None = None) → bool
Use this method to change the list of the bot’s commands.
Telegram documentation: https://core.telegram.org/bots/api#setmycommands
Parameters
• commands (list of telebot.types.BotCommand) – List of BotCommand. At most 100
commands can be specified.
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands

1.3. Content 201

pyTelegramBotAPI, Release 4.25.0

Returns
True on success.
Return type
bool
set_my_default_administrator_rights(rights: ChatAdministratorRights = None, for_channels: bool |
None = None) → bool
Use this method to change the default administrator rights requested by the bot when it’s added as an
administrator to groups or channels. These rights will be suggested to users, but they are are free to modify
the list before adding the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmydefaultadministratorrights
Parameters
• rights (telebot.types.ChatAdministratorRights) – A JSON-serialized object de-
scribing new default administrator rights. If not specified, the default administrator rights
will be cleared.
• for_channels (bool) – Pass True to change the default administrator rights of the bot in
channels. Otherwise, the default administrator rights of the bot for groups and supergroups
will be changed.
Returns
True on success.
Return type
bool
set_my_description(description: str | None = None, language_code: str | None = None)
Use this method to change the bot’s description, which is shown in the chat with the bot if the chat is empty.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmydescription
Parameters
• description (str) – New bot description; 0-512 characters. Pass an empty string to
remove the dedicated description for the given language.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, the description
will be applied to all users for whose language there is no dedicated description.
Returns
True on success.
set_my_name(name: str | None = None, language_code: str | None = None)
Use this method to change the bot’s name. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmyname
Parameters
• name (str) – Optional. New bot name; 0-64 characters. Pass an empty string to remove
the dedicated name for the given language.
• language_code (str) – Optional. A two-letter ISO 639-1 language code. If empty, the
name will be shown to all users for whose language there is no dedicated name.
Returns
True on success.

202 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

set_my_short_description(short_description: str | None = None, language_code: str | None = None)

Use this method to change the bot’s short description, which is shown on the bot’s profile page and is sent
together with the link when users share the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmyshortdescription
Parameters
• short_description (str) – New short description for the bot; 0-120 characters. Pass
an empty string to remove the dedicated short description for the given language.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, the short de-
scription will be applied to all users for whose language there is no dedicated short descrip-
tion.
Returns
True on success.
set_state(user_id: int, state: str | State, chat_id: int | None = None, business_connection_id: str | None =
None, message_thread_id: int | None = None, bot_id: int | None = None) → bool
Sets a new state of a user.

ò Note

You should set both user id and chat id in order to set state for a user in a chat. Otherwise, if you only
set user_id, chat_id will equal to user_id, this means that state will be set for the user in his private chat
with a bot.

Changed in version 4.23.0: Added additional parameters to support topics, business connections, and mes-
sage threads.

ã See also

For more details, visit the custom_states.py example.

Parameters
• user_id (int) – User’s identifier
• state (int or str or telebot.types.State) – new state. can be string, or telebot.
types.State
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
True on success
Return type
bool

1.3. Content 203

pyTelegramBotAPI, Release 4.25.0

set_sticker_emoji_list(sticker: str, emoji_list: List[str]) → bool

Use this method to set the emoji list of a custom emoji sticker set. Returns True on success.
Parameters
• sticker (str) – Sticker identifier
• emoji_list (list of str) – List of emoji
Returns
Returns True on success.
Return type
bool
set_sticker_keywords(sticker: str, keywords: List[str] = None) → bool
Use this method to change search keywords assigned to a regular or custom emoji sticker. The sticker must
belong to a sticker set created by the bot. Returns True on success.
Parameters
• sticker (str) – File identifier of the sticker.
• keywords (list of str) – A JSON-serialized list of 0-20 search keywords for the sticker
with total length of up to 64 characters
Returns
On success, True is returned.
Return type
bool
set_sticker_mask_position(sticker: str, mask_position: MaskPosition = None) → bool
Use this method to change the mask position of a mask sticker. The sticker must belong to a sticker set that
was created by the bot. Returns True on success.
Parameters
• sticker (str) – File identifier of the sticker.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces.
Returns
Returns True on success.
Return type
bool
set_sticker_position_in_set(sticker: str, position: int) → bool
Use this method to move a sticker in a set created by the bot to a specific position . Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setstickerpositioninset
Parameters
• sticker (str) – File identifier of the sticker
• position (int) – New sticker position in the set, zero-based
Returns
On success, True is returned.
Return type
bool

204 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

set_sticker_set_thumb(**kwargs)

set_sticker_set_thumbnail(name: str, user_id: int, thumbnail: Any | str = None, format: str | None =
None) → bool
Use this method to set the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker
sets only. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setstickersetthumbnail
Parameters
• name (str) – Sticker set name
• user_id (int) – User identifier
• thumbnail (filelike object) – A .WEBP or .PNG image with the thumbnail, must be
up to 128 kilobytes in size and have a width and height of exactly 100px, or a .TGS ani-
mation with a thumbnail up to 32 kilobytes in size (see https://core.telegram.org/stickers#
animated-sticker-requirements for animated sticker technical requirements), or a WEBM
video with the thumbnail up to 32 kilobytes in size; see https://core.telegram.org/stickers#
video-sticker-requirements for video sticker technical requirements. Pass a file_id as a
String to send a file that already exists on the Telegram servers, pass an HTTP URL as a
String for Telegram to get a file from the Internet, or upload a new one using multipart/form-
data. More information on Sending Files ». Animated and video sticker set thumbnails
can’t be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first
sticker is used as the thumbnail.
• format (str) – Format of the thumbnail, must be one of “static” for a .WEBP or .PNG
image, “animated” for a .TGS animation, or “video” for a WEBM video
Returns
On success, True is returned.
Return type
bool
set_sticker_set_title(name: str, title: str) → bool
Use this method to set the title of a created sticker set. Returns True on success.
Parameters
• name (str) – Sticker set name
• title (str) – New sticker set title
Returns
Returns True on success.
Return type
bool
set_update_listener(listener: Callable)
Sets a listener function to be called when a new update is received.
Parameters
listener (Callable) – Listener function.
set_user_emoji_status(user_id: int, emoji_status_custom_emoji_id: str | None = None,
emoji_status_expiration_date: int | None = None) → bool
Changes the emoji status for a given user that previously allowed the bot to manage their emoji status via
the Mini App method requestEmojiStatusAccess. Returns True on success.

1.3. Content 205

pyTelegramBotAPI, Release 4.25.0

Telegram documentation: https://core.telegram.org/bots/api#setuseremojistatus

Parameters
• user_id (int) – Unique identifier of the target user
• emoji_status_custom_emoji_id (str) – Custom emoji identifier of the emoji status
to set. Pass an empty string to remove the status.
• emoji_status_expiration_date (int) – Expiration date of the emoji status, if any
Returns
bool
set_webhook(url: str | None = None, certificate: str | Any | None = None, max_connections: int | None =
None, allowed_updates: List[str] | None = None, ip_address: str | None = None,
drop_pending_updates: bool | None = None, timeout: int | None = None, secret_token: str |
None = None) → bool
Use this method to specify a URL and receive incoming updates via an outgoing webhook. Whenever
there is an update for the bot, we will send an HTTPS POST request to the specified URL, containing a
JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of
attempts. Returns True on success.
If you’d like to make sure that the webhook was set by you, you can specify secret data in the parameter
secret_token. If specified, the request will contain a header “X-Telegram-Bot-Api-Secret-Token” with the
secret token as content.
Telegram Documentation: https://core.telegram.org/bots/api#setwebhook
Parameters
• url (str, optional) – HTTPS URL to send updates to. Use an empty string to remove
webhook integration, defaults to None
• certificate (str, optional) – Upload your public key certificate so that the root certifi-
cate in use can be checked, defaults to None
• max_connections (int, optional) – The maximum allowed number of simultaneous
HTTPS connections to the webhook for update delivery, 1-100. Defaults to 40. Use
lower values to limit the load on your bot’s server, and higher values to increase your bot’s
throughput, defaults to None
• allowed_updates (list, optional) – A JSON-serialized list of the update types you
want your bot to receive. For example, specify [“message”, “edited_channel_post”, “call-
back_query”] to only receive updates of these types. See Update for a complete list of avail-
able update types. Specify an empty list to receive all update types except chat_member
(default). If not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the setWeb-
hook, so unwanted updates may be received for a short period of time. Defaults to None
• ip_address (str, optional) – The fixed IP address which will be used to send webhook
requests instead of the IP address resolved through DNS, defaults to None
• drop_pending_updates (bool, optional) – Pass True to drop all pending updates, de-
faults to None
• timeout (int, optional) – Timeout of a request, defaults to None
• secret_token (str, optional) – A secret token to be sent in a header “X-Telegram-Bot-
Api-Secret-Token” in every webhook request, 1-256 characters. Only characters A-Z, a-z,
0-9, _ and - are allowed. The header is useful to ensure that the request comes from a
webhook set by you. Defaults to None

206 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
True on success.
Return type
bool if the request was successful.
setup_middleware(middleware: BaseMiddleware)
Registers class-based middleware.
Parameters
middleware (telebot.handler_backends.BaseMiddleware) – Subclass of telebot.
handler_backends.BaseMiddleware
Returns
None
shipping_query_handler(func, **kwargs)
Handles new incoming shipping query. Only for invoices with flexible price. As a parameter to the decorator
function, it passes telebot.types.ShippingQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
stop_bot()
Stops bot by stopping polling and closing the worker pool.
stop_message_live_location(chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None, timeout: int | None = None,
business_connection_id: str | None = None) → Message
Use this method to stop updating a live location message before live_period expires. On success, if the
message is not an inline message, the edited Message is returned, otherwise True is returned.
Telegram documentation: https://core.telegram.org/bots/api#stopmessagelivelocation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the mes-
sage with live location to stop
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message with live location to stop
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – A JSON-serialized object for a new inline keyboard.
• timeout (int) – Timeout in seconds for the request.
• business_connection_id (str) – Identifier of a business connection
Returns
On success, if the message is not an inline message, the edited Message is returned, otherwise
True is returned.

1.3. Content 207

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.Message or bool
stop_poll(chat_id: int | str, message_id: int, reply_markup: InlineKeyboardMarkup | None = None,
business_connection_id: str | None = None) → Poll
Use this method to stop a poll which was sent by the bot. On success, the stopped Poll is returned.
Telegram documentation: https://core.telegram.org/bots/api#stoppoll
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• message_id (int) – Identifier of the original message with the poll
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for a new message
markup.
• business_connection_id (str) – Identifier of the business connection to use for the
poll
Returns
On success, the stopped Poll is returned.
Return type
types.Poll
stop_polling()
Stops polling.
Does not accept any arguments.
unban_chat_member(chat_id: int | str, user_id: int, only_if_banned: bool | None = False) → bool
Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to
the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator
for this to work. By default, this method guarantees that after the call the user is not a member of the chat,
but will be able to join it. So if the user is a member of the chat they will also be removed from the chat. If
you don’t want this, use the parameter only_if_banned.
Telegram documentation: https://core.telegram.org/bots/api#unbanchatmember
Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @username)
• user_id (int) – Unique identifier of the target user
• only_if_banned (bool) – Do nothing if the user is not banned
Returns
True on success
Return type
bool
unban_chat_sender_chat(chat_id: int | str, sender_chat_id: int | str) → bool
Use this method to unban a previously banned channel chat in a supergroup or channel. The bot must be an
administrator for this to work and must have the appropriate administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unbanchatsenderchat
Parameters

208 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sender_chat_id (int or str) – Unique identifier of the target sender chat.
Returns
True on success.
Return type
bool
unhide_general_forum_topic(chat_id: int | str) → bool
Use this method to unhide the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unhidegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
unpin_all_chat_messages(chat_id: int | str) → bool
Use this method to unpin a all pinned messages in a supergroup chat. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinallchatmessages
Parameters
chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
Returns
True on success.
Return type
bool
unpin_all_forum_topic_messages(chat_id: str | int, message_thread_id: int) → bool
Use this method to clear the list of pinned messages in a forum topic. The bot must be an administrator
in the chat for this to work and must have the can_pin_messages administrator right in the supergroup.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinallforumtopicmessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic
Returns
On success, True is returned.
Return type
bool
unpin_all_general_forum_topic_messages(chat_id: int | str) → bool
Use this method to clear the list of pinned messages in a General forum topic. The bot must be an adminis-
trator in the chat for this to work and must have the can_pin_messages administrator right in the supergroup.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinAllGeneralForumTopicMessages

1.3. Content 209

pyTelegramBotAPI, Release 4.25.0

Parameters
chat_id (int | str) – Unique identifier for the target chat or username of chat
Returns
On success, True is returned.
Return type
bool
unpin_chat_message(chat_id: int | str, message_id: int | None = None, business_connection_id: str | None
= None) → bool
Use this method to unpin specific pinned message in a supergroup chat. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinchatmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Int: Identifier of a message to unpin
• business_connection_id (str) – Unique identifier of the business connection
Returns
True on success.
Return type
bool
upload_sticker_file(user_id: int, png_sticker: Any | str = None, sticker: InputFile | None = None,
sticker_format: str | None = None) → File
Use this method to upload a .png file with a sticker for later use in createNewStickerSet and addStickerToSet
methods (can be used multiple times). Returns the uploaded File on success.
Telegram documentation: https://core.telegram.org/bots/api#uploadstickerfile
Parameters
• user_id (int) – User identifier of sticker set owner
• png_sticker (filelike object) – DEPRECATED: PNG image with the sticker, must
be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or
height must be exactly 512px.
• sticker (telebot.types.InputFile) – A file with the sticker in .WEBP, .PNG, .TGS,
or .WEBM format. See https://core.telegram.org/stickers for technical requirements. More
information on Sending Files »
• sticker_format (str) – One of “static”, “animated”, “video”.
Returns
On success, the sent file is returned.
Return type
telebot.types.File
property user: User
The User object representing this bot. Equivalent to bot.get_me() but the result is cached so only one API
call is needed.
Returns
Bot’s info.

210 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.User
verify_chat(chat_id: int | str, custom_description: str | None = None) → bool
Verifies a chat on behalf of the organization which is represented by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#verifychat
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
• custom_description (str) – Custom description for the verification; 0-70 characters.
Must be empty if the organization isn’t allowed to provide a custom verification description.
Returns
Returns True on success.
Return type
bool
verify_user(user_id: int, custom_description: str | None = None) → bool
Verifies a user on behalf of the organization which is represented by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#verifyuser
Parameters
• user_id (int) – Unique identifier of the target user
• custom_description (str) – Custom description for the verification; 0-70 characters.
Must be empty if the organization isn’t allowed to provide a custom verification description.
Returns
Returns True on success.
Return type
bool

custom_filters file
class telebot.custom_filters.AdvancedCustomFilter
Bases: ABC
Advanced Custom Filter base class. Create child class with check() method. Accepts two parameters, returns
bool: True - filter passed, False - filter failed. message: Message class text: Filter value given in handler
Child classes should have .key property.

Listing 9: Example on creating an advanced custom filter.

class TextStartsFilter(AdvancedCustomFilter):
# Filter to check whether message starts with some text.
key = 'text_startswith'

def check(self, message, text):

return message.text.startswith(text)

check(message, text)
Perform a check.

1.3. Content 211

pyTelegramBotAPI, Release 4.25.0

key: str = None

class telebot.custom_filters.ChatFilter
Bases: AdvancedCustomFilter
Check whether chat_id corresponds to given chat_id.

Listing 10: Example on using this filter:

@bot.message_handler(chat_id=[99999])
# your function

key: str = 'chat_id'

class telebot.custom_filters.ForwardFilter
Bases: SimpleCustomFilter
Check whether message was forwarded from channel or group.

Listing 11: Example on using this filter:

@bot.message_handler(is_forwarded=True)
# your function

key: str = 'is_forwarded'

class telebot.custom_filters.IsAdminFilter(bot)
Bases: SimpleCustomFilter
Check whether the user is administrator / owner of the chat.

Listing 12: Example on using this filter:

@bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
# your function

key: str = 'is_chat_admin'

class telebot.custom_filters.IsDigitFilter
Bases: SimpleCustomFilter
Filter to check whether the string is made up of only digits.

Listing 13: Example on using this filter:

@bot.message_handler(is_digit=True)
# your function

key: str = 'is_digit'

class telebot.custom_filters.IsReplyFilter
Bases: SimpleCustomFilter
Check whether message is a reply.

212 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Listing 14: Example on using this filter:

@bot.message_handler(is_reply=True)
# your function

key: str = 'is_reply'

class telebot.custom_filters.LanguageFilter
Bases: AdvancedCustomFilter
Check users language_code.

Listing 15: Example on using this filter:

@bot.message_handler(language_code=['ru'])
# your function

key: str = 'language_code'

class telebot.custom_filters.SimpleCustomFilter
Bases: ABC
Simple Custom Filter base class. Create child class with check() method. Accepts only message, returns bool
value, that is compared with given in handler.
Child classes should have .key property.

Listing 16: Example on creating a simple custom filter.

class ForwardFilter(SimpleCustomFilter):
# Check whether message was forwarded from channel or group.
key = 'is_forwarded'

def check(self, message):

return message.forward_date is not None

check(message)
Perform a check.
key: str = None

class telebot.custom_filters.StateFilter(bot)
Bases: AdvancedCustomFilter
Filter to check state.

Listing 17: Example on using this filter:

@bot.message_handler(state=1)
# your function

key: str = 'state'

class telebot.custom_filters.TextContainsFilter
Bases: AdvancedCustomFilter
Filter to check Text message. key: text

1.3. Content 213

pyTelegramBotAPI, Release 4.25.0

Listing 18: Example on using this filter:

# Will respond if any message.text contains word 'account'
@bot.message_handler(text_contains=['account'])
# your function

key: str = 'text_contains'

class telebot.custom_filters.TextFilter(equals: str | None = None, contains: list | tuple | None = None,
starts_with: str | list | tuple | None = None, ends_with: str | list |
tuple | None = None, ignore_case: bool = False)
Bases: object
Advanced text filter to check (types.Message, types.CallbackQuery, types.InlineQuery, types.Poll)
example of usage is in examples/custom_filters/advanced_text_filter.py
Parameters
• equals (str) – string, True if object’s text is equal to passed string
• contains (list[str] or tuple[str]) – list[str] or tuple[str], True if any string element
of iterable is in text
• starts_with (str) – string, True if object’s text starts with passed string
• ends_with (str) – string, True if object’s text starts with passed string
• ignore_case (bool) – bool (default False), case insensitive
Raises
ValueError – if incorrect value for a parameter was supplied
Returns
None
class telebot.custom_filters.TextMatchFilter
Bases: AdvancedCustomFilter
Filter to check Text message.

Listing 19: Example on using this filter:

@bot.message_handler(text=['account'])
# your function

key: str = 'text'

class telebot.custom_filters.TextStartsFilter
Bases: AdvancedCustomFilter
Filter to check whether message starts with some text.

Listing 20: Example on using this filter:

# Will work if message.text starts with 'sir'.
@bot.message_handler(text_startswith='sir')
# your function

key: str = 'text_startswith'

214 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

handler_backends file
class telebot.handler_backends.BaseMiddleware
Bases: object
Base class for middleware. Your middlewares should be inherited from this class.
Set update_sensitive=True if you want to get different updates on different functions. For example, if you want
to handle pre_process for message update, then you will have to create pre_process_message function, and so
on. Same applies to post_process.

ò Note

If you want to use middleware, you have to set use_class_middlewares=True in your TeleBot instance.

Listing 21: Example of class-based middlewares.

class MyMiddleware(BaseMiddleware):
def __init__(self):
self.update_sensitive = True
self.update_types = ['message', 'edited_message']

def pre_process_message(self, message, data):

# only message update here
pass

def post_process_message(self, message, data, exception):

pass # only message update here for post_process

def pre_process_edited_message(self, message, data):

# only edited_message update here
pass

def post_process_edited_message(self, message, data, exception):

pass # only edited_message update here for post_process

post_process(message, data, exception)

pre_process(message, data)

update_sensitive: bool = False

class telebot.handler_backends.CancelUpdate
Bases: object
Class for canceling updates. Just return instance of this class in middleware to skip update. Update will skip
handler and execution of post_process in middlewares.
class telebot.handler_backends.ContinueHandling
Bases: object
Class for continue updates in handlers. Just return instance of this class in handlers to continue process.

1.3. Content 215

pyTelegramBotAPI, Release 4.25.0

Listing 22: Example of using ContinueHandling

@bot.message_handler(commands=['start'])
def start(message):
bot.send_message(message.chat.id, 'Hello World!')
return ContinueHandling()

@bot.message_handler(commands=['start'])
def start2(message):
bot.send_message(message.chat.id, 'Hello World2!')

class telebot.handler_backends.SkipHandler
Bases: object
Class for skipping handlers. Just return instance of this class in middleware to skip handler. Update will go to
post_process, but will skip execution of handler.

Extensions

1.3.5 AsyncTeleBot
AsyncTeleBot methods
class telebot.async_telebot.AsyncTeleBot(token: str, parse_mode: str | None = None, offset: int | None =
None, exception_handler:
~telebot.async_telebot.ExceptionHandler | None = None,
state_storage:
~telebot.asyncio_storage.base_storage.StateStorageBase |
None = <tele-
bot.asyncio_storage.memory_storage.StateMemoryStorage
object>, disable_web_page_preview: bool | None = None,
disable_notification: bool | None = None, protect_content:
bool | None = None, allow_sending_without_reply: bool | None
= None, colorful_logs: bool | None = False, validate_token:
bool | None = True)
Bases: object
This is the main asynchronous class for Bot.
It allows you to add handlers for different kind of updates.
Usage:

Listing 23: Using asynchronous implementation of TeleBot.

from telebot.async_telebot import AsyncTeleBot
bot = AsyncTeleBot('token') # get token from @BotFather
# now you can register other handlers/update listeners,
# and use bot methods.
# Remember to use async/await keywords when necessary.

See more examples in examples/ directory: https://github.com/eternnoir/pyTelegramBotAPI/tree/master/

examples

216 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

ò Note

Install coloredlogs module to specify colorful_logs=True

Parameters
• token (str) – Token of a bot, obtained from @BotFather
• parse_mode (str, optional) – Default parse mode, defaults to None
• offset (int, optional) – Offset used in get_updates, defaults to None
• exception_handler (Optional[ExceptionHandler], optional) – Exception han-
dler, which will handle the exception occured, defaults to None
• state_storage (telebot.asyncio_storage.StateMemoryStorage, optional) – Stor-
age for states, defaults to StateMemoryStorage()
• disable_web_page_preview (bool, optional) – Default value for dis-
able_web_page_preview, defaults to None
• disable_notification (bool, optional) – Default value for disable_notification, defaults
to None
• protect_content (bool, optional) – Default value for protect_content, defaults to None
• allow_sending_without_reply (bool, optional) – Deprecated - Use reply_parameters
instead. Default value for allow_sending_without_reply, defaults to None
• colorful_logs (bool, optional) – Outputs colorful logs
• validate_token (bool, optional) – Validate token, defaults to True;
Raises
• ImportError – If coloredlogs module is not installed and colorful_logs is True
• ValueError – If token is invalid

add_custom_filter(custom_filter: SimpleCustomFilter | AdvancedCustomFilter)

Create custom filter.

Listing 24: Example on checking the text of a message

class TextMatchFilter(AdvancedCustomFilter):
key = 'text'

async def check(self, message, text):

return text == message.text

Parameters
custom_filter (telebot.asyncio_filters.SimpleCustomFilter or telebot.
asyncio_filters.AdvancedCustomFilter) – Class with check(message) method.
Returns
None

async add_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None, **kwargs) → None
Add data to states.

1.3. Content 217

pyTelegramBotAPI, Release 4.25.0

Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
• kwargs – Data to add
Returns
None
async add_sticker_to_set(user_id: int, name: str, emojis: List[str] | str = None, png_sticker: str | Any |
None = None, tgs_sticker: str | Any | None = None, webm_sticker: str | Any |
None = None, mask_position: MaskPosition | None = None, sticker:
InputSticker | None = None) → bool
Use this method to add a new sticker to a set created by the bot. The format of the added sticker must match
the format of the other stickers in the set. Emoji sticker sets can have up to 200 stickers. Animated and
video sticker sets can have up to 50 stickers. Static sticker sets can have up to 120 stickers. Returns True
on success.

ò Note

**_sticker, mask_position, emojis parameters are deprecated, use stickers instead

Telegram documentation: https://core.telegram.org/bots/api#addstickertoset

Parameters
• user_id (int) – User identifier of created sticker set owner
• name (str) – Sticker set name
• emojis (str) – One or more emoji corresponding to the sticker
• png_sticker (str or filelike object) – PNG image with the sticker, must be up to
512 kilobytes in size, dimensions must not exceed 512px, and either width or height must
be exactly 512px. Pass a file_id as a String to send a file that already exists on the Telegram
servers, pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload
a new one using multipart/form-data.
• tgs_sticker (str or filelike object) – TGS animation with the sticker, uploaded
using multipart/form-data.
• webm_sticker (str or filelike object) – WebM animation with the sticker, uploaded
using multipart/form-data.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces
• sticker (telebot.types.InputSticker) – A JSON-serialized object for sticker to be
added to the sticker set
Returns
On success, True is returned.

218 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
bool
async answer_callback_query(callback_query_id: int, text: str | None = None, show_alert: bool | None
= None, url: str | None = None, cache_time: int | None = None) → bool
Use this method to send answers to callback queries sent from inline keyboards. The answer will be dis-
played to the user as a notification at the top of the chat screen or as an alert.
Telegram documentation: https://core.telegram.org/bots/api#answercallbackquery
Parameters
• callback_query_id (int) – Unique identifier for the query to be answered
• text (str) – Text of the notification. If not specified, nothing will be shown to the user,
0-200 characters
• show_alert (bool) – If True, an alert will be shown by the client instead of a notification
at the top of the chat screen. Defaults to false.
• url (str) – URL that will be opened by the user’s client. If you have created a Game and
accepted the conditions via @BotFather, specify the URL that opens your game - note that
this will only work if the query comes from a callback_game button.
• cache_time – The maximum amount of time in seconds that the result of the callback
query may be cached client-side. Telegram apps will support caching starting in version
3.14. Defaults to 0.
Returns
On success, True is returned.
Return type
bool
async answer_inline_query(inline_query_id: str, results: List[Any], cache_time: int | None = None,
is_personal: bool | None = None, next_offset: str | None = None,
switch_pm_text: str | None = None, switch_pm_parameter: str | None =
None, button: InlineQueryResultsButton | None = None) → bool
Use this method to send answers to an inline query. On success, True is returned. No more than 50 results
per query are allowed.
Telegram documentation: https://core.telegram.org/bots/api#answerinlinequery
Parameters
• inline_query_id (str) – Unique identifier for the answered query
• results (list of types.InlineQueryResult) – Array of results for the inline query
• cache_time (int) – The maximum amount of time in seconds that the result of the inline
query may be cached on the server.
• is_personal (bool) – Pass True, if results may be cached on the server side only for the
user that sent the query.
• next_offset (str) – Pass the offset that a client should send in the next query with the
same text to receive more results.
• switch_pm_parameter (str) – Deep-linking parameter for the /start message sent to the
bot when user presses the switch button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are
allowed. Example: An inline bot that sends YouTube videos can ask the user to connect
the bot to their YouTube account to adapt search results accordingly. To do this, it displays
a ‘Connect your YouTube account’ button above the results, or even before showing any.

1.3. Content 219

pyTelegramBotAPI, Release 4.25.0

The user presses the button, switches to a private chat with the bot and, in doing so, passes
a start parameter that instructs the bot to return an OAuth link. Once done, the bot can offer
a switch_inline button so that the user can easily return to the chat where they wanted to
use the bot’s inline capabilities.
• switch_pm_text (str) – Parameter for the start message sent to the bot when user presses
the switch button
• button (types.InlineQueryResultsButton) – A JSON-serialized object describing
a button to be shown above inline query results
Returns
On success, True is returned.
Return type
bool
async answer_pre_checkout_query(pre_checkout_query_id: str, ok: bool, error_message: str | None =
None) → bool
Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in
the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout
queries. On success, True is returned.

ò Note

The Bot API must receive an answer within 10 seconds after the pre-checkout query was sent.

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

Parameters
• pre_checkout_query_id (int) – Unique identifier for the query to be answered
• ok (bool) – Specify True if everything is alright (goods are available, etc.) and the bot is
ready to proceed with the order. Use False if there are any problems.
• error_message (str) – Required if ok is False. Error message in human readable form
that explains the reason for failure to proceed with the checkout (e.g. “Sorry, somebody just
bought the last of our amazing black T-shirts while you were busy filling out your payment
details. Please choose a different color or garment!”). Telegram will display this message
to the user.
Returns
On success, True is returned.
Return type
bool
async answer_shipping_query(shipping_query_id: str, ok: bool, shipping_options:
List[ShippingOption] | None = None, error_message: str | None = None)
→ bool
Asks for an answer to a shipping question.
Telegram documentation: https://core.telegram.org/bots/api#answershippingquery
Parameters
• shipping_query_id (str) – Unique identifier for the query to be answered

220 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• ok (bool) – Specify True if delivery to the specified address is possible and False if there
are any problems (for example, if delivery to the specified address is not possible)
• shipping_options (list of ShippingOption) – Required if ok is True. A JSON-
serialized array of available shipping options.
• error_message (str) – Required if ok is False. Error message in human readable form
that explains why it is impossible to complete the order (e.g. “Sorry, delivery to your
desired address is unavailable’). Telegram will display this message to the user.
Returns
On success, True is returned.
Return type
bool
async answer_web_app_query(web_app_query_id: str, result: InlineQueryResultBase) →
SentWebAppMessage
Use this method to set the result of an interaction with a Web App and send a corresponding message on
behalf of the user to the chat from which the query originated. On success, a SentWebAppMessage object
is returned.
Telegram Documentation: https://core.telegram.org/bots/api#answerwebappquery
Parameters
• web_app_query_id (str) – Unique identifier for the query to be answered
• result (telebot.types.InlineQueryResultBase) – A JSON-serialized object de-
scribing the message to be sent
Returns
On success, a SentWebAppMessage object is returned.
Return type
telebot.types.SentWebAppMessage
async approve_chat_join_request(chat_id: str | int, user_id: int | str) → bool
Use this method to approve a chat join request. The bot must be an administrator in the chat for this to work
and must have the can_invite_users administrator right. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#approvechatjoinrequest
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int or str) – Unique identifier of the target user
Returns
True on success.
Return type
bool
async ban_chat_member(chat_id: int | str, user_id: int, until_date: int | datetime | None = None,
revoke_messages: bool | None = None) → bool
Use this method to ban a user in a group, a supergroup or a channel. In the case of supergroups and channels,
the user will not be able to return to the chat on their own using invite links, etc., unless unbanned first.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#banchatmember

1.3. Content 221

pyTelegramBotAPI, Release 4.25.0

Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @channelusername)
• user_id (int) – Unique identifier of the target user
• until_date (int or datetime) – Date when the user will be unbanned, unix time. If
user is banned for more than 366 days or less than 30 seconds from the current time they
are considered to be banned forever
• revoke_messages (bool) – Bool: Pass True to delete all messages from the chat for the
user that is being removed. If False, the user will be able to see messages in the group that
were sent before the user was removed. Always True for supergroups and channels.
Returns
Returns True on success.
Return type
bool
async ban_chat_sender_chat(chat_id: int | str, sender_chat_id: int | str) → bool
Use this method to ban a channel chat in a supergroup or a channel. The owner of the chat will not be able
to send messages and join live streams on behalf of the chat, unless it is unbanned first. The bot must be
an administrator in the supergroup or channel for this to work and must have the appropriate administrator
rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#banchatsenderchat
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sender_chat_id (int or str) – Unique identifier of the target sender chat
Returns
True on success.
Return type
bool
business_connection_handler(func=None, **kwargs)
Handles new incoming business connection state.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
business_message_handler(commands: List[str] | None = None, regexp: str | None = None, func:
Callable | None = None, content_types: List[str] | None = None, **kwargs)
Handles New incoming message of any kind(for business accounts, see bot api 7.2 for more) - text, photo,
sticker, etc. As a parameter to the decorator function, it passes telebot.types.Message object. All
message handlers are tested in the order they were added.
Example:

222 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Listing 25: Usage of business_message_handler

bot = TeleBot('TOKEN')

# Handles all messages which text matches regexp.

@bot.business_message_handler(regexp='someregexp')
def command_help(message):
bot.send_message(message.chat.id, 'Did someone call for help?')

# Handle all sent documents of type 'text/plain'.

@bot.business_message_handler(func=lambda message: message.document.mime_type␣
˓→== 'text/plain',

content_types=['document'])
def command_handle_document(message):
bot.send_message(message.chat.id, 'Document received, sir!')

# Handle all other messages.

@bot.business_message_handler(func=lambda message: True, content_types=['audio',
˓→ 'photo', 'voice', 'video', 'document',

'text', 'location', 'contact', 'sticker'])

def default_command(message):
bot.send_message(message.chat.id, "This is the default command handler.")

Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (lambda) – Optional lambda function. The lambda receives the message to test as
the first parameter. It must return True if the command should handle the message.
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function

callback_query_handler(func=None, **kwargs)
Handles new incoming callback query. As a parameter to the decorator function, it passes telebot.
types.CallbackQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
channel_post_handler(commands=None, regexp=None, func=None, content_types=None, **kwargs)
Handles new incoming channel post of any kind - text, photo, sticker, etc. As a parameter to the decorator
function, it passes telebot.types.Message object.
Parameters

1.3. Content 223

pyTelegramBotAPI, Release 4.25.0

• commands (list of str) – Optional list of strings (commands to handle).

• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_boost_handler(func=None, **kwargs)
Handles new incoming chat boost state. it passes telebot.types.ChatBoostUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_join_request_handler(func=None, **kwargs)
Handles a request to join the chat has been sent. The bot must have the can_invite_users administrator right
in the chat to receive these updates. As a parameter to the decorator function, it passes telebot.types.
ChatJoinRequest object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chat_member_handler(func=None, **kwargs)
Handles update in a status of a user in a chat. The bot must be an administrator in the chat and must
explicitly specify “chat_member” in the list of allowed_updates to receive these updates. As a parameter
to the decorator function, it passes telebot.types.ChatMemberUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
chosen_inline_handler(func, **kwargs)
The result of an inline query that was chosen by a user and sent to their chat partner. Please see our
documentation on the feedback collecting for details on how to enable these updates for your bot. As a
parameter to the decorator function, it passes telebot.types.ChosenInlineResult object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

224 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
None
async close() → bool
Use this method to close the bot instance before moving it from one local server to another. You need to
delete the webhook before calling this method to ensure that the bot isn’t launched again after server restart.
The method will return error 429 in the first 10 minutes after the bot is launched. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#close
Returns
bool
async close_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to close an open topic in a forum supergroup chat. The bot must be an administrator in the
chat for this to work and must have the can_manage_topics administrator rights, unless it is the creator of
the topic. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#closeforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to close
Returns
On success, True is returned.
Return type
bool
async close_general_forum_topic(chat_id: int | str) → bool
Use this method to close the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#closegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
async close_session()
Closes existing session of aiohttp. Use this function if you stop polling/webhooks.
async copy_message(chat_id: int | str, from_chat_id: int | str, message_id: int, caption: str | None = None,
parse_mode: str | None = None, caption_entities: List[MessageEntity] | None =
None, disable_notification: bool | None = None, protect_content: bool | None = None,
reply_to_message_id: int | None = None, allow_sending_without_reply: bool | None
= None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None =
None, show_caption_above_media: bool | None = None, allow_paid_broadcast: bool
| None = None) → MessageID
Use this method to copy messages of any kind. If some of the specified messages can’t be found or copied,
they are skipped. Service messages, paid media messages, giveaway messages, giveaway winners mes-
sages, and invoice messages can’t be copied. A quiz poll can be copied only if the value of the field
correct_option_id is known to the bot. The method is analogous to the method forwardMessages, but the

1.3. Content 225

pyTelegramBotAPI, Release 4.25.0

copied messages don’t have a link to the original message. Album grouping is kept for copied messages.
On success, an array of MessageId of the sent messages is returned.
Telegram documentation: https://core.telegram.org/bots/api#copymessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_id (int) – Message identifier in the chat specified in from_chat_id
• caption (str) – New caption for media, 0-1024 characters after entities parsing. If not
specified, the original caption is kept
• parse_mode (str) – Mode for parsing entities in the new caption.
• caption_entities (Array of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the new caption, which can be specified instead of
parse_mode
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the MessageId of the sent message is returned.
Return type
telebot.types.MessageID

226 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async copy_messages(chat_id: str | int, from_chat_id: str | int, message_ids: List[int],

disable_notification: bool | None = None, message_thread_id: int | None = None,
protect_content: bool | None = None, remove_caption: bool | None = None) →
List[MessageID]
Use this method to copy messages of any kind. Service messages, paid media messages, giveaway mes-
sages, giveaway winners messages, and invoice messages can’t be copied. A quiz poll can be copied only
if the value of the field correct_option_id is known to the bot. The method is analogous to the method for-
wardMessage, but the copied message doesn’t have a link to the original message. Returns the MessageId
of the sent message on success.
Telegram documentation: https://core.telegram.org/bots/api#copymessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_ids (list of int) – Message identifiers in the chat specified in from_chat_id
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound
• message_thread_id (int) – Identifier of a message thread, in which the messages will
be sent
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
• remove_caption (bool) – Pass True to copy the messages without their captions
Returns
On success, an array of MessageId of the sent messages is returned.
Return type
list of telebot.types.MessageID
async create_chat_invite_link(chat_id: int | str, name: str | None = None, expire_date: int | datetime |
None = None, member_limit: int | None = None, creates_join_request:
bool | None = None) → ChatInviteLink
Use this method to create an additional invite link for a chat. The bot must be an administrator in the chat for
this to work and must have the appropriate administrator rights. The link can be revoked using the method
revokeChatInviteLink. Returns the new invite link as ChatInviteLink object.
Telegram documentation: https://core.telegram.org/bots/api#createchatinvitelink
Parameters
• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• expire_date (int or datetime) – Point in time (Unix timestamp) when the link will
expire
• member_limit (int) – Maximum number of users that can be members of the chat simul-
taneously
• creates_join_request (bool) – True, if users joining the chat via the link need to be
approved by chat administrators. If True, member_limit can’t be specified

1.3. Content 227

pyTelegramBotAPI, Release 4.25.0

Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
async create_chat_subscription_invite_link(chat_id: int | str, subscription_period: int,
subscription_price: int, name: str | None = None) →
ChatInviteLink
Use this method to create a subscription invite link for a channel chat. The bot must have the
can_invite_users administrator rights. The link can be edited using the method editChatSubscriptionIn-
viteLink or revoked using the method revokeChatInviteLink. Returns the new invite link as a ChatIn-
viteLink object.
Telegram documentation: https://core.telegram.org/bots/api#createchatsubscriptioninvitelink
Parameters
• chat_id (int or str) – Unique identifier for the target channel chat or username of the
target channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• subscription_period (int) – The number of seconds the subscription will be active
for before the next payment. Currently, it must always be 2592000 (30 days).
• subscription_price (int) – The amount of Telegram Stars a user must pay initially
and after each subsequent subscription period to be a member of the chat; 1-2500
Returns
Returns the new invite link as a ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
async create_forum_topic(chat_id: int, name: str, icon_color: int | None = None,
icon_custom_emoji_id: str | None = None) → ForumTopic
Use this method to create a topic in a forum supergroup chat. The bot must be an administrator in the chat
for this to work and must have the can_manage_topics administrator rights. Returns information about the
created topic as a ForumTopic object.
Telegram documentation: https://core.telegram.org/bots/api#createforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Name of the topic, 1-128 characters
• icon_color (int) – Color of the topic icon in RGB format. Currently, must be one of
0x6FB9F0, 0xFFD67E, 0xCB86DB, 0x8EEE98, 0xFF93B2, or 0xFB6F5F
• icon_custom_emoji_id (str) – Custom emoji for the topic icon. Must be an emoji of
type “tgs” and must be exactly 1 character long
Returns
On success, information about the created topic is returned as a ForumTopic object.
Return type
telebot.types.ForumTopic

228 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async create_invoice_link(title: str, description: str, payload: str, provider_token: str | None,
currency: str, prices: List[LabeledPrice], max_tip_amount: int | None =
None, suggested_tip_amounts: List[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, subscription_period: int | None = None, business_connection_id: str |
None = None) → str
Use this method to create a link for an invoice. Returns the created invoice link as String on success.
Telegram documentation: https://core.telegram.org/bots/api#createinvoicelink
Parameters
• business_connection_id (str) – Unique identifier of the business connection on behalf
of which the link will be created
• title (str) – Product name, 1-32 characters
• description (str) – Product description, 1-255 characters
• payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be displayed to
the user, use for your internal processes.
• provider_token (str) – Payments provider token, obtained via @Botfather; Pass None
to omit the parameter to use “XTR” currency
• currency (str) – Three-letter ISO 4217 currency code, see https://core.telegram.org/
bots/payments#supported-currencies
• prices (list of types.LabeledPrice) – Price breakdown, a list of components (e.g.
product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• subscription_period (int) – The number of seconds the subscription will be active
for before the next payment. The currency must be set to “XTR” (Telegram Stars) if the
parameter is used. Currently, it must always be 2592000 (30 days) if specified.
• max_tip_amount (int) – The maximum accepted amount for tips in the smallest units of
the currency
• suggested_tip_amounts (list of int) – A JSON-serialized array of suggested
amounts of tips in the smallest units of the currency. At most 4 suggested tip amounts
can be specified. The suggested tip amounts must be positive, passed in a strictly increased
order and must not exceed max_tip_amount.
• provider_data (str) – A JSON-serialized data about the invoice, which will be shared
with the payment provider. A detailed description of required fields should be provided by
the payment provider.
• photo_url (str) – URL of the product photo for the invoice. Can be a photo of the goods
or a photo of the invoice. People like it better when they see a photo of what they are paying
for.
• photo_size (int) – Photo size in bytes
• photo_width (int) – Photo width
• photo_height (int) – Photo height
• need_name (bool) – Pass True, if you require the user’s full name to complete the order

1.3. Content 229

pyTelegramBotAPI, Release 4.25.0

• need_phone_number (bool) – Pass True, if you require the user’s phone number to com-
plete the order
• need_email (bool) – Pass True, if you require the user’s email to complete the order
• need_shipping_address (bool) – Pass True, if you require the user’s shipping address
to complete the order
• send_phone_number_to_provider (bool) – Pass True, if user’s phone number should
be sent to provider
• send_email_to_provider (bool) – Pass True, if user’s email address should be sent to
provider
• is_flexible (bool) – Pass True, if the final price depends on the shipping method
Returns
Created invoice link as String on success.
Return type
str
async create_new_sticker_set(user_id: int, name: str, title: str, emojis: List[str] | None = None,
png_sticker: Any | str = None, tgs_sticker: Any | str = None,
webm_sticker: Any | str = None, contains_masks: bool | None = None,
sticker_type: str | None = None, mask_position: MaskPosition | None =
None, needs_repainting: bool | None = None, stickers:
List[InputSticker] = None, sticker_format: str | None = None) → bool
Use this method to create new sticker set owned by a user. The bot will be able to edit the created sticker
set. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#createnewstickerset

ò Note

Fields *_sticker are deprecated, pass a list of stickers to stickers parameter instead.

Parameters
• user_id (int) – User identifier of created sticker set owner
• name (str) – Short name of sticker set, to be used in t.me/addstickers/ URLs (e.g., animals).
Can contain only English letters, digits and underscores. Must begin with a letter, can’t con-
tain consecutive underscores and must end in “_by_<bot_username>”. <bot_username>
is case insensitive. 1-64 characters.
• title (str) – Sticker set title, 1-64 characters
• emojis (str) – One or more emoji corresponding to the sticker
• png_sticker (str) – PNG image with the sticker, must be up to 512 kilobytes in size,
dimensions must not exceed 512px, and either width or height must be exactly 512px. Pass
a file_id as a String to send a file that already exists on the Telegram servers, pass an HTTP
URL as a String for Telegram to get a file from the Internet, or upload a new one using
multipart/form-data.
• tgs_sticker (str) – TGS animation with the sticker, uploaded using multipart/form-
data.
• webm_sticker (str) – WebM animation with the sticker, uploaded using multipart/form-
data.

230 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• contains_masks (bool) – Pass True, if a set of mask stickers should be created. Depre-
cated since Bot API 6.2, use sticker_type instead.
• sticker_type (str) – Type of stickers in the set, pass “regular”, “mask”, or “cus-
tom_emoji”. By default, a regular sticker set is created.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces
• needs_repainting (bool) – Pass True if stickers in the sticker set must be repainted to
the color of text when used in messages, the accent color if used as emoji status, white on
chat photos, or another appropriate color based on context; for custom emoji sticker sets
only
• stickers (list of telebot.types.InputSticker) – List of stickers to be added to
the set
• sticker_format (str) – deprecated
Returns
On success, True is returned.
Return type
bool

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

Use this method to decline a chat join request. The bot must be an administrator in the chat for this to work
and must have the can_invite_users administrator right. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#declinechatjoinrequest
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int or str) – Unique identifier of the target user
Returns
True on success.
Return type
bool
async delete_chat_photo(chat_id: int | str) → bool
Use this method to delete a chat photo. Photos can’t be changed for private chats. The bot must be an
administrator in the chat for this to work and must have the appropriate admin rights. Returns True on
success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are
Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#deletechatphoto
Parameters
chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
Returns
True on success.
Return type
bool

1.3. Content 231

pyTelegramBotAPI, Release 4.25.0

async delete_chat_sticker_set(chat_id: int | str) → bool

Use this method to delete a group sticker set from a supergroup. The bot must be an administrator in the chat
for this to work and must have the appropriate admin rights. Use the field can_set_sticker_set optionally
returned in getChat requests to check if the bot can use this method. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletechatstickerset
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group (in the format @supergroupusername)
Returns
Returns True on success.
Return type
bool
async delete_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to delete a topic in a forum supergroup chat. The bot must be an administrator in the chat
for this to work and must have the can_manage_topics administrator rights, unless it is the creator of the
topic. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deleteforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to delete
Returns
On success, True is returned.
Return type
bool
async delete_message(chat_id: int | str, message_id: int, timeout: int | None = None) → bool
Use this method to delete a message, including service messages, with the following limitations: - A mes-
sage can only be deleted if it was sent less than 48 hours ago. - A dice message in a private chat can only be
deleted if it was sent more than 24 hours ago. - Bots can delete outgoing messages in private chats, groups,
and supergroups. - Bots can delete incoming messages in private chats. - Bots granted can_post_messages
permissions can delete outgoing messages in channels. - If the bot is an administrator of a group, it can
delete any message there. - If the bot has can_delete_messages permission in a supergroup or a channel, it
can delete any message there. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Identifier of the message to delete
• timeout (int) – Timeout in seconds for the request.
Returns
Returns True on success.
Return type
bool

232 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async delete_messages(chat_id: int | str, message_ids: List[int])

Use this method to delete multiple messages simultaneously. If some of the specified messages can’t be
found, they are skipped. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_ids (list of int) – Identifiers of the messages to be deleted
Returns
Returns True on success.
async delete_my_commands(scope: BotCommandScope | None = None, language_code: int | None =
None) → bool
Use this method to delete the list of the bot’s commands for the given scope and user language. After
deletion, higher level commands will be shown to affected users. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletemycommands
Parameters
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands
Returns
True on success.
Return type
bool
async delete_state(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → bool
Delete the current state of a user.
Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
Returns
None
async delete_sticker_from_set(sticker: str) → bool
Use this method to delete a sticker from a set created by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#deletestickerfromset
Parameters
sticker – File identifier of the sticker
Returns
On success, True is returned.
Return type
bool

1.3. Content 233

pyTelegramBotAPI, Release 4.25.0

async delete_sticker_set(name: str) → bool

Use this method to delete a sticker set. Returns True on success.
Parameters
name (str) – Sticker set name
Returns
Returns True on success.
Return type
bool
async delete_webhook(drop_pending_updates: bool | None = None, timeout: int | None = None) → bool
Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True
on success.
Telegram documentation: https://core.telegram.org/bots/api#deletewebhook
Parameters
• drop_pending_updates – Pass True to drop all pending updates, defaults to None
• timeout (int, optional) – Request connection timeout, defaults to None
Returns
Returns True on success.
Return type
bool
deleted_business_messages_handler(func=None, **kwargs)
Handles new incoming deleted messages state.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async download_file(file_path: str | None) → bytes
Downloads file.
Parameters
file_path (str) – Path where the file should be downloaded.
Returns
bytes
Return type
bytes
async edit_chat_invite_link(chat_id: int | str, invite_link: str | None = None, name: str | None = None,
expire_date: int | datetime | None = None, member_limit: int | None =
None, creates_join_request: bool | None = None) → ChatInviteLink
Use this method to edit a non-primary invite link created by the bot. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#editchatinvitelink
Parameters

234 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – Invite link name; 0-32 characters
• invite_link (str) – The invite link to edit
• expire_date (int or datetime) – Point in time (Unix timestamp) when the link will
expire
• member_limit (int) – Maximum number of users that can be members of the chat simul-
taneously
• creates_join_request (bool) – True, if users joining the chat via the link need to be
approved by chat administrators. If True, member_limit can’t be specified
Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
async edit_chat_subscription_invite_link(chat_id: int | str, invite_link: str, name: str | None =
None) → ChatInviteLink
Use this method to edit a subscription invite link created by the bot. The bot must have the can_invite_users
administrator rights. Returns the edited invite link as a ChatInviteLink object.
Telegram documentation: https://core.telegram.org/bots/api#editchatsubscriptioninvitelink
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• invite_link (str) – The invite link to edit
• name (str) – Invite link name; 0-32 characters
Returns
Returns the edited invite link as a ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
async edit_forum_topic(chat_id: int | str, message_thread_id: int, name: str | None = None,
icon_custom_emoji_id: str | None = None) → bool
Use this method to edit name and icon of a topic in a forum supergroup chat. The bot must be an admin-
istrator in the chat for this to work and must have can_manage_topics administrator rights, unless it is the
creator of the topic. Returns True on success.
Telegram Documentation: https://core.telegram.org/bots/api#editforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to edit
• name (str) – Optional, New name of the topic, 1-128 characters. If not specififed or empty,
the current name of the topic will be kept
• icon_custom_emoji_id (str) – Optional, New unique identifier of the custom emoji
shown as the topic icon. Use getForumTopicIconStickers to get all allowed custom emoji

1.3. Content 235

pyTelegramBotAPI, Release 4.25.0

identifiers. Pass an empty string to remove the icon. If not specified, the current icon will
be kept
Returns
On success, True is returned.
Return type
bool
async edit_general_forum_topic(chat_id: int | str, name: str) → bool
Use this method to edit the name of the ‘General’ topic in a forum supergroup chat. The bot must be an
administrator in the chat for this to work and must have can_manage_topics administrator rights. Returns
True on success.
Telegram documentation: https://core.telegram.org/bots/api#editgeneralforumtopic
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• name (str) – New topic name, 1-128 characters
async edit_message_caption(caption: str, chat_id: int | str | None = None, message_id: int | None =
None, inline_message_id: str | None = None, parse_mode: str | None =
None, caption_entities: List[MessageEntity] | None = None, reply_markup:
InlineKeyboardMarkup | None = None, show_caption_above_media: bool |
None = None, business_connection_id: str | None = None, timeout: int |
None = None) → Message | bool
Use this method to edit captions of messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagecaption
Parameters
• caption (str) – New caption of the message
• chat_id (int | str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel
• message_id (int) – Required if inline_message_id is not specified.
• inline_message_id (str) – Required if inline_message_id is not specified. Identifier of
the inline message.
• parse_mode (str) – New caption of the message, 0-1024 characters after entities parsing
• caption_entities (list of types.MessageEntity) – A JSON-serialized array of ob-
jects that describe how the caption should be parsed.
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for an inline key-
board.
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• business_connection_id (str) – Identifier of the business connection to send the mes-
sage through
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.

236 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
types.Message | bool
async edit_message_live_location(latitude: float, longitude: float, chat_id: int | str | None = None,
message_id: int | None = None, inline_message_id: str | None =
None, reply_markup: InlineKeyboardMarkup | None = None,
timeout: int | None = None, horizontal_accuracy: float | None =
None, heading: int | None = None, proximity_alert_radius: int |
None = None, live_period: int | None = None,
business_connection_id: str | None = None) → Message

Use this method to edit live location messages. A location can be edited until its live_period expires
or editing is explicitly
disabled by a call to stopMessageLiveLocation. On success, if the edited message is not an inline
message, the edited Message is returned, otherwise True is returned.
Telegram documentation: https://core.telegram.org/bots/api#editmessagelivelocation
Parameters
• latitude (float) – Latitude of new location
• longitude (float) – Longitude of new location
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the mes-
sage to edit
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – A JSON-serialized object for a new inline keyboard.
• timeout (int) – Timeout in seconds for the request.
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• horizontal_accuracy (float) – The radius of uncertainty for the location, measured
in meters; 0-1500
• heading (int) – Direction in which the user is moving, in degrees. Must be between 1
and 360 if specified.
• proximity_alert_radius (int) – The maximum distance for proximity alerts about
approaching another chat member, in meters. Must be between 1 and 100000 if specified.
• live_period (int) – New period in seconds during which the location can be updated,
starting from the message send date. If 0x7FFFFFFF is specified, then the location can be
updated forever. Otherwise, the new value must not exceed the current live_period by more
than a day, and the live location expiration date must remain within the next 90 days. If not
specified, then live_period remains unchanged
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be edited
Returns
On success, if the edited message is not an inline message, the edited Message is returned,
otherwise True is returned.
Return type
telebot.types.Message or bool

1.3. Content 237

pyTelegramBotAPI, Release 4.25.0

async edit_message_media(media: Any, chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup: InlineKeyboardMarkup
| None = None, business_connection_id: str | None = None, timeout: int |
None = None) → Message | bool
Use this method to edit animation, audio, document, photo, or video messages, or to add media to text
messages. If a message is part of a message album, then it can be edited only to an audio for audio albums,
only to a document for document albums and to a photo or a video otherwise. When an inline message
is edited, a new file can’t be uploaded; use a previously uploaded file via its file_id or specify a URL. On
success, if the edited message is not an inline message, the edited Message is returned, otherwise True is
returned. Note that business messages that were not sent by the bot and do not contain an inline keyboard
can only be edited within 48 hours from the time they were sent.
Telegram documentation: https://core.telegram.org/bots/api#editmessagemedia
Parameters
• media (InputMedia) – A JSON-serialized object for a new media content of the message
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• reply_markup (telebot.types.InlineKeyboardMarkup or
ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply) – A JSON-
serialized object for an inline keyboard.
• business_connection_id (str) – Unique identifier of the business connection
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool
async edit_message_reply_markup(chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None, business_connection_id: str
| None = None, timeout: int | None = None) → Message | bool
Use this method to edit only the reply markup of messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagereplymarkup
Parameters
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message

238 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or

ReplyKeyboardRemove or ForceReply) – A JSON-serialized object for an inline
keyboard.
• business_connection_id (str) – Unique identifier of the business connection
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool
async edit_message_text(text: str, chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, parse_mode: str | None = None,
entities: List[MessageEntity] | None = None, disable_web_page_preview: bool
| None = None, reply_markup: InlineKeyboardMarkup | None = None,
link_preview_options: LinkPreviewOptions | None = None,
business_connection_id: str | None = None, timeout: int | None = None) →
Message | bool
Use this method to edit text and game messages.
Telegram documentation: https://core.telegram.org/bots/api#editmessagetext
Parameters
• text (str) – New text of the message, 1-4096 characters after entities parsing
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• parse_mode (str) – Mode for parsing entities in the message text.
• entities (List of telebot.types.MessageEntity) – List of special entities that ap-
pear in the message text, which can be specified instead of parse_mode
• disable_web_page_preview (bool) – Deprecated - Use link_preview_options instead.
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for an inline key-
board.
• link_preview_options (LinkPreviewOptions) – A JSON-serialized object for op-
tions used to automatically generate Telegram link previews for messages.
• business_connection_id (str) – Unique identifier of the business connection
• timeout (int) – Timeout in seconds for the request.
Returns
On success, if edited message is sent by the bot, the edited Message is returned, otherwise
True is returned.
Return type
types.Message or bool

1.3. Content 239

pyTelegramBotAPI, Release 4.25.0

async edit_user_star_subscription(user_id: int, telegram_payment_charge_id: str, is_canceled:

bool) → bool
Allows the bot to cancel or re-enable extension of a subscription paid in Telegram Stars. Returns True on
success.
Telegram documentation: https://core.telegram.org/bots/api#edituserstarsubscription
Parameters
• user_id (int) – Identifier of the user whose subscription will be edited
• telegram_payment_charge_id (str) – Telegram payment identifier for the subscription
• is_canceled (bool) – Pass True to cancel extension of the user subscription; the sub-
scription must be active up to the end of the current subscription period. Pass False to
allow the user to re-enable a subscription that was previously canceled by the bot.
Returns
On success, True is returned.
Return type
bool
edited_business_message_handler(commands=None, regexp=None, func=None, content_types=None,
**kwargs)
Handles new version of a message(business accounts) that is known to the bot and was edited. As a param-
eter to the decorator function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns
None
edited_channel_post_handler(commands=None, regexp=None, func=None, content_types=None,
**kwargs)
Handles new version of a channel post that is known to the bot and was edited. As a parameter to the
decorator function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• kwargs – Optional keyword arguments(custom filters)
Returns

240 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

edited_message_handler(commands=None, regexp=None, func=None, content_types=None,

chat_types=None, **kwargs)
Handles new version of a message that is known to the bot and was edited.
As a parameter to the decorator function, it passes telebot.types.Message object.
Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• chat_types (list of str) – list of chat types
• kwargs – Optional keyword arguments(custom filters)
Returns
None
enable_saving_states(filename='./.state-save/states.pkl')
Enable saving states (by default saving disabled)

ò Note

It is recommended to pass a StatePickleStorage instance as state_storage to TeleBot class.

Parameters
filename (str, optional) – Filename of saving file, defaults to “./.state-save/states.pkl”

async export_chat_invite_link(chat_id: int | str) → str

Use this method to export an invite link to a supergroup or a channel. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#exportchatinvitelink
Parameters
chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
Returns
exported invite link as String on success.
Return type
str
async forward_message(chat_id: int | str, from_chat_id: int | str, message_id: int, disable_notification:
bool | None = None, protect_content: bool | None = None, timeout: int | None =
None, message_thread_id: int | None = None) → Message
Use this method to forward messages of any kind.
Telegram documentation: https://core.telegram.org/bots/api#forwardmessage
Parameters
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound

1.3. Content 241

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_id (int) – Message identifier in the chat specified in from_chat_id
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Unique identifier for the target message thread (topic) of the
forum; for forum supergroups only
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async forward_messages(chat_id: str | int, from_chat_id: str | int, message_ids: List[int],
disable_notification: bool | None = None, message_thread_id: int | None =
None, protect_content: bool | None = None) → List[MessageID]
Use this method to forward multiple messages of any kind. If some of the specified messages can’t be found
or forwarded, they are skipped. Service messages and messages with protected content can’t be forwarded.
Album grouping is kept for forwarded messages. On success, an array of MessageId of the sent messages
is returned.
Telegram documentation: https://core.telegram.org/bots/api#forwardmessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• from_chat_id (int or str) – Unique identifier for the chat where the original message
was sent (or channel username in the format @channelusername)
• message_ids (list) – Message identifiers in the chat specified in from_chat_id
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound
• message_thread_id (int) – Identifier of a message thread, in which the messages will
be sent
• protect_content (bool) – Protects the contents of the forwarded message from forward-
ing and saving
Returns
On success, the sent Message is returned.
Return type
telebot.types.MessageID
async get_available_gifts() → Gifts
Returns the list of gifts that can be sent by the bot to users. Requires no parameters. Returns a Gifts object.
Telegram documentation: https://core.telegram.org/bots/api#getavailablegifts
Returns
On success, a Gifts object is returned.

242 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.Gifts
async get_business_connection(business_connection_id: str) → BusinessConnection
Use this method to get information about the connection of the bot with a business account. Returns a
BusinessConnection object on success.
Telegram documentation: https://core.telegram.org/bots/api#getbusinessconnection
Parameters
business_connection_id (str) – Unique identifier of the business connection
Returns
Returns a BusinessConnection object on success.
Return type
telebot.types.BusinessConnection
async get_chat(chat_id: int | str) → ChatFullInfo
Use this method to get up to date information about the chat (current name of the user for one-on-one
conversations, current username of a user, group or channel, etc.). Returns a Chat object on success.
Telegram documentation: https://core.telegram.org/bots/api#getchat
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
Chat information
Return type
telebot.types.ChatFullInfo
async get_chat_administrators(chat_id: int | str) → List[ChatMember]
Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember
objects that contains information about all chat administrators except other bots.
Telegram documentation: https://core.telegram.org/bots/api#getchatadministrators
Parameters
chat_id – Unique identifier for the target chat or username of the target supergroup or channel
(in the format @channelusername)
Returns
List made of ChatMember objects.
Return type
list of telebot.types.ChatMember
async get_chat_member(chat_id: int | str, user_id: int) → ChatMember
Use this method to get information about a member of a chat. Returns a ChatMember object on success.
Telegram documentation: https://core.telegram.org/bots/api#getchatmember
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int) – Unique identifier of the target user
Returns
Returns ChatMember object on success.

1.3. Content 243

pyTelegramBotAPI, Release 4.25.0

Return type
telebot.types.ChatMember
async get_chat_member_count(chat_id: int | str) → int
Use this method to get the number of members in a chat.
Telegram documentation: https://core.telegram.org/bots/api#getchatmembercount
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
Number of members in the chat.
Return type
int
get_chat_members_count(**kwargs)

async get_chat_menu_button(chat_id: int | str = None) → MenuButton

Use this method to get the current value of the bot’s menu button in a private chat, or the default menu
button. Returns MenuButton on success.
Telegram Documentation: https://core.telegram.org/bots/api#getchatmenubutton
Parameters
chat_id (int or str) – Unique identifier for the target private chat. If not specified, default
bot’s menu button will be returned.
Returns
types.MenuButton
Return type
telebot.types.MenuButton
async get_custom_emoji_stickers(custom_emoji_ids: List[str]) → List[Sticker]
Use this method to get information about custom emoji stickers by their identifiers. Returns an Array of
Sticker objects.
Parameters
custom_emoji_ids (list of str) – List of custom emoji identifiers. At most 200 custom
emoji identifiers can be specified.
Returns
Returns an Array of Sticker objects.
Return type
list of telebot.types.Sticker
async get_file(file_id: str | None) → File
Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can
download files of up to 20MB in size. On success, a File object is returned. It is guaranteed that the link
will be valid for at least 1 hour. When the link expires, a new one can be requested by calling get_file again.
Telegram documentation: https://core.telegram.org/bots/api#getfile
Parameters
file_id (str) – File identifier
Returns
telebot.types.File

244 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async get_file_url(file_id: str | None) → str

Get a valid URL for downloading a file.
Parameters
file_id (str) – File identifier to get download URL for.
Returns
URL for downloading the file.
Return type
str
async get_forum_topic_icon_stickers() → List[Sticker]
Use this method to get custom emoji stickers, which can be used as a forum topic icon by any user. Requires
no parameters. Returns an Array of Sticker objects.
Telegram documentation: https://core.telegram.org/bots/api#getforumtopiciconstickers
Returns
On success, a list of StickerSet objects is returned.
Return type
List[telebot.types.StickerSet]
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]
Use this method to get data for high score tables. Will return the score of the specified user and several of
their neighbors in a game. On success, returns an Array of GameHighScore objects.
This method will currently return scores for the target user, plus two of their closest neighbors on each side.
Will also return the top three users if the user and their neighbors are not among them. Please note that this
behavior is subject to change.
Telegram documentation: https://core.telegram.org/bots/api#getgamehighscores
Parameters
• user_id (int) – User identifier
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
Returns
On success, returns an Array of GameHighScore objects.
Return type
List[types.GameHighScore]
async get_me() → User
Returns basic information about the bot in form of a User object.
Telegram documentation: https://core.telegram.org/bots/api#getme
async get_my_commands(scope: BotCommandScope | None, language_code: str | None) →
List[BotCommand]
Use this method to get the current list of the bot’s commands. Returns List of BotCommand on success.

1.3. Content 245

pyTelegramBotAPI, Release 4.25.0

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

Parameters
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands
Returns
List of BotCommand on success.
Return type
list of telebot.types.BotCommand
async get_my_default_administrator_rights(for_channels: bool = None) →
ChatAdministratorRights
Use this method to get the current default administrator rights of the bot. Returns ChatAdministratorRights
on success.
Telegram documentation: https://core.telegram.org/bots/api#getmydefaultadministratorrights
Parameters
for_channels (bool) – Pass True to get the default administrator rights of the bot in chan-
nels. Otherwise, the default administrator rights of the bot for groups and supergroups will
be returned.
Returns
Returns ChatAdministratorRights on success.
Return type
telebot.types.ChatAdministratorRights
async get_my_description(language_code: str | None = None)
Use this method to get the current bot description for the given user language. Returns BotDescription on
success.
Parameters
language_code (str) – A two-letter ISO 639-1 language code or an empty string
Returns
telebot.types.BotDescription
async get_my_name(language_code: str | None = None)
Use this method to get the current bot name for the given user language. Returns BotName on success.
Telegram documentation: https://core.telegram.org/bots/api#getmyname
Parameters
language_code (str) – Optional. A two-letter ISO 639-1 language code or an empty string
Returns
telebot.types.BotName
async get_my_short_description(language_code: str | None = None)
Use this method to get the current bot short description for the given user language. Returns BotShortDe-
scription on success.
Parameters
language_code (str) – A two-letter ISO 639-1 language code or an empty string

246 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
telebot.types.BotShortDescription
async get_star_transactions(offset: int | None = None, limit: int | None = None) → StarTransactions
Returns the bot’s Telegram Star transactions in chronological order.
Telegram documentation: https://core.telegram.org/bots/api#getstartransactions
Parameters
• offset (int) – Number of transactions to skip in the response
• limit (int) – The maximum number of transactions to be retrieved. Values between 1-
100 are accepted. Defaults to 100.
Returns
On success, returns a StarTransactions object.
Return type
types.StarTransactions
async get_state(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → str
Gets current state of a user. Not recommended to use this method. But it is ok for debugging.

. Warning

Even if you are using telebot.types.State, this method will return a string. When comparing(not
recommended), you should compare this string with telebot.types.State.name

Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
state of a user
Return type
str

async get_sticker_set(name: str) → StickerSet

Use this method to get a sticker set. On success, a StickerSet object is returned.
Telegram documentation: https://core.telegram.org/bots/api#getstickerset
Parameters
name (str) – Sticker set name
Returns
On success, a StickerSet object is returned.
Return type
telebot.types.StickerSet

1.3. Content 247

pyTelegramBotAPI, Release 4.25.0

async get_updates(offset: int | None = None, limit: int | None = None, timeout: int | None = 20,
allowed_updates: List | None = None, request_timeout: int | None = None) →
List[Update]
Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is
returned.
Telegram documentation: https://core.telegram.org/bots/api#getupdates
Parameters
• offset (int, optional) – Identifier of the first update to be returned. Must be greater
by one than the highest among the identifiers of previously received updates. By default,
updates starting with the earliest unconfirmed update are returned. An update is considered
confirmed as soon as getUpdates is called with an offset higher than its update_id. The
negative offset can be specified to retrieve updates starting from -offset update from the
end of the updates queue. All previous updates will forgotten.
• limit (int, optional) – Limits the number of updates to be retrieved. Values between
1-100 are accepted. Defaults to 100.
• timeout (int, optional) – Request connection timeout
• allowed_updates (list, optional) – Array of string. List the types of updates you want
your bot to receive.
• request_timeout (int, optional) – Timeout in seconds for request.
Returns
An Array of Update objects is returned.
Return type
list of telebot.types.Update
async get_user_chat_boosts(chat_id: int | str, user_id: int) → UserChatBoosts
Use this method to get the list of boosts added to a chat by a user. Requires administrator rights in the chat.
Returns a UserChatBoosts object.
Telegram documentation: https://core.telegram.org/bots/api#getuserchatboosts
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• user_id (int) – Unique identifier of the target user
Returns
On success, a UserChatBoosts object is returned.
Return type
telebot.types.UserChatBoosts
async get_user_profile_photos(user_id: int, offset: int | None = None, limit: int | None = None) →
UserProfilePhotos
Use this method to get a list of profile pictures for a user. Returns a telebot.types.UserProfilePhotos
object.
Telegram documentation: https://core.telegram.org/bots/api#getuserprofilephotos
Parameters
• user_id (int) – Unique identifier of the target user
• offset (int) – Sequential number of the first photo to be returned. By default, all photos
are returned.

248 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• limit (int) – Limits the number of photos to be retrieved. Values between 1-100 are
accepted. Defaults to 100.
Returns
UserProfilePhotos
Return type
telebot.types.UserProfilePhotos
async get_webhook_info(timeout: int | None = None) → WebhookInfo
Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo
object. If the bot is using getUpdates, will return an object with the url field empty.
Telegram documentation: https://core.telegram.org/bots/api#getwebhookinfo
Parameters
timeout (int, optional) – Request connection timeout
Returns
On success, returns a WebhookInfo object.
Return type
telebot.types.WebhookInfo
async hide_general_forum_topic(chat_id: int | str) → bool
Use this method to hide the ‘General’ topic in a forum supergroup chat. The bot must be an administrator in
the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#hidegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
async infinity_polling(timeout: int | None = 20, skip_pending: bool | None = False, request_timeout:
int | None = None, logger_level: int | None = 40, allowed_updates: List[str] |
None = None, restart_on_change: bool | None = False, path_to_watch: str |
None = None, *args, **kwargs)
Wrap polling with infinite loop and exception handling to avoid bot stops polling.

ò Note

Install watchdog and psutil before using restart_on_change option.

Parameters
• timeout (int) – Timeout in seconds for get_updates(Defaults to None)
• skip_pending (bool) – skip old updates
• request_timeout (int) – Aiohttp’s request timeout. Defaults to 5 min-
utes(aiohttp.ClientTimeout).
• logger_level (int) – Custom logging level for infinity_polling logging. Use logger
levels from logging as a value. None/NOTSET = no error logging
• allowed_updates (list of str) – A list of the update types you want your bot to re-
ceive. For example, specify [“message”, “edited_channel_post”, “callback_query”] to only
receive updates of these types. See util.update_types for a complete list of available update

1.3. Content 249

pyTelegramBotAPI, Release 4.25.0

types. Specify an empty list to receive all update types except chat_member (default). If
not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the
get_updates, so unwanted updates may be received for a short period of time.
• restart_on_change (bool) – Restart a file on file(s) change. Defaults to False
• path_to_watch (str) – Path to watch for changes. Defaults to current directory
Returns
None

inline_handler(func, **kwargs)
Handles new incoming inline query. As a parameter to the decorator function, it passes telebot.types.
InlineQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async kick_chat_member(chat_id: int | str, user_id: int, until_date: int | datetime | None = None,
revoke_messages: bool | None = None) → bool
This function is deprecated. Use ban_chat_member instead
async leave_chat(chat_id: int | str) → bool
Use this method for your bot to leave a group, supergroup or channel. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#leavechat
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target super-
group or channel (in the format @channelusername)
Returns
bool
async log_out() → bool
Use this method to log out from the cloud Bot API server before launching the bot locally. You MUST log
out the bot before running it locally, otherwise there is no guarantee that the bot will receive updates. After
a successful call, you can immediately log in on a local server, but will not be able to log in back to the
cloud Bot API server for 10 minutes. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#logout
Returns
True on success.
Return type
bool
message_handler(commands=None, regexp=None, func=None, content_types=None, chat_types=None,
**kwargs)
Handles new incoming message of any kind - text, photo, sticker, etc. As a parameter to the decorator
function, it passes telebot.types.Message object. All message handlers are tested in the order they
were added.

250 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Example:

Listing 26: Usage of message_handler

bot = TeleBot('TOKEN')

# Handles all messages which text matches regexp.

@bot.message_handler(regexp='someregexp')
async def command_help(message):
await bot.send_message(message.chat.id, 'Did someone call for help?')

# Handles messages in private chat

@bot.message_handler(chat_types=['private']) # You can add more chat types
async def command_help(message):
await bot.send_message(message.chat.id, 'Private chat detected, sir!')

# Handle all sent documents of type 'text/plain'.

@bot.message_handler(func=lambda message: message.document.mime_type == 'text/
˓→plain',

content_types=['document'])
async def command_handle_document(message):
await bot.send_message(message.chat.id, 'Document received, sir!')

# Handle all other messages.

@bot.message_handler(func=lambda message: True, content_types=['audio', 'photo',
˓→ 'voice', 'video', 'document',

'text', 'location', 'contact', 'sticker'])

async def default_command(message):
await bot.send_message(message.chat.id, "This is the default command␣
˓→handler.")

Parameters
• commands (list of str) – Optional list of strings (commands to handle).
• regexp (str) – Optional regular expression.
• func – Optional lambda function. The lambda receives the message to test as the first
parameter. It must return True if the command should handle the message.
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• chat_types (list of str) – list of chat types
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function

message_reaction_count_handler(func=None, **kwargs)
Handles new incoming message reaction count. As a parameter to the decorator function, it passes
telebot.types.MessageReactionCountUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

1.3. Content 251

pyTelegramBotAPI, Release 4.25.0

Returns
message_reaction_handler(func=None, **kwargs)
Handles new incoming message reaction. As a parameter to the decorator function, it passes telebot.
types.MessageReactionUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
my_chat_member_handler(func=None, **kwargs)
Handles update in a status of a bot. For private chats, this update is received only when the bot is
blocked or unblocked by the user. As a parameter to the decorator function, it passes telebot.types.
ChatMemberUpdated object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async pin_chat_message(chat_id: int | str, message_id: int, disable_notification: bool | None = False,
business_connection_id: str | None = None) → bool
Use this method to pin a message in a supergroup. The bot must be an administrator in the chat for this to
work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#pinchatmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Identifier of a message to pin
• disable_notification (bool) – Pass True, if it is not necessary to send a notification
to all group members about the new pinned message
• business_connection_id (str) – Unique identifier of the business connection
Returns
True on success.
Return type
bool
poll_answer_handler(func=None, **kwargs)
Handles change of user’s answer in a non-anonymous poll(when user changes the vote). Bots receive new
votes only in polls that were sent by the bot itself. As a parameter to the decorator function, it passes
telebot.types.PollAnswer object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

252 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
None
poll_handler(func, **kwargs)
Handles new state of a poll. Bots receive only updates about stopped polls and polls, which are sent by the
bot As a parameter to the decorator function, it passes telebot.types.Poll object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async polling(non_stop: bool = True, skip_pending=False, interval: int = 0, timeout: int = 20,
request_timeout: int | None = None, allowed_updates: List[str] | None = None, none_stop:
bool | None = None, restart_on_change: bool | None = False, path_to_watch: str | None =
None)
Runs bot in long-polling mode in a main loop. This allows the bot to retrieve Updates automagically and
notify listeners and message handlers accordingly.
Warning: Do not call this function more than once!
Always gets updates.

ò Note

Install watchdog and psutil before using restart_on_change option.

Parameters
• non_stop (bool) – Do not stop polling when an ApiException occurs.
• skip_pending (bool) – skip old updates
• interval (int) – Delay between two update retrivals
• timeout (int) – Request connection timeout
• request_timeout (int) – Timeout in seconds for get_updates(Defaults to None)
• allowed_updates (list of str) – A list of the update types you want your bot to re-
ceive. For example, specify [“message”, “edited_channel_post”, “callback_query”] to only
receive updates of these types. See util.update_types for a complete list of available update
types. Specify an empty list to receive all update types except chat_member (default). If
not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the
get_updates, so unwanted updates may be received for a short period of time.
• none_stop (bool) – Deprecated, use non_stop. Old typo, kept for backward compatibility.
• restart_on_change (bool) – Restart a file on file(s) change. Defaults to False.
• path_to_watch (str) – Path to watch for changes. Defaults to current directory
Returns

1.3. Content 253

pyTelegramBotAPI, Release 4.25.0

pre_checkout_query_handler(func, **kwargs)
New incoming pre-checkout query. Contains full information about checkout. As a parameter to the deco-
rator function, it passes telebot.types.PreCheckoutQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async process_new_updates(updates: List[Update])
Process new updates. Just pass list of updates - each update should be instance of Update object.
Parameters
updates (list of telebot.types.Update) – list of updates
Returns
None
async promote_chat_member(chat_id: int | str, user_id: int, can_change_info: bool | None = None,
can_post_messages: bool | None = None, can_edit_messages: bool | None =
None, can_delete_messages: bool | None = None, can_invite_users: bool |
None = None, can_restrict_members: bool | None = None,
can_pin_messages: bool | None = None, can_promote_members: bool |
None = None, is_anonymous: bool | None = None, can_manage_chat: bool |
None = None, can_manage_video_chats: bool | None = None,
can_manage_voice_chats: bool | None = None, can_manage_topics: bool |
None = None, can_post_stories: bool | None = None, can_edit_stories: bool
| None = None, can_delete_stories: bool | None = None) → bool
Use this method to promote or demote a user in a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean parameters
to demote a user.
Telegram documentation: https://core.telegram.org/bots/api#promotechatmember
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel ( in the format @channelusername)
• user_id (int) – Unique identifier of the target user
• can_change_info (bool) – Pass True, if the administrator can change chat title, photo
and other settings
• can_post_messages (bool) – Pass True, if the administrator can create channel posts,
channels only
• can_edit_messages (bool) – Pass True, if the administrator can edit messages of other
users, channels only
• can_delete_messages (bool) – Pass True, if the administrator can delete messages of
other users
• can_invite_users (bool) – Pass True, if the administrator can invite new users to the
chat
• can_restrict_members (bool) – Pass True, if the administrator can restrict, ban or un-
ban chat members

254 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• can_pin_messages (bool) – Pass True, if the administrator can pin messages, super-
groups only
• can_promote_members (bool) – Pass True, if the administrator can add new adminis-
trators with a subset of his own privileges or demote administrators that he has promoted,
directly or indirectly (promoted by administrators that were appointed by him)
• is_anonymous (bool) – Pass True, if the administrator’s presence in the chat is hidden
• can_manage_chat (bool) – Pass True, if the administrator can access the chat event log,
chat statistics, message statistics in channels, see channel members, see anonymous ad-
ministrators in supergroups and ignore slow mode. Implied by any other administrator
privilege
• can_manage_video_chats (bool) – Pass True, if the administrator can manage voice
chats For now, bots can use this privilege only for passing to other administrators.
• can_manage_voice_chats (bool) – Deprecated, use can_manage_video_chats.
• can_manage_topics (bool) – Pass True if the user is allowed to create, rename, close,
and reopen forum topics, supergroups only
• can_post_stories (bool) – Pass True if the administrator can create the channel’s stories
• can_edit_stories (bool) – Pass True if the administrator can edit the channel’s stories
• can_delete_stories (bool) – Pass True if the administrator can delete the channel’s
stories
Returns
True on success.
Return type
bool
purchased_paid_media_handler(func=None, **kwargs)
Handles new incoming purchased paid media.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async refund_star_payment(user_id: int, telegram_payment_charge_id: str) → bool
Refunds a successful payment in Telegram Stars. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#refundstarpayment
Parameters
• user_id (int) – Identifier of the user whose payment will be refunded
• telegram_payment_charge_id (str) – Telegram payment identifier
Returns
On success, True is returned.
Return type
bool

1.3. Content 255

pyTelegramBotAPI, Release 4.25.0

register_business_connection_handler(callback: Callable, func: Callable | None = None, pass_bot:

bool | None = False, **kwargs)
Registers business connection handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_business_message_handler(callback: Callable, commands: List[str] | None = None, regexp:
str | None = None, func: Callable | None = None, content_types:
List[str] | None = None, pass_bot: bool | None = False,
**kwargs)
Registers business connection handler.
Parameters
• callback (function) – function to be called
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• pass_bot (bool) – True, if bot instance should be passed to handler
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_callback_query_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot:
bool | None = False, **kwargs)
Registers callback query handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_channel_post_handler(callback: Callable[[Any], Awaitable], content_types: List[str] | None
= None, commands: List[str] | None = None, regexp: str | None =
None, func: Callable | None = None, pass_bot: bool | None = False,
**kwargs)

256 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Registers channel post message handler.

Parameters
• callback (Awaitable) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_boost_handler(callback: Callable, func: Callable | None = None, pass_bot: bool | None
= False, **kwargs)
Registers chat boost handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot – True if you need to pass TeleBot instance to handler(useful for separating
handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_join_request_handler(callback: Callable[[Any], Awaitable], func: Callable | None =
None, pass_bot: bool | None = False, **kwargs)
Registers chat join request handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_chat_member_handler(callback: Callable[[Any], Awaitable], func: Callable | None = None,
pass_bot: bool | None = False, **kwargs)
Registers chat member handler.
Parameters

1.3. Content 257

pyTelegramBotAPI, Release 4.25.0

• callback (Awaitable`) – function to be called

• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
:return:None
register_chosen_inline_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot: bool
| None = False, **kwargs)
Registers chosen inline handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_deleted_business_messages_handler(callback: Callable, func: Callable | None = None,
pass_bot: bool | None = False, **kwargs)
Registers deleted business messages handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_edited_business_message_handler(callback: Callable, content_types: List[str] | None =
None, commands: List[str] | None = None, regexp: str |
None = None, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers edited message handler for business accounts.
Parameters
• callback (function) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter

258 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_edited_channel_post_handler(callback: Callable[[Any], Awaitable], content_types: List[str]
| None = None, commands: List[str] | None = None, regexp:
str | None = None, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers edited channel post message handler.
Parameters
• callback (Awaitable) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_edited_message_handler(callback: Callable[[Any], Awaitable], content_types: List[str] |
None = None, commands: List[str] | None = None, regexp: str |
None = None, func: Callable | None = None, chat_types: List[str] |
None = None, pass_bot: bool | None = False, **kwargs)
Registers edited message handler.
Parameters
• callback (Awaitable) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str) – Regular expression
• func (function) – Function executed as a filter
• chat_types (bool) – True for private chat
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None

1.3. Content 259

pyTelegramBotAPI, Release 4.25.0

register_inline_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot: bool | None =

False, **kwargs)
Registers inline handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_message_handler(callback: Callable[[Any], Awaitable], content_types: List[str] | None = None,
commands: List[str] | None = None, regexp: str | None = None, func:
Callable | None = None, chat_types: List[str] | None = None, pass_bot: bool |
None = False, **kwargs)
Registers message handler.
Parameters
• callback (Awaitable) – function to be called
• content_types (list of str) – Supported message content types. Must be a list. De-
faults to [‘text’].
• commands (list of str) – list of commands
• regexp (str)
• func (function) – Function executed as a filter
• chat_types (list of str) – List of chat types
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_message_reaction_count_handler(callback: Callable[[Any], Awaitable], func: Callable =
None, pass_bot: bool | None = False, **kwargs)
Registers message reaction count handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None

260 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

register_message_reaction_handler(callback: Callable[[Any], Awaitable], func: Callable = None,

pass_bot: bool | None = False, **kwargs)
Registers message reaction handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_my_chat_member_handler(callback: Callable[[Any], Awaitable], func: Callable | None =
None, pass_bot: bool | None = False, **kwargs)
Registers my chat member handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_poll_answer_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot: bool |
None = False, **kwargs)
Registers poll answer handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_poll_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot: bool | None =
False, **kwargs)
Registers poll handler.
Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter

1.3. Content 261

pyTelegramBotAPI, Release 4.25.0

• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_pre_checkout_query_handler(callback: Callable[[Any], Awaitable], func: Callable,
pass_bot: bool | None = False, **kwargs)
Registers pre-checkout request handler.
Parameters
• callback (Awaitable) – function to be called
• func – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
decorated function
register_purchased_paid_media_handler(callback: Callable, func: Callable, pass_bot: bool | None =
False, **kwargs)
Registers purchased paid media handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_removed_chat_boost_handler(callback: Callable, func: Callable | None = None, pass_bot:
bool | None = False, **kwargs)
Registers removed chat boost handler.
Parameters
• callback (function) – function to be called
• func (function) – Function executed as a filter
• pass_bot – True if you need to pass TeleBot instance to handler(useful for separating
handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
register_shipping_query_handler(callback: Callable[[Any], Awaitable], func: Callable, pass_bot:
bool | None = False, **kwargs)
Registers shipping query handler.

262 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Parameters
• callback (Awaitable) – function to be called
• func (function) – Function executed as a filter
• pass_bot (bool) – True if you need to pass TeleBot instance to handler(useful for sepa-
rating handlers into different files)
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async remove_chat_verification(chat_id: int | str) → bool
Removes verification from a chat that is currently verified on behalf of the organization represented by the
bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#removechatverification
Parameters
chat_id (int | str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
Returns
Returns True on success.
Return type
bool
async remove_user_verification(user_id: int) → bool
Removes verification from a user who is currently verified on behalf of the organization represented by the
bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#removeuserverification
Parameters
user_id (int) – Unique identifier of the target user
Returns
Returns True on success.
Return type
bool
async remove_webhook() → bool
Alternative for delete_webhook but uses set_webhook
removed_chat_boost_handler(func=None, **kwargs)
Handles new incoming chat boost state. it passes telebot.types.ChatBoostRemoved object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)
Returns
None
async reopen_forum_topic(chat_id: str | int, message_thread_id: int) → bool
Use this method to reopen a closed topic in a forum supergroup chat. The bot must be an administrator in
the chat for this to work and must have the can_manage_topics administrator rights, unless it is the creator
of the topic. Returns True on success.

1.3. Content 263

pyTelegramBotAPI, Release 4.25.0

Telegram documentation: https://core.telegram.org/bots/api#reopenforumtopic

Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic to reopen
Returns
On success, True is returned.
Return type
bool
async reopen_general_forum_topic(chat_id: int | str) → bool
Use this method to reopen the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#reopengeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
async replace_sticker_in_set(user_id: int, name: str, old_sticker: str, sticker: InputSticker) → bool

Use this method to replace an existing sticker in a sticker set with a new one. The method is
equivalent to calling deleteStickerFromSet, then addStickerToSet,
then setStickerPositionInSet. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#replaceStickerInSet
Parameters
• user_id (int) – User identifier of the sticker set owner
• name (str) – Sticker set name
• old_sticker (str) – File identifier of the replaced sticker
• sticker (telebot.types.InputSticker) – A JSON-serialized object with informa-
tion about the added sticker. If exactly the same sticker had already been added to the set,
then the set remains unchanged.
Returns
Returns True on success.
Return type
bool
async reply_to(message: Message, text: str, **kwargs) → Message
Convenience function for send_message(message.chat.id, text, re-
ply_parameters=(message.message_id. . . ), **kwargs)
Parameters
• message (types.Message) – Instance of telebot.types.Message
• text (str) – Text of the message.
• kwargs – Additional keyword arguments which are passed to telebot.TeleBot.
send_message()

264 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async reset_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → bool
Reset data for a user in chat.
Parameters
• user_id (int) – User’s identifier
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
True on success
Return type
bool
async restrict_chat_member(chat_id: int | str, user_id: int, until_date: int | datetime | None = None,
can_send_messages: bool | None = None, can_send_media_messages:
bool | None = None, can_send_polls: bool | None = None,
can_send_other_messages: bool | None = None,
can_add_web_page_previews: bool | None = None, can_change_info: bool
| None = None, can_invite_users: bool | None = None, can_pin_messages:
bool | None = None, permissions: ChatPermissions | None = None,
use_independent_chat_permissions: bool | None = None) → bool
Use this method to restrict a user in a supergroup. The bot must be an administrator in the supergroup
for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift
restrictions from a user.
Telegram documentation: https://core.telegram.org/bots/api#restrictchatmember

. Warning

Individual parameters are deprecated and will be removed, use ‘permissions’ instead

Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @channelusername)
• user_id (int) – Unique identifier of the target user
• until_date (int or datetime, optional) – Date when restrictions will be lifted for the
user, unix time. If user is restricted for more than 366 days or less than 30 seconds from
the current time, they are considered to be restricted forever
• can_send_messages (bool) – deprecated
• can_send_media_messages (bool) – deprecated

1.3. Content 265

pyTelegramBotAPI, Release 4.25.0

• can_send_polls (bool) – deprecated

• can_send_other_messages (bool) – deprecated
• can_add_web_page_previews (bool) – deprecated
• can_change_info (bool) – deprecated
• can_invite_users (bool) – deprecated
• can_pin_messages (bool) – deprecated
• use_independent_chat_permissions (bool, optional) – Pass True if chat per-
missions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos, can_send_videos,
can_send_video_notes, and can_send_voice_notes permissions; the can_send_polls
permission will imply the can_send_messages permission.
• permissions (types.ChatPermissions) – Pass ChatPermissions object to set all per-
missions at once. Use this parameter instead of passing all boolean parameters to avoid
backward compatibility problems in future.
Returns
True on success
Return type
bool

retrieve_data(user_id: int, chat_id: int | None = None, business_connection_id: str | None = None,
message_thread_id: int | None = None, bot_id: int | None = None) → Dict[str, Any] | None
Returns context manager with data for a user in chat.
Parameters
• user_id (int) – User identifier
• chat_id (int, optional) – Chat’s unique identifier, defaults to user_id
• bot_id (int, optional) – Bot’s identifier, defaults to current bot id
• business_connection_id (str, optional) – Business identifier
• message_thread_id (int, optional) – Identifier of the message thread
Returns
Context manager with data for a user in chat
Return type
dict
async revoke_chat_invite_link(chat_id: int | str, invite_link: str) → ChatInviteLink
Use this method to revoke an invite link created by the bot. Note: If the primary link is revoked, a new link
is automatically generated The bot must be an administrator in the chat for this to work and must have the
appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#revokechatinvitelink
Parameters
• chat_id (int or str) – Id: Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• invite_link (str) – The invite link to revoke

266 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Returns the new invite link as ChatInviteLink object.
Return type
telebot.types.ChatInviteLink
async run_webhooks(listen: str | None = '127.0.0.1', port: int | None = 443, url_path: str | None = None,
certificate: str | None = None, certificate_key: str | None = None, webhook_url: str |
None = None, max_connections: int | None = None, allowed_updates: List | None =
None, ip_address: str | None = None, drop_pending_updates: bool | None = None,
timeout: int | None = None, secret_token: str | None = None, secret_token_length: int
| None = 20, debug: bool | None = False)
This class sets webhooks and listens to a given url and port.
Parameters
• listen – IP address to listen to. Defaults to 0.0.0.0
• port – A port which will be used to listen to webhooks.
• url_path – Path to the webhook. Defaults to /token
• certificate – Path to the certificate file.
• certificate_key – Path to the certificate key file.
• webhook_url – Webhook URL.
• max_connections – Maximum allowed number of simultaneous HTTPS connections to
the webhook for update delivery, 1-100. Defaults to 40. Use lower values to limit the load
on your bot’s server, and higher values to increase your bot’s throughput.
• allowed_updates – A JSON-serialized list of the update types you want your bot to re-
ceive. For example, specify [“message”, “edited_channel_post”, “callback_query”] to only
receive updates of these types. See Update for a complete list of available update types.
Specify an empty list to receive all updates regardless of type (default). If not specified,
the previous setting will be used.
• ip_address – The fixed IP address which will be used to send webhook requests instead
of the IP address resolved through DNS
• drop_pending_updates – Pass True to drop all pending updates
• timeout – Integer. Request connection timeout
• secret_token – Secret token to be used to verify the webhook request.
• secret_token_length – Length of a secret token, defaults to 20
• debug – Debug mode, defaults to False
Returns
async save_prepared_inline_message(user_id: int, result: InlineQueryResultBase, 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
Stores a message that can be sent by a user of a Mini App. Returns a PreparedInlineMessage object.
Telegram Documentation: https://core.telegram.org/bots/api#savepreparedinlinemessage
Parameters
• user_id (int) – Unique identifier of the target user that can use the prepared message

1.3. Content 267

pyTelegramBotAPI, Release 4.25.0

• result (telebot.types.InlineQueryResultBase) – A JSON-serialized object de-

scribing the message to be sent
• allow_user_chats (bool, optional) – Pass True if the message can be sent to private
chats with users
• allow_bot_chats (bool, optional) – Pass True if the message can be sent to private chats
with bots
• allow_group_chats (bool, optional) – Pass True if the message can be sent to group
and supergroup chats
• allow_channel_chats (bool, optional) – Pass True if the message can be sent to channel
chats
Returns
telebot.types.PreparedInlineMessage
async send_animation(chat_id: int | str, animation: Any | str, duration: int | None = None, width: int |
None = None, height: int | None = None, thumbnail: str | Any | None = None,
caption: str | None = None, parse_mode: str | None = None, caption_entities:
List[MessageEntity] | None = None, disable_notification: bool | None = None,
protect_content: bool | None = None, reply_to_message_id: int | None = None,
allow_sending_without_reply: bool | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, timeout: int | None = None, message_thread_id: int |
None = None, has_spoiler: bool | None = None, thumb: str | Any | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, show_caption_above_media:
bool | None = None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). On success,
the sent Message is returned. Bots can currently send animation files of up to 50 MB in size, this limit may
be changed in the future.
Telegram documentation: https://core.telegram.org/bots/api#sendanimation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• animation (str or telebot.types.InputFile) – Animation to send. Pass a file_id as
String to send an animation that exists on the Telegram servers (recommended), pass an
HTTP URL as a String for Telegram to get an animation from the Internet, or upload a new
animation using multipart/form-data.
• duration (int) – Duration of sent animation in seconds
• width (int) – Animation width
• height (int) – Animation height
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.

268 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• caption (str) – Animation caption (may also be used when resending animation by
file_id), 0-1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the animation caption
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• message_thread_id (int) – Identifier of a message thread, in which the video will be
sent
• has_spoiler (bool) – Pass True, if the animation should be sent as a spoiler
• thumb (str or telebot.types.InputFile) – Deprecated. Use thumbnail instead
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

1.3. Content 269

pyTelegramBotAPI, Release 4.25.0

async send_audio(chat_id: int | str, audio: Any | str, caption: str | None = None, duration: int | None =
None, performer: str | None = None, title: str | None = None, reply_to_message_id: int |
None = None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, parse_mode: str | None = None,
disable_notification: bool | None = None, timeout: int | None = None, thumbnail: str |
Any | None = None, caption_entities: List[MessageEntity] | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None =
None, message_thread_id: int | None = None, thumb: str | Any | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None
= None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None =
None) → Message
Use this method to send audio files, if you want Telegram clients to display them in the music player. Your
audio must be in the .MP3 or .M4A format. On success, the sent Message is returned. Bots can currently
send audio files of up to 50 MB in size, this limit may be changed in the future.
For sending voice messages, use the send_voice method instead.
Telegram documentation: https://core.telegram.org/bots/api#sendaudio
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• audio (str or telebot.types.InputFile) – Audio file to send. Pass a file_id as String
to send an audio file that exists on the Telegram servers (recommended), pass an HTTP
URL as a String for Telegram to get an audio file from the Internet, or upload a new one
using multipart/form-data. Audio must be in the .MP3 or .M4A format.
• caption (str) – Audio caption, 0-1024 characters after entities parsing
• duration (int) – Duration of the audio in seconds
• performer (str) – Performer
• title (str) – Track name
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply)
• parse_mode (str) – Mode for parsing entities in the audio caption. See formatting options
for more details.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>

270 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized

list of special entities that appear in the caption, which can be specified instead of
parse_mode
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• thumb (str or telebot.types.InputFile) – Deprecated. Use thumbnail instead
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_chat_action(chat_id: int | str, action: str, timeout: int | None = None, message_thread_id:
int | None = None, business_connection_id: str | None = None) → bool
Use this method when you need to tell the user that something is happening on the bot’s side. The status is
set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).
Returns True on success.
Example: The ImageBot needs some time to process a request and upload the image. Instead of sending a
text message along the lines of “Retrieving image, please wait. . . ”, the bot may use sendChatAction with
action = upload_photo. The user will see a “sending photo” status for the bot.
Telegram documentation: https://core.telegram.org/bots/api#sendchataction
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• action (str) – Type of action to broadcast. Choose one, depending on what the user is
about to receive: typing for text messages, upload_photo for photos, record_video or up-
load_video for videos, record_voice or upload_voice for voice notes, upload_document for
general files, choose_sticker for stickers, find_location for location data, record_video_note
or upload_video_note for video notes.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – The thread to which the message will be sent(supergroups
only)
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent

1.3. Content 271

pyTelegramBotAPI, Release 4.25.0

Returns
Returns True on success.
Return type
bool
async send_contact(chat_id: int | str, phone_number: str, first_name: str, last_name: str | None = None,
vcard: str | None = None, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
timeout: int | None = None, allow_sending_without_reply: bool | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool |
None = None) → Message
Use this method to send phone contacts. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendcontact
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• phone_number (str) – Contact’s phone number
• first_name (str) – Contact’s first name
• last_name (str) – Contact’s last name
• vcard (str) – Additional data about the contact in the form of a vCard, 0-2048 bytes
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if one of the specified replied-to messages is
not found.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The thread to which the message will be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect

272 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_dice(chat_id: int | str, emoji: str | None = None, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout:
int | None = None, allow_sending_without_reply: bool | None = None, protect_content:
bool | None = None, message_thread_id: int | None = None, reply_parameters:
ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None) →
Message
Use this method to send an animated emoji that will display a random value. On success, the sent Message
is returned.
Telegram documentation: https://core.telegram.org/bots/api#senddice
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• emoji (str) – Emoji on which the dice throw animation is based. Currently, must be one
of “”, “”, “”, “”, “”, or “”. Dice can have values 1-6 for “”, “” and “”, values 1-5 for “” and
“”, and values 1-64 for “”. Defaults to “”
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
• message_thread_id (int) – The identifier of a message thread, unique within the chat
to which the message with the thread identifier belongs
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect

1.3. Content 273

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_document(chat_id: int | str, document: Any | str, reply_to_message_id: int | None = None,
caption: str | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
parse_mode: str | None = None, disable_notification: bool | None = None, timeout:
int | None = None, thumbnail: str | Any | None = None, caption_entities:
List[MessageEntity] | None = None, allow_sending_without_reply: bool | None =
None, visible_file_name: str | None = None, disable_content_type_detection: bool |
None = None, data: str | Any | None = None, protect_content: bool | None = None,
message_thread_id: int | None = None, thumb: str | Any | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool |
None = None) → Message
Use this method to send general files.
Telegram documentation: https://core.telegram.org/bots/api#senddocument
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• document (str or telebot.types.InputFile) – (document) File to send. Pass a file_id
as String to send a file that exists on the Telegram servers (recommended), pass an HTTP
URL as a String for Telegram to get a file from the Internet, or upload a new one using
multipart/form-data
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• caption (str) – Document caption (may also be used when resending documents by
file_id), 0-1024 characters after entities parsing
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• parse_mode (str) – Mode for parsing entities in the document caption
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – InputFile or String : Thumbnail of
the file sent; can be ignored if thumbnail generation for the file is supported server-side.
The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail’s width
and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-
data. Thumbnails can’t be reused and can be only uploaded as a new file, so you can

274 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-

data under <file_attach_name>
• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• visible_file_name (str) – allows to define file name that will be visible in the Telegram
instead of original file name
• disable_content_type_detection (bool) – Disables automatic server-side content
type detection for files uploaded using multipart/form-data
• data (str) – function typo miss compatibility: do not use it
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• thumb (str or telebot.types.InputFile) – Deprecated. Use thumbnail instead
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_game(chat_id: int | str, game_short_name: str, disable_notification: bool | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None, timeout:
int | None = None, allow_sending_without_reply: bool | None = None, protect_content:
bool | None = None, message_thread_id: int | None = None, reply_parameters:
ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None) →
Message
Used to send the game.
Telegram documentation: https://core.telegram.org/bots/api#sendgame
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• game_short_name (str) – Short name of the game, serves as the unique identifier for the
game. Set up your games via @BotFather.

1.3. Content 275

pyTelegramBotAPI, Release 4.25.0

• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (InlineKeyboardMarkup or ReplyKeyboardMarkup or
ReplyKeyboardRemove or ForceReply) – Additional interface options. A JSON-
serialized object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• timeout (int) – Timeout in seconds for waiting for a response from the bot.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if one of the specified replied-to messages is
not found.
• protect_content (bool) – Pass True, if content of the message needs to be protected
from being viewed by the bot.
• message_thread_id (int) – Identifier of the thread to which the message will be sent.
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of the business connection.
• message_effect_id (str) – Identifier of the message effect.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message
async send_gift(user_id: int, gift_id: str, text: str | None = None, text_parse_mode: str | None = None,
text_entities: List[MessageEntity] | None = None, pay_for_upgrade: bool | None =
None) → bool
Sends a gift to the given user. The gift can’t be converted to Telegram Stars by the user. Returns True on
success.
Telegram documentation: https://core.telegram.org/bots/api#sendgift
Parameters
• user_id (int) – Unique identifier of the target user that will receive the gift
• gift_id (str) – Identifier of the gift
• pay_for_upgrade (bool) – Pass True to pay for the gift upgrade from the bot’s balance,
thereby making the upgrade free for the receiver
• text (str) – Text that will be shown along with the gift; 0-255 characters
• text_parse_mode (str) – Mode for parsing entities in the text. See formatting options for
more details. Entities other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”,
and “custom_emoji” are ignored.
• text_entities (list of types.MessageEntity) – A JSON-serialized list of special
entities that appear in the gift text. It can be specified instead of text_parse_mode. Entities

276 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

other than “bold”, “italic”, “underline”, “strikethrough”, “spoiler”, and “custom_emoji”

are ignored.
Returns
Returns True on success.
Return type
bool
async send_invoice(chat_id: int | str, title: str, description: str, invoice_payload: str, provider_token: str
| None, currency: str, prices: List[LabeledPrice], start_parameter: 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, disable_notification: bool | None = None, reply_to_message_id: int | None =
None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, provider_data: str | None =
None, timeout: int | None = None, allow_sending_without_reply: bool | None = None,
max_tip_amount: int | None = None, suggested_tip_amounts: List[int] | None =
None, protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, message_effect_id: str | None =
None, allow_paid_broadcast: bool | None = None) → Message
Sends invoice.
Telegram documentation: https://core.telegram.org/bots/api#sendinvoice
Parameters
• chat_id (int or str) – Unique identifier for the target private chat
• title (str) – Product name, 1-32 characters
• description (str) – Product description, 1-255 characters
• invoice_payload (str) – Bot-defined invoice payload, 1-128 bytes. This will not be
displayed to the user, use for your internal processes.
• provider_token (str) – Payments provider token, obtained via @Botfather; Pass None
to omit the parameter to use “XTR” currency
• currency (str) – Three-letter ISO 4217 currency code, see https://core.telegram.org/
bots/payments#supported-currencies
• prices (List[types.LabeledPrice]) – Price breakdown, a list of components (e.g. prod-
uct price, tax, discount, delivery cost, delivery tax, bonus, etc.)
• start_parameter (str) – Unique deep-linking parameter that can be used to generate
this invoice when used as a start parameter
• photo_url (str) – URL of the product photo for the invoice. Can be a photo of the goods
or a marketing image for a service. People like it better when they see what they are paying
for.
• photo_size (int) – Photo size in bytes
• photo_width (int) – Photo width
• photo_height (int) – Photo height
• need_name (bool) – Pass True, if you require the user’s full name to complete the order

1.3. Content 277

pyTelegramBotAPI, Release 4.25.0

• need_phone_number (bool) – Pass True, if you require the user’s phone number to com-
plete the order
• need_email (bool) – Pass True, if you require the user’s email to complete the order
• need_shipping_address (bool) – Pass True, if you require the user’s shipping address
to complete the order
• is_flexible (bool) – Pass True, if the final price depends on the shipping method
• send_phone_number_to_provider (bool) – Pass True, if user’s phone number should
be sent to provider
• send_email_to_provider (bool) – Pass True, if user’s email address should be sent to
provider
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (str) – A JSON-serialized object for an inline keyboard. If empty, one
‘Pay total price’ button will be shown. If not empty, the first button must be a Pay button
• provider_data (str) – A JSON-serialized data about the invoice, which will be shared
with the payment provider. A detailed description of required fields should be provided by
the payment provider.
• timeout (int) – Timeout of a request, defaults to None
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• max_tip_amount (int) – The maximum accepted amount for tips in the smallest units of
the currency
• suggested_tip_amounts (list of int) – A JSON-serialized array of suggested
amounts of tips in the smallest units of the currency. At most 4 suggested tip amounts
can be specified. The suggested tip amounts must be positive, passed in a strictly increased
order and must not exceed max_tip_amount.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The identifier of a message thread, in which the invoice
message will be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• message_effect_id (str) – The identifier of a message effect to be applied to the mes-
sage
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message

278 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async send_location(chat_id: int | str, latitude: float, longitude: float, live_period: int | None = None,
reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
disable_notification: bool | None = None, timeout: int | None = None,
horizontal_accuracy: float | None = None, heading: int | None = None,
proximity_alert_radius: int | None = None, allow_sending_without_reply: bool |
None = None, protect_content: bool | None = None, message_thread_id: int | None
= None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send point on the map. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendlocation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• latitude (float) – Latitude of the location
• longitude (float) – Longitude of the location
• live_period (int) – Period in seconds during which the location will be updated (see
Live Locations, should be between 60 and 86400, or 0x7FFFFFFF for live locations that
can be edited indefinitely.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• horizontal_accuracy (float) – The radius of uncertainty for the location, measured
in meters; 0-1500
• heading (int) – For live locations, a direction in which the user is moving, in degrees.
Must be between 1 and 360 if specified.
• proximity_alert_radius (int) – For live locations, a maximum distance for proximity
alerts about approaching another chat member, in meters. Must be between 1 and 100000
if specified.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.

1.3. Content 279

pyTelegramBotAPI, Release 4.25.0

• business_connection_id (str) – Identifier of a business connection, in which the mes-

sage will be sent
• message_effect_id (str) – Unique identifier of the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_media_group(chat_id: int | str, media: List[InputMediaAudio | InputMediaDocument |
InputMediaPhoto | InputMediaVideo], disable_notification: bool | None = None,
protect_content: bool | None = None, reply_to_message_id: int | None = None,
timeout: int | None = None, allow_sending_without_reply: bool | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters |
None = None, business_connection_id: str | None = None, message_effect_id:
str | None = None, allow_paid_broadcast: bool | None = None) →
List[Message]
Use this method to send a group of photos, videos, documents or audios as an album. Documents and audio
files can be only grouped in an album with messages of the same type. On success, an array of Messages
that were sent is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendmediagroup
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• media (list of types.InputMedia) – A JSON-serialized array describing messages to
be sent, must include 2-10 items
• disable_notification (bool) – Sends the messages silently. Users will receive a no-
tification with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• timeout (int) – Timeout in seconds for the request.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• message_thread_id (int) – Identifier of a message thread, in which the messages will
be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect

280 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, an array of Messages that were sent is returned.
Return type
List[types.Message]
async send_message(chat_id: int | str, text: str, parse_mode: str | None = None, entities:
List[MessageEntity] | None = None, disable_web_page_preview: bool | None = None,
disable_notification: bool | None = None, protect_content: bool | None = None,
reply_to_message_id: int | None = None, allow_sending_without_reply: bool | None
= None, reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, timeout: int | None = None,
message_thread_id: int | None = None, reply_parameters: ReplyParameters | None =
None, link_preview_options: LinkPreviewOptions | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
allow_paid_broadcast: bool | None = None) → Message
Use this method to send text messages.
Warning: Do not send more than about 4096 characters each message, otherwise you’ll risk an HTTP 414
error. If you must send more than 4096 characters, use the split_string or smart_split function in util.py.
Telegram documentation: https://core.telegram.org/bots/api#sendmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• text (str) – Text of the message to be sent
• parse_mode (str) – Mode for parsing entities in the message text.
• entities (Array of telebot.types.MessageEntity) – List of special entities that ap-
pear in message text, which can be specified instead of parse_mode
• disable_web_page_preview (bool) – Deprecated - Use link_preview_options instead.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – If True, the message content will be hidden for all users except
for the target user
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.

1.3. Content 281

pyTelegramBotAPI, Release 4.25.0

• message_thread_id (int) – Unique identifier for the target message thread (topic) of the
forum; for forum supergroups only
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• link_preview_options (telebot.types.LinkPreviewOptions) – Options for pre-
viewing links.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_paid_media(chat_id: int | str, star_count: int, media: List[InputPaidMedia], caption: str |
None = None, parse_mode: str | None = None, caption_entities:
List[MessageEntity] | None = None, show_caption_above_media: bool | None =
None, disable_notification: bool | None = None, protect_content: bool | None =
None, reply_parameters: ReplyParameters | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, business_connection_id: str | None = None, payload:
str | None = None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send paid media to channel chats. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendpaidmedia
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• star_count (int) – The number of Telegram Stars that must be paid to buy access to the
media
• media (list of telebot.types.InputPaidMedia) – A JSON-serialized array describ-
ing the media to be sent; up to 10 items
• caption (str) – Media caption, 0-1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the media caption
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_parameters (telebot.types.ReplyParameters) – Description of the mes-
sage to reply to

282 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.

ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to
force a reply from the user
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• payload (str) – Bot-defined paid media payload, 0-128 bytes. This will not be displayed
to the user, use it for your internal processes.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_photo(chat_id: int | str, photo: Any | str, caption: str | None = None, parse_mode: str | None =
None, caption_entities: List[MessageEntity] | None = None, disable_notification: bool |
None = None, protect_content: bool | None = None, reply_to_message_id: int | None =
None, allow_sending_without_reply: bool | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply
| None = None, timeout: int | None = None, message_thread_id: int | None = None,
has_spoiler: bool | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
show_caption_above_media: bool | None = None, allow_paid_broadcast: bool | None =
None) → Message
Use this method to send photos. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendphoto
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• photo (str or telebot.types.InputFile) – Photo to send. Pass a file_id as String
to send a photo that exists on the Telegram servers (recommended), pass an HTTP URL
as a String for Telegram to get a photo from the Internet, or upload a new photo using
multipart/form-data. The photo must be at most 10 MB in size. The photo’s width and
height must not exceed 10000 in total. Width and height ratio must be at most 20.
• caption (str) – Photo caption (may also be used when resending photos by file_id), 0-
1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the photo caption.
• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving

1.3. Content 283

pyTelegramBotAPI, Release 4.25.0

• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-

sage is a reply, ID of the original message
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• has_spoiler (bool) – Pass True, if the photo should be sent as a spoiler
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_poll(chat_id: int | str, question: str, options: List[InputPollOption], is_anonymous: bool |
None = None, type: str | None = None, allows_multiple_answers: bool | None = None,
correct_option_id: int | None = None, explanation: str | None = None,
explanation_parse_mode: str | None = None, open_period: int | None = None,
close_date: int | datetime | None = None, is_closed: bool | None = None,
disable_notification: bool | None = False, reply_to_message_id: int | None = None,
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove
| ForceReply | None = None, allow_sending_without_reply: bool | None = None, timeout:
int | None = None, explanation_entities: List[MessageEntity] | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None =
None, question_parse_mode: str | None = None, question_entities: List[MessageEntity] |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None
= None) → Message
Use this method to send a native poll. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendpoll
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• question (str) – Poll question, 1-300 characters

284 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• options (list of InputPollOption) – A JSON-serialized list of 2-10 answer options

• is_anonymous (bool) – True, if the poll needs to be anonymous, defaults to True
• type (str) – Poll type, “quiz” or “regular”, defaults to “regular”
• allows_multiple_answers (bool) – True, if the poll allows multiple answers, ignored
for polls in quiz mode, defaults to False
• correct_option_id (int) – 0-based identifier of the correct answer option. Available
only for polls in quiz mode, defaults to None
• explanation (str) – Text that is shown when a user chooses an incorrect answer or taps
on the lamp icon in a quiz-style poll, 0-200 characters with at most 2 line feeds after entities
parsing
• explanation_parse_mode (str) – Mode for parsing entities in the explanation. See
formatting options for more details.
• open_period (int) – Amount of time in seconds the poll will be active after creation,
5-600. Can’t be used together with close_date.
• close_date (int | datetime) – Point in time (Unix timestamp) when the poll will be
automatically closed.
• is_closed (bool) – Pass True, if the poll needs to be immediately closed. This can be
useful for poll preview.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the poll allows multiple options to be voted simultaneously.
• reply_markup (InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply) – Additional interface options. A JSON-
serialized object for an inline keyboard, custom reply keyboard, instructions to remove
reply keyboard or to force a reply from the user.
• timeout (int) – Timeout in seconds for waiting for a response from the user.
• explanation_entities (list of MessageEntity) – A JSON-serialized list of special
entities that appear in the explanation, which can be specified instead of parse_mode
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The identifier of a message thread, in which the poll will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of the business connection to send the mes-
sage through
• question_parse_mode (str) – Mode for parsing entities in the question. See formatting
options for more details. Currently, only custom emoji entities are allowed
• question_entities (list of MessageEntity) – A JSON-serialized list of special en-
tities that appear in the poll question. It can be specified instead of question_parse_mode
• message_effect_id (str) – Identifier of the message effect to apply to the sent message

1.3. Content 285

pyTelegramBotAPI, Release 4.25.0

• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,

ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
types.Message
async send_sticker(chat_id: int | str, sticker: Any | str, reply_to_message_id: int | None = None,
reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup |
ReplyKeyboardRemove | ForceReply | None = None, disable_notification: bool |
None = None, timeout: int | None = None, allow_sending_without_reply: bool | None
= None, protect_content: bool | None = None, data: Any | str = None,
message_thread_id: int | None = None, emoji: str | None = None, reply_parameters:
ReplyParameters | None = None, business_connection_id: str | None = None,
message_effect_id: str | None = None, allow_paid_broadcast: bool | None = None)
→ Message
Use this method to send static .WEBP, animated .TGS, or video .WEBM stickers. On success, the sent
Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendsticker
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sticker (str or telebot.types.InputFile) – Sticker to send. Pass a file_id as String
to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as
a String for Telegram to get a .webp file from the Internet, or upload a new one using
multipart/form-data.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – to disable the notification
• timeout (int) – Timeout in seconds for the request.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• data (str) – function typo miss compatibility: do not use it
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• emoji (str) – Emoji associated with the sticker; only for just uploaded stickers
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.

286 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• business_connection_id (str) – Unique identifier for the target business connection

• message_effect_id (str) – Unique identifier for the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_venue(chat_id: int | str, latitude: float, longitude: float, title: str, address: str, foursquare_id:
str | None = None, foursquare_type: str | None = None, disable_notification: bool | None
= None, reply_to_message_id: int | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply
| None = None, timeout: int | None = None, allow_sending_without_reply: bool | None =
None, google_place_id: str | None = None, google_place_type: str | None = None,
protect_content: bool | None = None, message_thread_id: int | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str | None
= None, message_effect_id: str | None = None, allow_paid_broadcast: bool | None =
None) → Message
Use this method to send information about a venue. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendvenue
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel
• latitude (float) – Latitude of the venue
• longitude (float) – Longitude of the venue
• title (str) – Name of the venue
• address (str) – Address of the venue
• foursquare_id (str) – Foursquare identifier of the venue
• foursquare_type (str) – Foursquare type of the venue, if known. (For example,
“arts_entertainment/default”, “arts_entertainment/aquarium” or “food/icecream”.)
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if one of the specified replied-to messages is
not found.

1.3. Content 287

pyTelegramBotAPI, Release 4.25.0

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

• google_place_type (str) – Google Places type of the venue.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – The thread to which the message will be sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_video(chat_id: int | str, video: Any | str, duration: int | None = None, width: int | None =
None, height: int | None = None, thumbnail: str | Any | None = None, caption: str | None
= None, parse_mode: str | None = None, caption_entities: List[MessageEntity] | None
= None, supports_streaming: bool | None = None, disable_notification: bool | None =
None, protect_content: bool | None = None, reply_to_message_id: int | None = None,
allow_sending_without_reply: bool | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply
| None = None, timeout: int | None = None, data: str | Any | None = None,
message_thread_id: int | None = None, has_spoiler: bool | None = None, thumb: str |
Any | None = None, reply_parameters: ReplyParameters | None = None,
business_connection_id: str | None = None, message_effect_id: str | None = None,
show_caption_above_media: bool | None = None, allow_paid_broadcast: bool | None =
None) → Message
Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as
Document).
Telegram documentation: https://core.telegram.org/bots/api#sendvideo
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• video (str or telebot.types.InputFile) – Video to send. You can either pass a
file_id as String to resend a video that is already on the Telegram servers, or upload a new
video file using multipart/form-data.
• duration (int) – Duration of sent video in seconds
• width (int) – Video width
• height (int) – Video height
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.

288 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.
• caption (str) – Video caption (may also be used when resending videos by file_id), 0-
1024 characters after entities parsing
• parse_mode (str) – Mode for parsing entities in the video caption
• caption_entities (list of telebot.types.MessageEntity) – List of special enti-
ties that appear in the caption, which can be specified instead of parse_mode
• supports_streaming (bool) – Pass True, if the uploaded video is suitable for streaming
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• timeout (int) – Timeout in seconds for the request.
• data (str) – function typo miss compatibility: do not use it
• message_thread_id (int) – Identifier of a message thread, in which the video will be
sent
• has_spoiler (bool) – Pass True, if the video should be sent as a spoiler
• thumb (str or telebot.types.InputFile) – Deprecated. Use thumbnail instead
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect
• show_caption_above_media (bool) – Pass True, if the caption must be shown above
the message media. Supported only for animation, photo and video messages.
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message

1.3. Content 289

pyTelegramBotAPI, Release 4.25.0

async send_video_note(chat_id: int | str, data: Any | str, duration: int | None = None, length: int | None
= None, reply_to_message_id: int | None = None, reply_markup:
InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove |
ForceReply | None = None, disable_notification: bool | None = None, timeout: int
| None = None, thumbnail: str | Any | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None
= None, message_thread_id: int | None = None, thumb: str | Any | None = None,
reply_parameters: ReplyParameters | None = None, business_connection_id: str |
None = None, message_effect_id: str | None = None, allow_paid_broadcast: bool
| None = None) → Message
As of v.4.0, Telegram clients support rounded square MPEG4 videos of up to 1 minute long. Use this
method to send video messages. On success, the sent Message is returned.
Telegram documentation: https://core.telegram.org/bots/api#sendvideonote
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• data (str or telebot.types.InputFile) – Video note to send. Pass a file_id as String
to send a video note that exists on the Telegram servers (recommended) or upload a new
video using multipart/form-data. Sending video notes by a URL is currently unsupported
• duration (int) – Duration of sent video in seconds
• length (int) – Video width and height, i.e. diameter of the video message
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.
• timeout (int) – Timeout in seconds for the request.
• thumbnail (str or telebot.types.InputFile) – Thumbnail of the file sent; can
be ignored if thumbnail generation for the file is supported server-side. The thumbnail
should be in JPEG format and less than 200 kB in size. A thumbnail’s width and height
should not exceed 320. Ignored if the file is not uploaded using multipart/form-data.
Thumbnails can’t be reused and can be only uploaded as a new file, so you can pass “at-
tach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under
<file_attach_name>.
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the video note will
be sent
• thumb (str or telebot.types.InputFile) – Deprecated. Use thumbnail instead

290 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.

• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be sent
• message_effect_id (str) – Unique identifier of the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
Return type
telebot.types.Message
async send_voice(chat_id: int | str, voice: Any | str, caption: str | None = None, duration: int | None =
None, reply_to_message_id: int | None = None, reply_markup: InlineKeyboardMarkup |
ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None,
parse_mode: str | None = None, disable_notification: bool | None = None, timeout: int |
None = None, caption_entities: List[MessageEntity] | None = None,
allow_sending_without_reply: bool | None = None, protect_content: bool | None =
None, message_thread_id: int | None = None, reply_parameters: ReplyParameters |
None = None, business_connection_id: str | None = None, message_effect_id: str | None
= None, allow_paid_broadcast: bool | None = None) → Message
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice
message. For this to work, your audio must be in an .OGG file encoded with OPUS, or in .MP3 format,
or in .M4A format (other formats may be sent as Audio or Document). On success, the sent Message is
returned. Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the
future.
Telegram documentation: https://core.telegram.org/bots/api#sendvoice
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• voice (str or telebot.types.InputFile) – Audio file to send. Pass a file_id as String
to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a
String for Telegram to get a file from the Internet, or upload a new one using multipart/form-
data.
• caption (str) – Voice message caption, 0-1024 characters after entities parsing
• duration (int) – Duration of the voice message in seconds
• reply_to_message_id (int) – Deprecated - Use reply_parameters instead. If the mes-
sage is a reply, ID of the original message
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – Additional interface options. A JSON-serialized object for an
inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force
a reply from the user.
• parse_mode (str) – Mode for parsing entities in the voice message caption. See format-
ting options for more details.
• disable_notification (bool) – Sends the message silently. Users will receive a noti-
fication with no sound.

1.3. Content 291

pyTelegramBotAPI, Release 4.25.0

• timeout (int) – Timeout in seconds for the request.

• caption_entities (list of telebot.types.MessageEntity) – A JSON-serialized
list of special entities that appear in the caption, which can be specified instead of
parse_mode
• allow_sending_without_reply (bool) – Deprecated - Use reply_parameters instead.
Pass True, if the message should be sent even if the specified replied-to message is not
found
• protect_content (bool) – Protects the contents of the sent message from forwarding
and saving
• message_thread_id (int) – Identifier of a message thread, in which the message will be
sent
• reply_parameters (telebot.types.ReplyParameters) – Reply parameters.
• business_connection_id (str) – Unique identifier for the target business connection
• message_effect_id (str) – Unique identifier for the message effect
• allow_paid_broadcast (bool) – Pass True to allow up to 1000 messages per second,
ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars
will be withdrawn from the bot’s balance
Returns
On success, the sent Message is returned.
async set_chat_administrator_custom_title(chat_id: int | str, user_id: int, custom_title: str) →
bool
Use this method to set a custom title for an administrator in a supergroup promoted by the bot. Returns
True on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatadministratorcustomtitle
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• user_id (int) – Unique identifier of the target user
• custom_title (str) – New custom title for the administrator; 0-16 characters, emoji are
not allowed
Returns
True on success.
Return type
bool
async set_chat_description(chat_id: int | str, description: str | None = None) → bool
Use this method to change the description of a supergroup or a channel. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights.
Telegram documentation: https://core.telegram.org/bots/api#setchatdescription
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• description (str) – Str: New chat description, 0-255 characters

292 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
True on success.
Return type
bool
async set_chat_menu_button(chat_id: int | str = None, menu_button: MenuButton = None) → bool
Use this method to change the bot’s menu button in a private chat, or the default menu button. Returns True
on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatmenubutton
Parameters
• chat_id (int or str) – Unique identifier for the target private chat. If not specified,
default bot’s menu button will be changed.
• menu_button (telebot.types.MenuButton) – A JSON-serialized object for the new
bot’s menu button. Defaults to MenuButtonDefault
Returns
True on success.
Return type
bool
async set_chat_permissions(chat_id: int | str, permissions: ChatPermissions,
use_independent_chat_permissions: bool | None = None) → bool
Use this method to set default chat permissions for all members. The bot must be an administrator in the
group or a supergroup for this to work and must have the can_restrict_members admin rights.
Telegram documentation: https://core.telegram.org/bots/api#setchatpermissions
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• permissions (telebot.types..ChatPermissions) – New default chat permissions
• use_independent_chat_permissions (bool) – Pass True if chat permis-
sions are set independently. Otherwise, the can_send_other_messages and
can_add_web_page_previews permissions will imply the can_send_messages,
can_send_audios, can_send_documents, can_send_photos, can_send_videos,
can_send_video_notes, and can_send_voice_notes permissions; the can_send_polls
permission will imply the can_send_messages permission.
Returns
True on success
Return type
bool
async set_chat_photo(chat_id: int | str, photo: Any) → bool
Use this method to set a new profile photo for the chat. Photos can’t be changed for private chats. The bot
must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns
True on success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members
Are Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#setchatphoto
Parameters

1.3. Content 293

pyTelegramBotAPI, Release 4.25.0

• chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
• photo (typing.Union[file_like, str]) – InputFile: New chat photo, uploaded using
multipart/form-data
Returns
True on success.
Return type
bool
async set_chat_sticker_set(chat_id: int | str, sticker_set_name: str) → StickerSet
Use this method to 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 appropriate administrator rights. Use the field can_set_sticker_set
optionally returned in getChat requests to check if the bot can use this method. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setchatstickerset
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup (in the format @supergroupusername)
• sticker_set_name (str) – Name of the sticker set to be set as the group sticker set
Returns
StickerSet object
Return type
telebot.types.StickerSet
async set_chat_title(chat_id: int | str, title: str) → bool
Use this method to change the title of a chat. Titles can’t be changed for private chats. The bot must be
an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on
success. Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are
Admins’ setting is off in the target group.
Telegram documentation: https://core.telegram.org/bots/api#setchattitle
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• title (str) – New chat title, 1-255 characters
Returns
True on success.
Return type
bool
async set_custom_emoji_sticker_set_thumbnail(name: str, custom_emoji_id: str | None = None) →
bool
Use this method to set the thumbnail of a custom emoji sticker set. Returns True on success.
Parameters
• name (str) – Sticker set name
• custom_emoji_id (str) – Custom emoji identifier of a sticker from the sticker set; pass
an empty string to drop the thumbnail and use the first sticker as the thumbnail.

294 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
Returns True on success.
Return type
bool
async set_game_score(user_id: int | str, score: int, force: bool | None = None, chat_id: int | str | None =
None, message_id: int | None = None, inline_message_id: str | None = None,
disable_edit_message: bool | None = None) → Message | bool
Sets the value of points in the game to a specific user.
Telegram documentation: https://core.telegram.org/bots/api#setgamescore
Parameters
• user_id (int or str) – User identifier
• score (int) – New score, must be non-negative
• force (bool) – Pass True, if the high score is allowed to decrease. This can be useful
when fixing mistakes or banning cheaters
• chat_id (int or str) – Required if inline_message_id is not specified. Unique identifier
for the target chat or username of the target channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the sent
message
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message
• disable_edit_message (bool) – Pass True, if the game message should not be automat-
ically edited to include the current scoreboard
Returns
On success, if the message was sent by the bot, returns the edited Message, otherwise returns
True.
Return type
types.Message or bool
async set_message_reaction(chat_id: int | str, message_id: int, reaction: List[ReactionType] | None =
None, is_big: bool | None = None) → bool
Use this method to change the chosen reactions on a message. Service messages can’t be reacted to. Auto-
matically forwarded messages from a channel to its discussion group have the same available reactions as
messages in the channel. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmessagereaction
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
supergroup or channel (in the format @channelusername)
• message_id (int) – Identifier of the message to set reaction to
• reaction (list of telebot.types.ReactionType) – New list of reaction types to set
on the message. Currently, as non-premium users, bots can set up to one reaction per
message. A custom emoji reaction can be used if it is either already present on the message
or explicitly allowed by chat administrators.
• is_big (bool) – Pass True to set the reaction with a big animation

1.3. Content 295

pyTelegramBotAPI, Release 4.25.0

Returns
bool
async set_my_commands(commands: List[BotCommand], scope: BotCommandScope | None = None,
language_code: str | None = None) → bool
Use this method to change the list of the bot’s commands.
Telegram documentation: https://core.telegram.org/bots/api#setmycommands
Parameters
• commands (list of telebot.types.BotCommand) – List of BotCommand. At most 100
commands can be specified.
• scope (telebot.types.BotCommandScope) – The scope of users for which the com-
mands are relevant. Defaults to BotCommandScopeDefault.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, commands will
be applied to all users from the given scope, for whose language there are no dedicated
commands
Returns
True on success.
Return type
bool
async set_my_default_administrator_rights(rights: ChatAdministratorRights = None, for_channels:
bool = None) → bool
Use this method to change the default administrator rights requested by the bot when it’s added as an
administrator to groups or channels. These rights will be suggested to users, but they are are free to modify
the list before adding the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmydefaultadministratorrights
Parameters
• rights (telebot.types.ChatAdministratorRights) – A JSON-serialized object de-
scribing new default administrator rights. If not specified, the default administrator rights
will be cleared.
• for_channels (bool) – Pass True to change the default administrator rights of the bot in
channels. Otherwise, the default administrator rights of the bot for groups and supergroups
will be changed.
Returns
True on success.
Return type
bool
async set_my_description(description: str | None = None, language_code: str | None = None)
Use this method to change the bot’s description, which is shown in the chat with the bot if the chat is empty.
Returns True on success.
Parameters
• description (str) – New bot description; 0-512 characters. Pass an empty string to
remove the dedicated description for the given language.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, the description
will be applied to all users for whose language there is no dedicated description.

296 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Returns
True on success.
async set_my_name(name: str | None = None, language_code: str | None = None)
Use this method to change the bot’s name. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setmyname
Parameters
• name (str) – Optional. New bot name; 0-64 characters. Pass an empty string to remove
the dedicated name for the given language.
• language_code (str) – Optional. A two-letter ISO 639-1 language code. If empty, the
name will be shown to all users for whose language there is no dedicated name.
Returns
True on success.
async set_my_short_description(short_description: str | None = None, language_code: str | None =
None)
Use this method to change the bot’s short description, which is shown on the bot’s profile page and is sent
together with the link when users share the bot. Returns True on success.
Parameters
• short_description (str) – New short description for the bot; 0-120 characters. Pass
an empty string to remove the dedicated short description for the given language.
• language_code (str) – A two-letter ISO 639-1 language code. If empty, the short de-
scription will be applied to all users for whose language there is no dedicated short descrip-
tion.
Returns
True on success.
async set_state(user_id: int, state: int | str | State, chat_id: int | None = None, business_connection_id:
str | None = None, message_thread_id: int | None = None, bot_id: int | None = None) →
bool
Sets a new state of a user.

ò Note

You should set both user id and chat id in order to set state for a user in a chat. Otherwise, if you only
set user_id, chat_id will equal to user_id, this means that state will be set for the user in his private chat
with a bot.

Changed in version 4.23.0: Added additional parameters to support topics, business connections, and mes-
sage threads.

ã See also

For more details, visit the custom_states.py example.

Parameters
• user_id (int) – User’s identifier

1.3. Content 297

pyTelegramBotAPI, Release 4.25.0

• state (int or str or telebot.types.State) – new state. can be string, or telebot.

types.State
• chat_id (int) – Chat’s identifier
• bot_id (int) – Bot’s identifier, defaults to current bot id
• business_connection_id (str) – Business identifier
• message_thread_id (int) – Identifier of the message thread
Returns
True on success
Return type
bool

async set_sticker_emoji_list(name: str, emoji_list: List[str]) → bool

Use this method to set the emoji list of a sticker set. Returns True on success.
Parameters
• name (str) – Sticker set name
• emoji_list (list of str) – List of emojis
Returns
Returns True on success.
Return type
bool
async set_sticker_keywords(sticker: str, keywords: List[str] = None) → bool
Use this method to change search keywords assigned to a regular or custom emoji sticker. The sticker must
belong to a sticker set created by the bot. Returns True on success.
Parameters
• sticker (str) – File identifier of the sticker.
• keywords (list of str) – A JSON-serialized list of 0-20 search keywords for the sticker
with total length of up to 64 characters
Returns
On success, True is returned.
Return type
bool
async set_sticker_mask_position(sticker: str, mask_position: MaskPosition = None) → bool
Use this method to change the mask position of a mask sticker. The sticker must belong to a sticker set that
was created by the bot. Returns True on success.
Parameters
• sticker (str) – File identifier of the sticker.
• mask_position (telebot.types.MaskPosition) – A JSON-serialized object for po-
sition where the mask should be placed on faces.
Returns
Returns True on success.
Return type
bool

298 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

async set_sticker_position_in_set(sticker: str, position: int) → bool

Use this method to move a sticker in a set created by the bot to a specific position . Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setstickerpositioninset
Parameters
• sticker (str) – File identifier of the sticker
• position (int) – New sticker position in the set, zero-based
Returns
On success, True is returned.
Return type
bool
set_sticker_set_thumb(**kwargs)

async set_sticker_set_thumbnail(name: str, user_id: int, thumbnail: Any | str = None, format: str |
None = None) → bool
Use this method to set the thumbnail of a sticker set. Animated thumbnails can be set for animated sticker
sets only. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#setstickersetthumbnail
Parameters
• name (str) – Sticker set name
• user_id (int) – User identifier
• thumbnail (filelike object) – A .WEBP or .PNG image with the thumbnail, must be
up to 128 kilobytes in size and have a width and height of exactly 100px, or a .TGS ani-
mation with a thumbnail up to 32 kilobytes in size (see https://core.telegram.org/stickers#
animated-sticker-requirements for animated sticker technical requirements), or a WEBM
video with the thumbnail up to 32 kilobytes in size; see https://core.telegram.org/stickers#
video-sticker-requirements for video sticker technical requirements. Pass a file_id as a
String to send a file that already exists on the Telegram servers, pass an HTTP URL as a
String for Telegram to get a file from the Internet, or upload a new one using multipart/form-
data. More information on Sending Files ». Animated and video sticker set thumbnails
can’t be uploaded via HTTP URL. If omitted, then the thumbnail is dropped and the first
sticker is used as the thumbnail.
Returns
On success, True is returned.
Return type
bool
async set_sticker_set_title(name: str, title: str) → bool
Use this method to set the title of a created sticker set. Returns True on success.
Parameters
• name (str) – Sticker set name
• title (str) – New sticker set title
Returns
Returns True on success.

1.3. Content 299

pyTelegramBotAPI, Release 4.25.0

Return type
bool
set_update_listener(func: Awaitable)
Update listener is a function that gets any update.
Parameters
func (Awaitable) – function that should get update.

Listing 27: Example on asynchronous update listeners.

async def update_listener(new_messages):
for message in new_messages:
print(message.text) # Prints message text

bot.set_update_listener(update_listener)

Returns
None

async set_user_emoji_status(user_id: int, emoji_status_custom_emoji_id: str | None = None,

emoji_status_expiration_date: int | None = None) → bool
Use this method to change the emoji status for a given user that previously allowed the bot to manage their
emoji status via the Mini App method requestEmojiStatusAccess.
Telegram documentation: https://core.telegram.org/bots/api#setuseremojistatus
Parameters
• user_id (int) – Unique identifier of the target user
• emoji_status_custom_emoji_id (str, optional) – Custom emoji identifier of the emoji
status to set. Pass an empty string to remove the status.
• emoji_status_expiration_date (int, optional) – Expiration date of the emoji status,
if any
Returns
bool
async set_webhook(url: str | None = None, certificate: str | Any | None = None, max_connections: int |
None = None, allowed_updates: List[str] | None = None, ip_address: str | None =
None, drop_pending_updates: bool | None = None, timeout: int | None = None,
secret_token: str | None = None) → bool
Use this method to specify a URL and receive incoming updates via an outgoing webhook. Whenever
there is an update for the bot, we will send an HTTPS POST request to the specified URL, containing a
JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of
attempts. Returns True on success.
If you’d like to make sure that the webhook was set by you, you can specify secret data in the parameter
secret_token. If specified, the request will contain a header “X-Telegram-Bot-Api-Secret-Token” with the
secret token as content.
Telegram Documentation: https://core.telegram.org/bots/api#setwebhook
Parameters
• url (str, optional) – HTTPS URL to send updates to. Use an empty string to remove
webhook integration, defaults to None

300 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• certificate (str, optional) – Upload your public key certificate so that the root certifi-
cate in use can be checked, defaults to None
• max_connections (int, optional) – The maximum allowed number of simultaneous
HTTPS connections to the webhook for update delivery, 1-100. Defaults to 40. Use
lower values to limit the load on your bot’s server, and higher values to increase your bot’s
throughput, defaults to None
• allowed_updates (list, optional) – A JSON-serialized list of the update types you
want your bot to receive. For example, specify [“message”, “edited_channel_post”, “call-
back_query”] to only receive updates of these types. See Update for a complete list of avail-
able update types. Specify an empty list to receive all update types except chat_member
(default). If not specified, the previous setting will be used.
Please note that this parameter doesn’t affect updates created before the call to the setWeb-
hook, so unwanted updates may be received for a short period of time. Defaults to None
• ip_address (str, optional) – The fixed IP address which will be used to send webhook
requests instead of the IP address resolved through DNS, defaults to None
• drop_pending_updates (bool, optional) – Pass True to drop all pending updates, de-
faults to None
• timeout (int, optional) – Timeout of a request, defaults to None
• secret_token (str, optional) – A secret token to be sent in a header “X-Telegram-Bot-
Api-Secret-Token” in every webhook request, 1-256 characters. Only characters A-Z, a-z,
0-9, _ and - are allowed. The header is useful to ensure that the request comes from a
webhook set by you. Defaults to None
Returns
True on success.
Return type
bool if the request was successful.
setup_middleware(middleware: BaseMiddleware)
Setup middleware.

ò Note

Take a look at the telebot.asyncio_handler_backends.BaseMiddleware section for more.

Parameters
middleware (telebot.asyncio_handler_backends.BaseMiddleware) – Middleware-
class.
Returns
None

shipping_query_handler(func, **kwargs)
Handles new incoming shipping query. Only for invoices with flexible price. As a parameter to the decorator
function, it passes telebot.types.ShippingQuery object.
Parameters
• func (function) – Function executed as a filter
• kwargs – Optional keyword arguments(custom filters)

1.3. Content 301

pyTelegramBotAPI, Release 4.25.0

Returns
None
async skip_updates()
Skip existing updates. Only last update will remain on server.
async stop_message_live_location(chat_id: int | str | None = None, message_id: int | None = None,
inline_message_id: str | None = None, reply_markup:
InlineKeyboardMarkup | None = None, timeout: int | None = None,
business_connection_id: str | None = None) → Message
Use this method to stop updating a live location message before live_period expires. On success, if the
message is not an inline message, the edited Message is returned, otherwise True is returned.
Telegram documentation: https://core.telegram.org/bots/api#stopmessagelivelocation
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Required if inline_message_id is not specified. Identifier of the mes-
sage with live location to stop
• inline_message_id (str) – Required if chat_id and message_id are not specified. Iden-
tifier of the inline message with live location to stop
• reply_markup (telebot.types.InlineKeyboardMarkup or telebot.types.
ReplyKeyboardMarkup or telebot.types.ReplyKeyboardRemove or telebot.
types.ForceReply) – A JSON-serialized object for a new inline keyboard.
• timeout (int) – Timeout in seconds for the request.
• business_connection_id (str) – Identifier of a business connection, in which the mes-
sage will be edited
Returns
On success, if the message is not an inline message, the edited Message is returned, otherwise
True is returned.
Return type
telebot.types.Message or bool
async stop_poll(chat_id: int | str, message_id: int, reply_markup: InlineKeyboardMarkup | None = None,
business_connection_id: str | None = None) → Poll
Use this method to stop a poll which was sent by the bot. On success, the stopped Poll is returned.
Telegram documentation: https://core.telegram.org/bots/api#stoppoll
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
• message_id (int) – Identifier of the original message with the poll
• reply_markup (InlineKeyboardMarkup) – A JSON-serialized object for a new message
markup.
• business_connection_id (str) – Identifier of the business connection to send the mes-
sage through
Returns
On success, the stopped Poll is returned.

302 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
types.Poll
async unban_chat_member(chat_id: int | str, user_id: int, only_if_banned: bool | None = False) → bool
Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to
the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator
for this to work. By default, this method guarantees that after the call the user is not a member of the chat,
but will be able to join it. So if the user is a member of the chat they will also be removed from the chat. If
you don’t want this, use the parameter only_if_banned.
Telegram documentation: https://core.telegram.org/bots/api#unbanchatmember
Parameters
• chat_id (int or str) – Unique identifier for the target group or username of the target
supergroup or channel (in the format @username)
• user_id (int) – Unique identifier of the target user
• only_if_banned (bool) – Do nothing if the user is not banned
Returns
True on success
Return type
bool
async unban_chat_sender_chat(chat_id: int | str, sender_chat_id: int | str) → bool
Use this method to unban a previously banned channel chat in a supergroup or channel. The bot must be an
administrator for this to work and must have the appropriate administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unbanchatsenderchat
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• sender_chat_id (int or str) – Unique identifier of the target sender chat.
Returns
True on success.
Return type
bool
async unhide_general_forum_topic(chat_id: int | str) → bool
Use this method to unhide the ‘General’ topic in a forum supergroup chat. The bot must be an administrator
in the chat for this to work and must have can_manage_topics administrator rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unhidegeneralforumtopic
Parameters
chat_id (int or str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
async unpin_all_chat_messages(chat_id: int | str) → bool
Use this method to unpin a all pinned messages in a supergroup chat. The bot must be an administrator in
the chat for this to work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinallchatmessages

1.3. Content 303

pyTelegramBotAPI, Release 4.25.0

Parameters
chat_id (int or str) – Int or Str: Unique identifier for the target chat or username of the
target channel (in the format @channelusername)
Returns
True on success.
Return type
bool
async unpin_all_forum_topic_messages(chat_id: str | int, message_thread_id: int) → bool
Use this method to clear the list of pinned messages in a forum topic. The bot must be an administrator
in the chat for this to work and must have the can_pin_messages administrator right in the supergroup.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinallforumtopicmessages
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_thread_id (int) – Identifier of the topic
Returns
On success, True is returned.
Return type
bool
async unpin_all_general_forum_topic_messages(chat_id: int | str) → bool
Use this method to clear the list of pinned messages in a General forum topic. The bot must be an adminis-
trator in the chat for this to work and must have the can_pin_messages administrator right in the supergroup.
Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinAllGeneralForumTopicMessages
Parameters
chat_id (int | str) – Unique identifier for the target chat or username of chat
Returns
On success, True is returned.
Return type
bool
async unpin_chat_message(chat_id: int | str, message_id: int | None = None, business_connection_id: str
| None = None) → bool
Use this method to unpin specific pinned message in a supergroup chat. The bot must be an administrator
in the chat for this to work and must have the appropriate admin rights. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#unpinchatmessage
Parameters
• chat_id (int or str) – Unique identifier for the target chat or username of the target
channel (in the format @channelusername)
• message_id (int) – Int: Identifier of a message to unpin
• business_connection_id (str) – Unique identifier of the business connection
Returns
True on success.

304 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
bool
async upload_sticker_file(user_id: int, png_sticker: Any | str = None, sticker: InputFile | None = None,
sticker_format: str | None = None) → File
Use this method to upload a .png file with a sticker for later use in createNewStickerSet and addStickerToSet
methods (can be used multiple times). Returns the uploaded File on success.
Telegram documentation: https://core.telegram.org/bots/api#uploadstickerfile
Parameters
• user_id (int) – User identifier of sticker set owner
• png_sticker (filelike object) – DEPRECATED: PNG image with the sticker, must
be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or
height must be exactly 512px.
• sticker (telebot.types.InputFile) – A file with the sticker in .WEBP, .PNG, .TGS,
or .WEBM format. See https://core.telegram.org/stickers for technical requirements. More
information on Sending Files »
• sticker_format (str) – One of “static”, “animated”, “video”.
Returns
On success, the sent file is returned.
Return type
telebot.types.File
property user

async verify_chat(chat_id: int | str, custom_description: str | None = None) → bool

Verifies a chat on behalf of the organization which is represented by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#verifychat
Parameters
• chat_id (int | str) – Unique identifier for the target chat or username of the target channel
(in the format @channelusername)
• custom_description (str) – Custom description for the verification; 0-70 characters.
Must be empty if the organization isn’t allowed to provide a custom verification description.
Returns
Returns True on success.
Return type
bool
async verify_user(user_id: int, custom_description: str | None = None) → bool
Verifies a user on behalf of the organization which is represented by the bot. Returns True on success.
Telegram documentation: https://core.telegram.org/bots/api#verifyuser
Parameters
• user_id (int) – Unique identifier of the target user
• custom_description (str) – Custom description for the verification; 0-70 characters.
Must be empty if the organization isn’t allowed to provide a custom verification description.

1.3. Content 305

pyTelegramBotAPI, Release 4.25.0

Returns
Returns True on success.
Return type
bool
class telebot.async_telebot.ExceptionHandler
Bases: object
Class for handling exceptions while Polling
async handle(exception)

class telebot.async_telebot.Handler(callback, *args, **kwargs)

Bases: object
Class for (next step|reply) handlers

Asyncio filters
class telebot.asyncio_filters.AdvancedCustomFilter
Bases: ABC
Advanced Custom Filter base class. Create child class with check() method. Accepts two parameters, returns
bool: True - filter passed, False - filter failed. message: Message class text: Filter value given in handler
Child classes should have .key property.

Listing 28: Example on creating an advanced custom filter.

class TextStartsFilter(AdvancedCustomFilter):
# Filter to check whether message starts with some text.
key = 'text_startswith'

def check(self, message, text):

return message.text.startswith(text)

async check(message, text)

Perform a check.
key: str = None

class telebot.asyncio_filters.ChatFilter
Bases: AdvancedCustomFilter
Check whether chat_id corresponds to given chat_id.

Listing 29: Example on using this filter:

@bot.message_handler(chat_id=[99999])
# your function

key: str = 'chat_id'

class telebot.asyncio_filters.ForwardFilter
Bases: SimpleCustomFilter
Check whether message was forwarded from channel or group.

306 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Listing 30: Example on using this filter:

@bot.message_handler(is_forwarded=True)
# your function

key: str = 'is_forwarded'

class telebot.asyncio_filters.IsAdminFilter(bot)
Bases: SimpleCustomFilter
Check whether the user is administrator / owner of the chat.

Listing 31: Example on using this filter:

@bot.message_handler(chat_types=['supergroup'], is_chat_admin=True)
# your function

key: str = 'is_chat_admin'

class telebot.asyncio_filters.IsDigitFilter
Bases: SimpleCustomFilter
Filter to check whether the string is made up of only digits.

Listing 32: Example on using this filter:

@bot.message_handler(is_digit=True)
# your function

key: str = 'is_digit'

class telebot.asyncio_filters.IsReplyFilter
Bases: SimpleCustomFilter
Check whether message is a reply.

Listing 33: Example on using this filter:

@bot.message_handler(is_reply=True)
# your function

key: str = 'is_reply'

class telebot.asyncio_filters.LanguageFilter
Bases: AdvancedCustomFilter
Check users language_code.

Listing 34: Example on using this filter:

@bot.message_handler(language_code=['ru'])
# your function

key: str = 'language_code'

1.3. Content 307

pyTelegramBotAPI, Release 4.25.0

class telebot.asyncio_filters.SimpleCustomFilter
Bases: ABC
Simple Custom Filter base class. Create child class with check() method. Accepts only message, returns bool
value, that is compared with given in handler.
Child classes should have .key property.

Listing 35: Example on creating a simple custom filter.

class ForwardFilter(SimpleCustomFilter):
# Check whether message was forwarded from channel or group.
key = 'is_forwarded'

def check(self, message):

return message.forward_date is not None

async check(message) → bool

Perform a check.
key: str = None

class telebot.asyncio_filters.StateFilter(bot)
Bases: AdvancedCustomFilter
Filter to check state.

Listing 36: Example on using this filter:

@bot.message_handler(state=1)
# your function

key: str = 'state'

class telebot.asyncio_filters.TextContainsFilter
Bases: AdvancedCustomFilter
Filter to check Text message. key: text

Listing 37: Example on using this filter:

# Will respond if any message.text contains word 'account'
@bot.message_handler(text_contains=['account'])
# your function

key: str = 'text_contains'

class telebot.asyncio_filters.TextFilter(equals: str | None = None, contains: list | tuple | None = None,
starts_with: str | list | tuple | None = None, ends_with: str | list
| tuple | None = None, ignore_case: bool = False)
Bases: object
Advanced text filter to check (types.Message, types.CallbackQuery, types.InlineQuery, types.Poll)
example of usage is in examples/asynchronous_telebot/custom_filters/advanced_text_filter.py
Parameters
• equals (str) – string, True if object’s text is equal to passed string

308 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• contains (list[str] or tuple[str]) – list[str] or tuple[str], True if any string element

of iterable is in text
• starts_with (str) – string, True if object’s text starts with passed string
• ends_with (str) – string, True if object’s text starts with passed string
• ignore_case (bool) – bool (default False), case insensitive
Raises
ValueError – if incorrect value for a parameter was supplied
Returns
None
class telebot.asyncio_filters.TextMatchFilter
Bases: AdvancedCustomFilter
Filter to check Text message.

Listing 38: Example on using this filter:

@bot.message_handler(text=['account'])
# your function

key: str = 'text'

class telebot.asyncio_filters.TextStartsFilter
Bases: AdvancedCustomFilter
Filter to check whether message starts with some text.

Listing 39: Example on using this filter:

# Will work if message.text starts with 'sir'.
@bot.message_handler(text_startswith='sir')
# your function

key: str = 'text_startswith'

Asyncio handler backends

File with all middleware classes, states.
class telebot.asyncio_handler_backends.BaseMiddleware
Bases: object
Base class for middleware. Your middlewares should be inherited from this class.
Set update_sensitive=True if you want to get different updates on different functions. For example, if you want
to handle pre_process for message update, then you will have to create pre_process_message function, and so
on. Same applies to post_process.

Listing 40: Example of class-based middlewares

class MyMiddleware(BaseMiddleware):
def __init__(self):
self.update_sensitive = True
self.update_types = ['message', 'edited_message']
(continues on next page)

1.3. Content 309

pyTelegramBotAPI, Release 4.25.0

(continued from previous page)

async def pre_process_message(self, message, data):

# only message update here
pass

async def post_process_message(self, message, data, exception):

pass # only message update here for post_process

async def pre_process_edited_message(self, message, data):

# only edited_message update here
pass

async def post_process_edited_message(self, message, data, exception):

pass # only edited_message update here for post_process

async post_process(message, data, exception)

async pre_process(message, data)

update_sensitive: bool = False

class telebot.asyncio_handler_backends.CancelUpdate
Bases: object
Class for canceling updates. Just return instance of this class in middleware to skip update. Update will skip
handler and execution of post_process in middlewares.
class telebot.asyncio_handler_backends.ContinueHandling
Bases: object
Class for continue updates in handlers. Just return instance of this class in handlers to continue process.

Listing 41: Example of using ContinueHandling

@bot.message_handler(commands=['start'])
async def start(message):
await bot.send_message(message.chat.id, 'Hello World!')
return ContinueHandling()

@bot.message_handler(commands=['start'])
async def start2(message):
await bot.send_message(message.chat.id, 'Hello World2!')

class telebot.asyncio_handler_backends.SkipHandler
Bases: object
Class for skipping handlers. Just return instance of this class in middleware to skip handler. Update will go to
post_process, but will skip execution of handler.

Extensions

1.3.6 Callback data factory

callback_data file
Callback data factory’s file.

310 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

class telebot.callback_data.CallbackData(*parts, prefix: str, sep=':')

Bases: object
Callback data factory This class will help you to work with CallbackQuery
filter(**config) → CallbackDataFilter
Generate filter
Parameters
config – specified named parameters will be checked with CallbackQuery.data
Returns
CallbackDataFilter class
new(*args, **kwargs) → str
Generate callback data
Parameters
• args – positional parameters of CallbackData instance parts
• kwargs – named parameters
Returns
str
parse(callback_data: str) → Dict[str, str]
Parse data from the callback data
Parameters
callback_data – string, use to telebot.types.CallbackQuery to parse it from string to a dict
Returns
dict parsed from callback data
class telebot.callback_data.CallbackDataFilter(factory, config: Dict[str, str])
Bases: object
Filter for CallbackData.
check(query) → bool
Checks if query.data appropriates to specified config
Parameters
query (telebot.types.CallbackQuery) – telebot.types.CallbackQuery
Returns
True if query.data appropriates to specified config
Return type
bool

1.3.7 Utils
util file
telebot.util.antiflood(function: Callable, *args, number_retries=5, **kwargs)
Use this function inside loops in order to avoid getting TooManyRequests error. Example:

from telebot.util import antiflood

for chat_id in chat_id_list:
msg = antiflood(bot.send_message, chat_id, text)

1.3. Content 311

pyTelegramBotAPI, Release 4.25.0

Parameters
• function (:obj:int) – The function to call
• number_retries – Number of retries to send
• args (tuple) – The arguments to pass to the function
• kwargs (dict) – The keyword arguments to pass to the function
Returns
None

telebot.util.chunks(lst, n)
Yield successive n-sized chunks from lst.
telebot.util.content_type_media = ['text', 'animation', 'audio', 'document', 'photo',
'sticker', 'story', 'video', 'video_note', 'voice', 'contact', 'dice', 'game', 'poll',
'venue', 'location', 'invoice', 'successful_payment', 'connected_website',
'passport_data', 'web_app_data']
Contains all media content types.
telebot.util.content_type_service = ['new_chat_members', 'left_chat_member',
'new_chat_title', 'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
'supergroup_chat_created', 'channel_chat_created', 'message_auto_delete_timer_changed',
'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message', 'users_shared',
'chat_shared', 'write_access_allowed', 'proximity_alert_triggered',
'forum_topic_created', 'forum_topic_edited', 'forum_topic_closed',
'forum_topic_reopened', 'general_forum_topic_hidden', 'general_forum_topic_unhidden',
'giveaway_created', 'giveaway', 'giveaway_winners', 'giveaway_completed',
'video_chat_scheduled', 'video_chat_started', 'video_chat_ended',
'video_chat_participants_invited']
Contains all service content types such as User joined the group.
telebot.util.escape(text: str) → str | None
Replaces the following chars in text (’&’ with ‘&amp;’, ‘<’ with ‘&lt;’ and ‘>’ with ‘&gt;’).
Parameters
text – the text to escape
Returns
the escaped text
telebot.util.extract_arguments(text: str) → str
Returns the argument after the command.

Listing 42: Examples:

extract_arguments("/get name"): 'name'
extract_arguments("/get"): ''
extract_arguments("/get@botName name"): 'name'

Parameters
text (str) – String to extract the arguments from a command
Returns
the arguments if text is a command (according to is_command), else None.

312 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
str or None

telebot.util.extract_bot_id(token) → int | None

telebot.util.extract_command(text: str) → str | None

Extracts the command from text (minus the ‘/’) if text is a command (see is_command). If text is not a command,
this function returns None.

Listing 43: Examples:

extract_command('/help'): 'help'
extract_command('/help@BotName'): 'help'
extract_command('/search black eyed peas'): 'search'
extract_command('Good day to you'): None

Parameters
text (str) – String to extract the command from
Returns
the command if text is a command (according to is_command), else None.
Return type
str or None

telebot.util.generate_random_token() → str
Generates a random token consisting of letters and digits, 16 characters long.
Returns
a random token
Return type
str
telebot.util.is_bytes(var) → bool
Returns True if the given object is a bytes object.
Parameters
var (object) – object to be checked
Returns
True if the given object is a bytes object.
Return type
bool
telebot.util.is_command(text: str) → bool
Checks if text is a command. Telegram chat commands start with the ‘/’ character.
Parameters
text (str) – Text to check.
Returns
True if text is a command, else False.
Return type
bool

1.3. Content 313

pyTelegramBotAPI, Release 4.25.0

telebot.util.is_dict(var) → bool
Returns True if the given object is a dictionary.
Parameters
var (object) – object to be checked
Returns
True if the given object is a dictionary.
Return type
bool
telebot.util.is_pil_image(var) → bool
Returns True if the given object is a PIL.Image.Image object.
Parameters
var (object) – object to be checked
Returns
True if the given object is a PIL.Image.Image object.
Return type
bool
telebot.util.is_string(var) → bool
Returns True if the given object is a string.
telebot.util.parse_web_app_data(token: str, raw_init_data: str)
Parses web app data.
Parameters
• token (str) – The bot token
• raw_init_data (str) – The raw init data
Returns
The parsed init data
telebot.util.pil_image_to_file(image, extension='JPEG', quality='web_low')

telebot.util.quick_markup(values: Dict[str, Dict[str, Any]], row_width: int = 2) → InlineKeyboardMarkup

Returns a reply markup from a dict in this format: {‘text’: kwargs} This is useful to avoid always typing ‘btn1 =
InlineKeyboardButton(. . . )’ ‘btn2 = InlineKeyboardButton(. . . )’
Example:

Listing 44: Using quick_markup:

from telebot.util import quick_markup

markup = quick_markup({
'Twitter': {'url': 'https://twitter.com'},
'Facebook': {'url': 'https://facebook.com'},
'Back': {'callback_data': 'whatever'}
}, row_width=2)
# returns an InlineKeyboardMarkup with two buttons in a row, one leading to Twitter,
˓→ the other to facebook

# and a back button below

(continues on next page)

314 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

(continued from previous page)

# kwargs can be:
{
'url': None,
'callback_data': None,
'switch_inline_query': None,
'switch_inline_query_current_chat': None,
'callback_game': None,
'pay': None,
'login_url': None,
'web_app': None
}

Parameters
• values (dict) – a dict containing all buttons to create in this format: {text: kwargs} {str:}
• row_width (int) – number of telebot.types.InlineKeyboardButton objects on each
row
Returns
InlineKeyboardMarkup
Return type
types.InlineKeyboardMarkup

telebot.util.smart_split(text: str, chars_per_string: int = 4096) → List[str]

Splits one string into multiple strings, with a maximum amount of chars_per_string characters per string. This
is very useful for splitting one giant message into multiples. If chars_per_string > 4096: chars_per_string =
4096. Splits by ‘n’, ‘. ‘ or ‘ ‘ in exactly this priority.
Parameters
• text (str) – The text to split
• chars_per_string (int) – The number of maximum characters per part the text is split
to.
Returns
The splitted text as a list of strings.
Return type
list of str
telebot.util.split_string(text: str, chars_per_string: int) → List[str]
Splits one string into multiple strings, with a maximum amount of chars_per_string characters per string. This
is very useful for splitting one giant message into multiples.
Parameters
• text (str) – The text to split
• chars_per_string (int) – The number of characters per line the text is split into.
Returns
The splitted text as a list of strings.
Return type
list of str

1.3. Content 315

pyTelegramBotAPI, Release 4.25.0

telebot.util.update_types = ['message', 'edited_message', 'channel_post',

'edited_channel_post', 'inline_query', 'chosen_inline_result', 'callback_query',
'shipping_query', 'pre_checkout_query', 'poll', 'poll_answer', 'my_chat_member',
'chat_member', 'chat_join_request', 'message_reaction', 'message_reaction_count',
'chat_boost', 'removed_chat_boost', 'business_connection', 'business_message',
'edited_business_message', 'deleted_business_messages', 'purchased_paid_media']
All update types, should be used for allowed_updates parameter in polling.
telebot.util.user_link(user: User, include_id: bool = False) → str
Returns an HTML user link. This is useful for reports. Attention: Don’t forget to set parse_mode to ‘HTML’!

Listing 45: Example:

bot.send_message(your_user_id, user_link(message.from_user) + ' started the bot!',␣
˓→parse_mode='HTML')

ò Note

You can use formatting.* for all other formatting options(bold, italic, links, and etc.) This method is kept for
backward compatibility, and it is recommended to use formatting.* for more options.

Parameters
• user (telebot.types.User) – the user (not the user_id)
• include_id (bool) – include the user_id
Returns
HTML user link
Return type
str

telebot.util.validate_token(token) → bool

telebot.util.validate_web_app_data(token: str, raw_init_data: str)

Validates web app data.
Parameters
• token (str) – The bot token
• raw_init_data (str) – The raw init data
Returns
The parsed init data
telebot.util.webhook_google_functions(bot, request)
A webhook endpoint for Google Cloud Functions FaaS.
Parameters
• bot (telebot.TeleBot or telebot.async_telebot.AsyncTeleBot) – The bot in-
stance
• request (flask.Request) – The request object
Returns
The response object

316 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

1.3.8 Formatting options

Markdown & HTML formatting functions.
Added in version 4.5.1.
telebot.formatting.apply_html_entities(text: str, entities: List | None, custom_subs: Dict[str, str] | None)
→ str
Author: @sviat9440 Updaters: @badiboy, @EgorKhabarov Message: “Test parse _formatting_, [url](https:
//example.com), [text_mention](tg://user?id=123456) and mention @username”

Listing 46: Example:

apply_html_entities(text, entities)
>> "<b>Test</b> parse <i>formatting</i>, <a href="https://example.com">url</a>, <a␣
˓→href="tg://user?id=123456">text_mention</a> and mention @username"

Custom subs:
You can customize the substitutes. By default, there is no substitute for the entities: hashtag, bot_command,
email. You can add or modify substitute an existing entity.

Listing 47: Example:

apply_html_entities(
text,
entities,
{"bold": "<strong class="example">{text}</strong>", "italic": "<i class="example
˓→">{text}</i>", "mention": "<a href={url}>{text}</a>"},

)
>> "<strong class="example">Test</strong> parse <i class="example">formatting</i>,
˓→<a href="https://example.com">url</a> and <a href="tg://user?id=123456">text_

˓→mention</a> and mention <a href="https://t.me/username">@username</a>"

telebot.formatting.escape_html(content: str) → str

Escapes HTML characters in a string of HTML.
Parameters
content (str) – The string of HTML to escape.
Returns
The escaped string.
Return type
str
telebot.formatting.escape_markdown(content: str) → str
Escapes Markdown characters in a string of Markdown.
Credits to: simonsmh
Parameters
content (str) – The string of Markdown to escape.
Returns
The escaped string.
Return type
str

1.3. Content 317

pyTelegramBotAPI, Release 4.25.0

telebot.formatting.format_text(*args, separator='\n')
Formats a list of strings into a single string.

format_text( # just an example

mbold('Hello'),
mitalic('World')
)

Parameters
• args (str) – Strings to format.
• separator (str) – The separator to use between each string.
Returns
The formatted string.
Return type
str

telebot.formatting.hbold(content: str, escape: bool | None = True) → str

Returns an HTML-formatted bold string.
Parameters
• content (str) – The string to bold.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.hcite(content: str, escape: bool | None = True, expandable: bool | None = False) → str
Returns a html-formatted block-quotation string.
Parameters
• content (str) – The string to bold.
• escape (bool) – True if you need to escape special characters. Defaults to True.
• expandable (bool) – True if you need the quote to be expandable. Defaults to False.
Returns
The formatted string.
Return type
str
telebot.formatting.hcode(content: str, escape: bool | None = True) → str
Returns an HTML-formatted code string.
Parameters
• content (str) – The string to code.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.

318 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

Return type
str
telebot.formatting.hide_link(url: str) → str
Hide url of an image.
Parameters
url (str) – The url of the image.
Returns
The hidden url.
Return type
str
telebot.formatting.hitalic(content: str, escape: bool | None = True) → str
Returns an HTML-formatted italic string.
Parameters
• content (str) – The string to italicize.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.hlink(content: str, url: str, escape: bool | None = True) → str
Returns an HTML-formatted link string.
Parameters
• content (str) – The string to link.
• url (str) – The URL to link to.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.hpre(content: str, escape: bool | None = True, language: str = '') → str
Returns an HTML-formatted preformatted string.
Parameters
• content (str) – The string to preformatted.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str

1.3. Content 319

pyTelegramBotAPI, Release 4.25.0

telebot.formatting.hspoiler(content: str, escape: bool | None = True) → str

Returns an HTML-formatted spoiler string.
Parameters
• content (str) – The string to spoiler.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.hstrikethrough(content: str, escape: bool | None = True) → str
Returns an HTML-formatted strikethrough string.
Parameters
• content (str) – The string to strikethrough.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.hunderline(content: str, escape: bool | None = True) → str
Returns an HTML-formatted underline string.
Parameters
• content (str) – The string to underline.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.mbold(content: str, escape: bool | None = True) → str
Returns a Markdown-formatted bold string.
Parameters
• content (str) – The string to bold.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.mcite(content: str, escape: bool | None = True, expandable: bool | None = False) → str
Returns a Markdown-formatted block-quotation string.
Parameters
• content (str) – The string to bold.

320 Chapter 1. TeleBot

pyTelegramBotAPI, Release 4.25.0

• escape (bool) – True if you need to escape special characters. Defaults to True.
• expandable (bool) – True if you need the quote to be expandable. Defaults to False.
Returns
The formatted string.
Return type
str
telebot.formatting.mcode(content: str, language: str = '', escape: bool | None = True) → str
Returns a Markdown-formatted code string.
Parameters
• content (str) – The string to code.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.mitalic(content: str, escape: bool | None = True) → str
Returns a Markdown-formatted italic string.
Parameters
• content (str) – The string to italicize.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.mlink(content: str, url: str, escape: bool | None = True) → str
Returns a Markdown-formatted link string.
Parameters
• content (str) – The string to link.
• url (str) – The URL to link to.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.mspoiler(content: str, escape: bool | None = True) → str
Returns a Markdown-formatted spoiler string.
Parameters
• content (str) – The string to spoiler.
• escape (bool) – True if you need to escape special characters. Defaults to True.

1.3. Content 321

pyTelegramBotAPI, Release 4.25.0

Returns
The formatted string.
Return type
str
telebot.formatting.mstrikethrough(content: str, escape: bool | None = True) → str
Returns a Markdown-formatted strikethrough string.
Parameters
• content (str) – The string to strikethrough.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str
telebot.formatting.munderline(content: str, escape: bool | None = True) → str
Returns a Markdown-formatted underline string.
Parameters
• content (str) – The string to underline.
• escape (bool) – True if you need to escape special characters. Defaults to True.
Returns
The formatted string.
Return type
str

322 Chapter 1. TeleBot

CHAPTER

TWO

INDICES AND TABLES

• genindex
• modindex
• search

323
pyTelegramBotAPI, Release 4.25.0

324 Chapter 2. Indices and tables

PYTHON MODULE INDEX

t
telebot, 117
telebot.async_telebot, 216
telebot.asyncio_filters, 306
telebot.asyncio_handler_backends, 309
telebot.callback_data, 310
telebot.custom_filters, 211
telebot.formatting, 317
telebot.handler_backends, 215
telebot.types, 3
telebot.util, 311

325
pyTelegramBotAPI, Release 4.25.0

326 Python Module Index

INDEX

A answer_web_app_query() (tele-
add() (telebot.types.InlineKeyboardMarkup method), 43 bot.async_telebot.AsyncTeleBot method),
add() (telebot.types.Poll method), 93 221
add() (telebot.types.ReplyKeyboardMarkup method), 98 answer_web_app_query() (telebot.TeleBot method),
add_custom_filter() (tele- 123
bot.async_telebot.AsyncTeleBot method), antiflood() (in module telebot.util), 311
217 any_entities (telebot.types.Message property), 86
add_custom_filter() (telebot.TeleBot method), 119 any_text (telebot.types.Message property), 86
add_data() (telebot.async_telebot.AsyncTeleBot apply_html_entities() (in module tele-
method), 217 bot.formatting), 317
add_data() (telebot.TeleBot method), 119 approve_chat_join_request() (tele-
add_price() (telebot.types.ShippingOption method), bot.async_telebot.AsyncTeleBot method),
102 221
add_sticker_to_set() (tele- approve_chat_join_request() (telebot.TeleBot
bot.async_telebot.AsyncTeleBot method), method), 123
218 AsyncTeleBot (class in telebot.async_telebot), 216
add_sticker_to_set() (telebot.TeleBot method), 120 Audio (class in telebot.types), 4
AdvancedCustomFilter (class in tele-
bot.asyncio_filters), 306 B
AdvancedCustomFilter (class in tele- BackgroundFill (class in telebot.types), 5
bot.custom_filters), 211 BackgroundFillFreeformGradient (class in tele-
AffiliateInfo (class in telebot.types), 3 bot.types), 5
Animation (class in telebot.types), 4 BackgroundFillGradient (class in telebot.types), 5
answer_callback_query() (tele- BackgroundFillSolid (class in telebot.types), 6
bot.async_telebot.AsyncTeleBot method), BackgroundType (class in telebot.types), 6
219 BackgroundTypeChatTheme (class in telebot.types), 6
answer_callback_query() (telebot.TeleBot method), BackgroundTypeFill (class in telebot.types), 7
121 BackgroundTypePattern (class in telebot.types), 7
answer_inline_query() (tele- BackgroundTypeWallpaper (class in telebot.types), 7
bot.async_telebot.AsyncTeleBot method), ban_chat_member() (tele-
219 bot.async_telebot.AsyncTeleBot method),
answer_inline_query() (telebot.TeleBot method), 121 221
answer_pre_checkout_query() (tele- ban_chat_member() (telebot.TeleBot method), 123
bot.async_telebot.AsyncTeleBot method), ban_chat_sender_chat() (tele-
220 bot.async_telebot.AsyncTeleBot method),
answer_pre_checkout_query() (telebot.TeleBot 222
method), 122 ban_chat_sender_chat() (telebot.TeleBot method),
answer_shipping_query() (tele- 124
bot.async_telebot.AsyncTeleBot method), BaseMiddleware (class in tele-
220 bot.asyncio_handler_backends), 309
answer_shipping_query() (telebot.TeleBot method), BaseMiddleware (class in telebot.handler_backends),
122 215

327
pyTelegramBotAPI, Release 4.25.0

Birthdate (class in telebot.types), 8 channel_post_handler() (telebot.TeleBot method),

BotCommand (class in telebot.types), 8 125
BotCommandScope (class in telebot.types), 8 Chat (class in telebot.types), 15
BotCommandScopeAllChatAdministrators (class in chat_boost_handler() (tele-
telebot.types), 9 bot.async_telebot.AsyncTeleBot method),
BotCommandScopeAllGroupChats (class in tele- 224
bot.types), 10 chat_boost_handler() (telebot.TeleBot method), 126
BotCommandScopeAllPrivateChats (class in tele- chat_join_request_handler() (tele-
bot.types), 10 bot.async_telebot.AsyncTeleBot method),
BotCommandScopeChat (class in telebot.types), 10 224
BotCommandScopeChatAdministrators (class in tele- chat_join_request_handler() (telebot.TeleBot
bot.types), 10 method), 126
BotCommandScopeChatMember (class in telebot.types), chat_member_handler() (tele-
11 bot.async_telebot.AsyncTeleBot method),
BotCommandScopeDefault (class in telebot.types), 11 224
BotDescription (class in telebot.types), 11 chat_member_handler() (telebot.TeleBot method), 126
BotName (class in telebot.types), 12 ChatAdministratorRights (class in telebot.types), 15
BotShortDescription (class in telebot.types), 12 ChatBackground (class in telebot.types), 16
business_connection_handler() (tele- ChatBoost (class in telebot.types), 16
bot.async_telebot.AsyncTeleBot method), ChatBoostAdded (class in telebot.types), 17
222 ChatBoostRemoved (class in telebot.types), 17
business_connection_handler() (telebot.TeleBot ChatBoostSource (class in telebot.types), 17
method), 124 ChatBoostSourceGiftCode (class in telebot.types), 18
business_message_handler() (tele- ChatBoostSourceGiveaway (class in telebot.types), 18
bot.async_telebot.AsyncTeleBot method), ChatBoostSourcePremium (class in telebot.types), 18
222 ChatBoostUpdated (class in telebot.types), 19
business_message_handler() (telebot.TeleBot ChatFilter (class in telebot.asyncio_filters), 306
method), 124 ChatFilter (class in telebot.custom_filters), 212
BusinessConnection (class in telebot.types), 12 ChatFullInfo (class in telebot.types), 19
BusinessIntro (class in telebot.types), 13 ChatInviteLink (class in telebot.types), 22
BusinessLocation (class in telebot.types), 13 ChatJoinRequest (class in telebot.types), 23
BusinessMessagesDeleted (class in telebot.types), 13 ChatLocation (class in telebot.types), 23
BusinessOpeningHours (class in telebot.types), 13 ChatMember (class in telebot.types), 23
BusinessOpeningHoursInterval (class in tele- ChatMemberAdministrator (class in telebot.types), 24
bot.types), 14 ChatMemberBanned (class in telebot.types), 25
ChatMemberLeft (class in telebot.types), 26
C ChatMemberMember (class in telebot.types), 27
callback_query_handler() (tele- ChatMemberOwner (class in telebot.types), 27
bot.async_telebot.AsyncTeleBot method), ChatMemberRestricted (class in telebot.types), 28
223 ChatMemberUpdated (class in telebot.types), 29
callback_query_handler() (telebot.TeleBot method), ChatPermissions (class in telebot.types), 30
125 ChatPhoto (class in telebot.types), 31
CallbackData (class in telebot.callback_data), 310 ChatShared (class in telebot.types), 31
CallbackDataFilter (class in telebot.callback_data), check() (telebot.asyncio_filters.AdvancedCustomFilter
311 method), 306
CallbackQuery (class in telebot.types), 14 check() (telebot.asyncio_filters.SimpleCustomFilter
can_manage_voice_chats (telebot.types.ChatMember method), 308
property), 24 check() (telebot.callback_data.CallbackDataFilter
CancelUpdate (class in tele- method), 311
bot.asyncio_handler_backends), 310 check() (telebot.custom_filters.AdvancedCustomFilter
CancelUpdate (class in telebot.handler_backends), 215 method), 211
channel_post_handler() (tele- check() (telebot.custom_filters.SimpleCustomFilter
bot.async_telebot.AsyncTeleBot method), method), 213
223 chosen_inline_handler() (tele-

328 Index
pyTelegramBotAPI, Release 4.25.0

bot.async_telebot.AsyncTeleBot method), create_forum_topic() (tele-

224 bot.async_telebot.AsyncTeleBot method),
chosen_inline_handler() (telebot.TeleBot method), 228
126 create_forum_topic() (telebot.TeleBot method), 131
ChosenInlineResult (class in telebot.types), 31 create_invoice_link() (tele-
chunks() (in module telebot.util), 312 bot.async_telebot.AsyncTeleBot method),
clear_reply_handlers() (telebot.TeleBot method), 228
127 create_invoice_link() (telebot.TeleBot method), 131
clear_reply_handlers_by_message_id() (tele- create_new_sticker_set() (tele-
bot.TeleBot method), 127 bot.async_telebot.AsyncTeleBot method),
clear_step_handler() (telebot.TeleBot method), 127 230
clear_step_handler_by_chat_id() (telebot.TeleBot create_new_sticker_set() (telebot.TeleBot method),
method), 127 132
close() (telebot.async_telebot.AsyncTeleBot method),
225 D
close() (telebot.TeleBot method), 127 decline_chat_join_request() (tele-
close_forum_topic() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 231
225 decline_chat_join_request() (telebot.TeleBot
close_forum_topic() (telebot.TeleBot method), 127 method), 133
close_general_forum_topic() (tele- delete_chat_photo() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
225 231
close_general_forum_topic() (telebot.TeleBot delete_chat_photo() (telebot.TeleBot method), 134
method), 128 delete_chat_sticker_set() (tele-
close_session() (telebot.async_telebot.AsyncTeleBot bot.async_telebot.AsyncTeleBot method),
method), 225 231
Contact (class in telebot.types), 32 delete_chat_sticker_set() (telebot.TeleBot
contains_masks (telebot.types.StickerSet property), 105 method), 134
content_type_media (in module telebot.util), 312 delete_forum_topic() (tele-
content_type_service (in module telebot.util), 312 bot.async_telebot.AsyncTeleBot method),
ContinueHandling (class in tele- 232
bot.asyncio_handler_backends), 310 delete_forum_topic() (telebot.TeleBot method), 134
ContinueHandling (class in telebot.handler_backends), delete_message() (telebot.async_telebot.AsyncTeleBot
215 method), 232
convert_input_sticker() (telebot.types.InputSticker delete_message() (telebot.TeleBot method), 135
method), 73 delete_messages() (tele-
copy_message() (telebot.async_telebot.AsyncTeleBot bot.async_telebot.AsyncTeleBot method),
method), 225 232
copy_message() (telebot.TeleBot method), 128 delete_messages() (telebot.TeleBot method), 135
copy_messages() (telebot.async_telebot.AsyncTeleBot delete_my_commands() (tele-
method), 226 bot.async_telebot.AsyncTeleBot method),
copy_messages() (telebot.TeleBot method), 129 233
CopyTextButton (class in telebot.types), 32 delete_my_commands() (telebot.TeleBot method), 135
create_chat_invite_link() (tele- delete_state() (telebot.async_telebot.AsyncTeleBot
bot.async_telebot.AsyncTeleBot method), method), 233
227 delete_state() (telebot.TeleBot method), 136
create_chat_invite_link() (telebot.TeleBot delete_sticker_from_set() (tele-
method), 130 bot.async_telebot.AsyncTeleBot method),
create_chat_subscription_invite_link() (tele- 233
bot.async_telebot.AsyncTeleBot method), delete_sticker_from_set() (telebot.TeleBot
228 method), 136
create_chat_subscription_invite_link() (tele- delete_sticker_set() (tele-
bot.TeleBot method), 130 bot.async_telebot.AsyncTeleBot method),

Index 329
pyTelegramBotAPI, Release 4.25.0

233 edit_message_media() (tele-

delete_sticker_set() (telebot.TeleBot method), 136 bot.async_telebot.AsyncTeleBot method),
delete_webhook() (telebot.async_telebot.AsyncTeleBot 237
method), 234 edit_message_media() (telebot.TeleBot method), 140
delete_webhook() (telebot.TeleBot method), 136 edit_message_reply_markup() (tele-
deleted_business_messages_handler() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 238
234 edit_message_reply_markup() (telebot.TeleBot
deleted_business_messages_handler() (tele- method), 141
bot.TeleBot method), 137 edit_message_text() (tele-
Dice (class in telebot.types), 33 bot.async_telebot.AsyncTeleBot method),
Dictionaryable (class in telebot.types), 33 239
difference (telebot.types.ChatMemberUpdated prop- edit_message_text() (telebot.TeleBot method), 142
erty), 29 edit_user_star_subscription() (tele-
disable_save_next_step_handlers() (tele- bot.async_telebot.AsyncTeleBot method),
bot.TeleBot method), 137 239
disable_save_reply_handlers() (telebot.TeleBot edit_user_star_subscription() (telebot.TeleBot
method), 137 method), 142
Document (class in telebot.types), 33 edited_business_message_handler() (tele-
download_file() (telebot.async_telebot.AsyncTeleBot bot.async_telebot.AsyncTeleBot method),
method), 234 240
download_file() (telebot.TeleBot method), 137 edited_business_message_handler() (tele-
bot.TeleBot method), 143
E edited_channel_post_handler() (tele-
edit_chat_invite_link() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 240
234 edited_channel_post_handler() (telebot.TeleBot
edit_chat_invite_link() (telebot.TeleBot method), method), 143
137 edited_message_handler() (tele-
edit_chat_subscription_invite_link() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 240
235 edited_message_handler() (telebot.TeleBot method),
edit_chat_subscription_invite_link() (tele- 143
bot.TeleBot method), 138 enable_save_next_step_handlers() (tele-
edit_forum_topic() (tele- bot.TeleBot method), 144
bot.async_telebot.AsyncTeleBot method), enable_save_reply_handlers() (telebot.TeleBot
235 method), 144
edit_forum_topic() (telebot.TeleBot method), 138 enable_saving_states() (tele-
edit_general_forum_topic() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 241
236 enable_saving_states() (telebot.TeleBot method),
edit_general_forum_topic() (telebot.TeleBot 144
method), 138 escape() (in module telebot.util), 312
edit_message_caption() (tele- escape_html() (in module telebot.formatting), 317
bot.async_telebot.AsyncTeleBot method), escape_markdown() (in module telebot.formatting), 317
236 ExceptionHandler (class in telebot), 117
edit_message_caption() (telebot.TeleBot method), ExceptionHandler (class in telebot.async_telebot), 306
139 export_chat_invite_link() (tele-
edit_message_live_location() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 241
237 export_chat_invite_link() (telebot.TeleBot
edit_message_live_location() (telebot.TeleBot method), 144
method), 139 ExternalReplyInfo (class in telebot.types), 34
extract_arguments() (in module telebot.util), 312

330 Index
pyTelegramBotAPI, Release 4.25.0

extract_bot_id() (in module telebot.util), 313 get_business_connection() (telebot.TeleBot

extract_command() (in module telebot.util), 313 method), 146
get_chat() (telebot.async_telebot.AsyncTeleBot
F method), 243
File (class in telebot.types), 35 get_chat() (telebot.TeleBot method), 146
file (telebot.types.InputFile property), 65 get_chat_administrators() (tele-
file_name (telebot.types.InputFile property), 65 bot.async_telebot.AsyncTeleBot method),
filter() (telebot.callback_data.CallbackData method), 243
311 get_chat_administrators() (telebot.TeleBot
ForceReply (class in telebot.types), 35 method), 146
format_text() (in module telebot.formatting), 317 get_chat_member() (tele-
ForumTopic (class in telebot.types), 36 bot.async_telebot.AsyncTeleBot method),
ForumTopicClosed (class in telebot.types), 36 243
ForumTopicCreated (class in telebot.types), 36 get_chat_member() (telebot.TeleBot method), 147
ForumTopicEdited (class in telebot.types), 37 get_chat_member_count() (tele-
ForumTopicReopened (class in telebot.types), 37 bot.async_telebot.AsyncTeleBot method),
forward_date (telebot.types.Message property), 86 244
forward_from (telebot.types.Message property), 86 get_chat_member_count() (telebot.TeleBot method),
forward_from_chat (telebot.types.Message property), 147
86 get_chat_members_count() (tele-
forward_from_message_id (telebot.types.Message bot.async_telebot.AsyncTeleBot method),
property), 86 244
forward_message() (tele- get_chat_members_count() (telebot.TeleBot method),
bot.async_telebot.AsyncTeleBot method), 147
241 get_chat_menu_button() (tele-
forward_message() (telebot.TeleBot method), 145 bot.async_telebot.AsyncTeleBot method),
forward_messages() (tele- 244
bot.async_telebot.AsyncTeleBot method), get_chat_menu_button() (telebot.TeleBot method),
242 147
forward_messages() (telebot.TeleBot method), 145 get_custom_emoji_stickers() (tele-
forward_sender_name (telebot.types.Message prop- bot.async_telebot.AsyncTeleBot method),
erty), 86 244
forward_signature (telebot.types.Message property), get_custom_emoji_stickers() (telebot.TeleBot
86 method), 147
ForwardFilter (class in telebot.asyncio_filters), 306 get_file() (telebot.async_telebot.AsyncTeleBot
ForwardFilter (class in telebot.custom_filters), 212 method), 244
full_name (telebot.types.User property), 112 get_file() (telebot.TeleBot method), 148
get_file_url() (telebot.async_telebot.AsyncTeleBot
G method), 244
Game (class in telebot.types), 37 get_file_url() (telebot.TeleBot method), 148
GameHighScore (class in telebot.types), 38 get_forum_topic_icon_stickers() (tele-
GeneralForumTopicHidden (class in telebot.types), 38 bot.async_telebot.AsyncTeleBot method),
GeneralForumTopicUnhidden (class in telebot.types), 245
38 get_forum_topic_icon_stickers() (telebot.TeleBot
generate_random_token() (in module telebot.util), method), 148
313 get_game_high_scores() (tele-
get_available_gifts() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 245
242 get_game_high_scores() (telebot.TeleBot method),
get_available_gifts() (telebot.TeleBot method), 146 148
get_business_connection() (tele- get_me() (telebot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 245
243 get_me() (telebot.TeleBot method), 149
get_my_commands() (tele-

Index 331
pyTelegramBotAPI, Release 4.25.0

bot.async_telebot.AsyncTeleBot method), GiveawayWinners (class in telebot.types), 40

245
get_my_commands() (telebot.TeleBot method), 149 H
get_my_default_administrator_rights() (tele- handle() (telebot.async_telebot.ExceptionHandler
bot.async_telebot.AsyncTeleBot method), method), 306
246 handle() (telebot.ExceptionHandler method), 118
get_my_default_administrator_rights() (tele- Handler (class in telebot), 118
bot.TeleBot method), 149 Handler (class in telebot.async_telebot), 306
get_my_description() (tele- hbold() (in module telebot.formatting), 318
bot.async_telebot.AsyncTeleBot method), hcite() (in module telebot.formatting), 318
246 hcode() (in module telebot.formatting), 318
get_my_description() (telebot.TeleBot method), 149 hide_general_forum_topic() (tele-
get_my_name() (telebot.async_telebot.AsyncTeleBot bot.async_telebot.AsyncTeleBot method),
method), 246 249
get_my_name() (telebot.TeleBot method), 150 hide_general_forum_topic() (telebot.TeleBot
get_my_short_description() (tele- method), 152
bot.async_telebot.AsyncTeleBot method), hide_link() (in module telebot.formatting), 319
246 hitalic() (in module telebot.formatting), 319
get_my_short_description() (telebot.TeleBot hlink() (in module telebot.formatting), 319
method), 150 hpre() (in module telebot.formatting), 319
get_star_transactions() (tele- hspoiler() (in module telebot.formatting), 319
bot.async_telebot.AsyncTeleBot method), hstrikethrough() (in module telebot.formatting), 320
247 html_caption (telebot.types.Message property), 86
get_star_transactions() (telebot.TeleBot method), html_text (telebot.types.Message property), 86
150 html_text (telebot.types.TextQuote property), 107
get_state() (telebot.async_telebot.AsyncTeleBot hunderline() (in module telebot.formatting), 320
method), 247
get_state() (telebot.TeleBot method), 150 I
get_sticker_set() (tele- InaccessibleMessage (class in telebot.types), 41
bot.async_telebot.AsyncTeleBot method), infinity_polling() (tele-
247 bot.async_telebot.AsyncTeleBot method),
get_sticker_set() (telebot.TeleBot method), 151 249
get_updates() (telebot.async_telebot.AsyncTeleBot infinity_polling() (telebot.TeleBot method), 153
method), 247 inline_handler() (telebot.async_telebot.AsyncTeleBot
get_updates() (telebot.TeleBot method), 151 method), 250
get_user_chat_boosts() (tele- inline_handler() (telebot.TeleBot method), 153
bot.async_telebot.AsyncTeleBot method), InlineKeyboardButton (class in telebot.types), 41
248 InlineKeyboardMarkup (class in telebot.types), 43
get_user_chat_boosts() (telebot.TeleBot method), InlineQuery (class in telebot.types), 44
152 InlineQueryResultArticle (class in telebot.types), 44
get_user_profile_photos() (tele- InlineQueryResultAudio (class in telebot.types), 45
bot.async_telebot.AsyncTeleBot method), InlineQueryResultBase (class in telebot.types), 46
248 InlineQueryResultCachedAudio (class in tele-
get_user_profile_photos() (telebot.TeleBot bot.types), 47
method), 152 InlineQueryResultCachedBase (class in tele-
get_webhook_info() (tele- bot.types), 48
bot.async_telebot.AsyncTeleBot method), InlineQueryResultCachedDocument (class in tele-
249 bot.types), 48
get_webhook_info() (telebot.TeleBot method), 152 InlineQueryResultCachedGif (class in telebot.types),
Gift (class in telebot.types), 38 49
Gifts (class in telebot.types), 39 InlineQueryResultCachedMpeg4Gif (class in tele-
Giveaway (class in telebot.types), 39 bot.types), 50
GiveawayCompleted (class in telebot.types), 40 InlineQueryResultCachedPhoto (class in tele-
GiveawayCreated (class in telebot.types), 40 bot.types), 50

332 Index
pyTelegramBotAPI, Release 4.25.0

InlineQueryResultCachedSticker (class in tele- J

bot.types), 51 JsonDeserializable (class in telebot.types), 75
InlineQueryResultCachedVideo (class in tele- JsonSerializable (class in telebot.types), 75
bot.types), 52
InlineQueryResultCachedVoice (class in tele- K
bot.types), 53 key (telebot.asyncio_filters.AdvancedCustomFilter
InlineQueryResultContact (class in telebot.types), 54 attribute), 306
InlineQueryResultDocument (class in telebot.types), key (telebot.asyncio_filters.ChatFilter attribute), 306
55 key (telebot.asyncio_filters.ForwardFilter attribute), 307
InlineQueryResultGame (class in telebot.types), 56 key (telebot.asyncio_filters.IsAdminFilter attribute), 307
InlineQueryResultGif (class in telebot.types), 56 key (telebot.asyncio_filters.IsDigitFilter attribute), 307
InlineQueryResultLocation (class in telebot.types), key (telebot.asyncio_filters.IsReplyFilter attribute), 307
57 key (telebot.asyncio_filters.LanguageFilter attribute),
InlineQueryResultMpeg4Gif (class in telebot.types), 307
58 key (telebot.asyncio_filters.SimpleCustomFilter at-
InlineQueryResultPhoto (class in telebot.types), 59 tribute), 308
InlineQueryResultsButton (class in telebot.types), 63 key (telebot.asyncio_filters.StateFilter attribute), 308
InlineQueryResultVenue (class in telebot.types), 60 key (telebot.asyncio_filters.TextContainsFilter attribute),
InlineQueryResultVideo (class in telebot.types), 62 308
InlineQueryResultVoice (class in telebot.types), 63 key (telebot.asyncio_filters.TextMatchFilter attribute),
InputContactMessageContent (class in telebot.types), 309
64 key (telebot.asyncio_filters.TextStartsFilter attribute),
InputFile (class in telebot.types), 64 309
InputInvoiceMessageContent (class in telebot.types), key (telebot.custom_filters.AdvancedCustomFilter at-
65 tribute), 211
InputLocationMessageContent (class in tele- key (telebot.custom_filters.ChatFilter attribute), 212
bot.types), 66 key (telebot.custom_filters.ForwardFilter attribute), 212
InputMedia (class in telebot.types), 67 key (telebot.custom_filters.IsAdminFilter attribute), 212
InputMediaAnimation (class in telebot.types), 67 key (telebot.custom_filters.IsDigitFilter attribute), 212
InputMediaAudio (class in telebot.types), 68 key (telebot.custom_filters.IsReplyFilter attribute), 213
InputMediaDocument (class in telebot.types), 69 key (telebot.custom_filters.LanguageFilter attribute), 213
InputMediaPhoto (class in telebot.types), 70 key (telebot.custom_filters.SimpleCustomFilter at-
InputMediaVideo (class in telebot.types), 70 tribute), 213
InputPaidMedia (class in telebot.types), 71 key (telebot.custom_filters.StateFilter attribute), 213
InputPaidMediaPhoto (class in telebot.types), 71 key (telebot.custom_filters.TextContainsFilter attribute),
InputPaidMediaVideo (class in telebot.types), 72 214
InputPollOption (class in telebot.types), 72 key (telebot.custom_filters.TextMatchFilter attribute),
InputSticker (class in telebot.types), 73 214
InputTextMessageContent (class in telebot.types), 73 key (telebot.custom_filters.TextStartsFilter attribute), 214
InputVenueMessageContent (class in telebot.types), 74 KeyboardButton (class in telebot.types), 75
Invoice (class in telebot.types), 74 KeyboardButtonPollType (class in telebot.types), 76
is_animated (telebot.types.StickerSet property), 105 KeyboardButtonRequestChat (class in telebot.types),
is_bytes() (in module telebot.util), 313 76
is_command() (in module telebot.util), 313 KeyboardButtonRequestUser (class in telebot.types),
is_dict() (in module telebot.util), 313 77
is_pil_image() (in module telebot.util), 314 KeyboardButtonRequestUsers (class in telebot.types),
is_string() (in module telebot.util), 314 77
is_video (telebot.types.StickerSet property), 105 kick_chat_member() (tele-
IsAdminFilter (class in telebot.asyncio_filters), 307 bot.async_telebot.AsyncTeleBot method),
IsAdminFilter (class in telebot.custom_filters), 212 250
IsDigitFilter (class in telebot.asyncio_filters), 307 kick_chat_member() (telebot.TeleBot method), 153
IsDigitFilter (class in telebot.custom_filters), 212
IsReplyFilter (class in telebot.asyncio_filters), 307 L
IsReplyFilter (class in telebot.custom_filters), 212 LabeledPrice (class in telebot.types), 78

Index 333
pyTelegramBotAPI, Release 4.25.0

LanguageFilter (class in telebot.asyncio_filters), 307 MessageReactionCountUpdated (class in tele-

LanguageFilter (class in telebot.custom_filters), 213 bot.types), 89
leave_chat() (telebot.async_telebot.AsyncTeleBot MessageReactionUpdated (class in telebot.types), 89
method), 250 middleware_handler() (telebot.TeleBot method), 156
leave_chat() (telebot.TeleBot method), 154 mitalic() (in module telebot.formatting), 321
LinkPreviewOptions (class in telebot.types), 78 mlink() (in module telebot.formatting), 321
load_next_step_handlers() (telebot.TeleBot module
method), 154 telebot, 117
load_reply_handlers() (telebot.TeleBot method), 154 telebot.async_telebot, 216
Location (class in telebot.types), 79 telebot.asyncio_filters, 306
log_deprecation_warning() (in module tele- telebot.asyncio_handler_backends, 309
bot.types), 117 telebot.callback_data, 310
log_out() (telebot.async_telebot.AsyncTeleBot telebot.custom_filters, 211
method), 250 telebot.formatting, 317
log_out() (telebot.TeleBot method), 154 telebot.handler_backends, 215
LoginUrl (class in telebot.types), 79 telebot.types, 3
telebot.util, 311
M mspoiler() (in module telebot.formatting), 321
MaskPosition (class in telebot.types), 80 mstrikethrough() (in module telebot.formatting), 322
max_row_keys (telebot.types.InlineKeyboardMarkup at- munderline() (in module telebot.formatting), 322
tribute), 44 my_chat_member_handler() (tele-
max_row_keys (telebot.types.ReplyKeyboardMarkup at- bot.async_telebot.AsyncTeleBot method),
tribute), 98 252
mbold() (in module telebot.formatting), 320 my_chat_member_handler() (telebot.TeleBot method),
mcite() (in module telebot.formatting), 320 156
mcode() (in module telebot.formatting), 321
MenuButton (class in telebot.types), 80 N
MenuButtonCommands (class in telebot.types), 80 new() (telebot.callback_data.CallbackData method), 311
MenuButtonDefault (class in telebot.types), 81 new_chat_member (telebot.types.Message property), 86
MenuButtonWebApp (class in telebot.types), 81
Message (class in telebot.types), 81 O
message_handler() (tele- OrderInfo (class in telebot.types), 90
bot.async_telebot.AsyncTeleBot method),
250 P
message_handler() (telebot.TeleBot method), 154 PaidMedia (class in telebot.types), 90
message_reaction_count_handler() (tele- PaidMediaInfo (class in telebot.types), 90
bot.async_telebot.AsyncTeleBot method), PaidMediaPhoto (class in telebot.types), 91
251 PaidMediaPreview (class in telebot.types), 91
message_reaction_count_handler() (tele- PaidMediaPurchased (class in telebot.types), 91
bot.TeleBot method), 155 PaidMediaVideo (class in telebot.types), 91
message_reaction_handler() (tele- parse() (telebot.callback_data.CallbackData method),
bot.async_telebot.AsyncTeleBot method), 311
252 parse_chat() (telebot.types.Message class method), 86
message_reaction_handler() (telebot.TeleBot parse_entities() (telebot.types.Game class method),
method), 156 38
MessageAutoDeleteTimerChanged (class in tele- parse_entities() (telebot.types.Message class
bot.types), 86 method), 86
MessageEntity (class in telebot.types), 87 parse_photo() (telebot.types.Game class method), 38
MessageID (class in telebot.types), 87 parse_photo() (telebot.types.Message class method),
MessageOrigin (class in telebot.types), 88 86
MessageOriginChannel (class in telebot.types), 88 parse_web_app_data() (in module telebot.util), 314
MessageOriginChat (class in telebot.types), 88 PhotoSize (class in telebot.types), 92
MessageOriginHiddenUser (class in telebot.types), 88 pil_image_to_file() (in module telebot.util), 314
MessageOriginUser (class in telebot.types), 89

334 Index
pyTelegramBotAPI, Release 4.25.0

pin_chat_message() (tele- ReactionType (class in telebot.types), 95

bot.async_telebot.AsyncTeleBot method), ReactionTypeCustomEmoji (class in telebot.types), 96
252 ReactionTypeEmoji (class in telebot.types), 96
pin_chat_message() (telebot.TeleBot method), 157 ReactionTypePaid (class in telebot.types), 96
Poll (class in telebot.types), 92 refund_star_payment() (tele-
poll_answer_handler() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 255
252 refund_star_payment() (telebot.TeleBot method), 160
poll_answer_handler() (telebot.TeleBot method), 157 RefundedPayment (class in telebot.types), 96
poll_handler() (telebot.async_telebot.AsyncTeleBot register_business_connection_handler() (tele-
method), 253 bot.async_telebot.AsyncTeleBot method),
poll_handler() (telebot.TeleBot method), 157 255
PollAnswer (class in telebot.types), 93 register_business_connection_handler() (tele-
polling() (telebot.async_telebot.AsyncTeleBot bot.TeleBot method), 160
method), 253 register_business_message_handler() (tele-
polling() (telebot.TeleBot method), 157 bot.async_telebot.AsyncTeleBot method),
PollOption (class in telebot.types), 93 256
post_process() (tele- register_business_message_handler() (tele-
bot.asyncio_handler_backends.BaseMiddleware bot.TeleBot method), 160
method), 310 register_callback_query_handler() (tele-
post_process() (tele- bot.async_telebot.AsyncTeleBot method),
bot.handler_backends.BaseMiddleware 256
method), 215 register_callback_query_handler() (tele-
pre_checkout_query_handler() (tele- bot.TeleBot method), 161
bot.async_telebot.AsyncTeleBot method), register_channel_post_handler() (tele-
253 bot.async_telebot.AsyncTeleBot method),
pre_checkout_query_handler() (telebot.TeleBot 256
method), 158 register_channel_post_handler() (telebot.TeleBot
pre_process() (telebot.asyncio_handler_backends.BaseMiddlewaremethod), 161
method), 310 register_chat_boost_handler() (tele-
pre_process() (telebot.handler_backends.BaseMiddleware bot.async_telebot.AsyncTeleBot method),
method), 215 257
PreCheckoutQuery (class in telebot.types), 94 register_chat_boost_handler() (telebot.TeleBot
PreparedInlineMessage (class in telebot.types), 94 method), 161
process_new_updates() (tele- register_chat_join_request_handler() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
254 257
process_new_updates() (telebot.TeleBot method), 158 register_chat_join_request_handler() (tele-
promote_chat_member() (tele- bot.TeleBot method), 162
bot.async_telebot.AsyncTeleBot method), register_chat_member_handler() (tele-
254 bot.async_telebot.AsyncTeleBot method),
promote_chat_member() (telebot.TeleBot method), 158 257
ProximityAlertTriggered (class in telebot.types), 95 register_chat_member_handler() (telebot.TeleBot
purchased_paid_media_handler() (tele- method), 162
bot.async_telebot.AsyncTeleBot method), register_chosen_inline_handler() (tele-
255 bot.async_telebot.AsyncTeleBot method),
purchased_paid_media_handler() (telebot.TeleBot 258
method), 160 register_chosen_inline_handler() (tele-
bot.TeleBot method), 162
Q register_deleted_business_messages_handler()
quick_markup() (in module telebot.util), 314 (telebot.async_telebot.AsyncTeleBot method),
258
R register_deleted_business_messages_handler()
ReactionCount (class in telebot.types), 95 (telebot.TeleBot method), 162

Index 335
pyTelegramBotAPI, Release 4.25.0

register_edited_business_message_handler() register_poll_handler() (tele-

(telebot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
258 261
register_edited_business_message_handler() register_poll_handler() (telebot.TeleBot method),
(telebot.TeleBot method), 163 167
register_edited_channel_post_handler() (tele- register_pre_checkout_query_handler() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
259 262
register_edited_channel_post_handler() (tele- register_pre_checkout_query_handler() (tele-
bot.TeleBot method), 163 bot.TeleBot method), 168
register_edited_message_handler() (tele- register_purchased_paid_media_handler() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method), 262
259 register_purchased_paid_media_handler() (tele-
register_edited_message_handler() (tele- bot.TeleBot method), 168
bot.TeleBot method), 164 register_removed_chat_boost_handler() (tele-
register_for_reply() (telebot.TeleBot method), 164 bot.async_telebot.AsyncTeleBot method),
register_for_reply_by_message_id() (tele- 262
bot.TeleBot method), 164 register_removed_chat_boost_handler() (tele-
register_inline_handler() (tele- bot.TeleBot method), 168
bot.async_telebot.AsyncTeleBot method), register_shipping_query_handler() (tele-
259 bot.async_telebot.AsyncTeleBot method),
register_inline_handler() (telebot.TeleBot 262
method), 165 register_shipping_query_handler() (tele-
register_message_handler() (tele- bot.TeleBot method), 168
bot.async_telebot.AsyncTeleBot method), remove_chat_verification() (tele-
260 bot.async_telebot.AsyncTeleBot method),
register_message_handler() (telebot.TeleBot 263
method), 165 remove_chat_verification() (telebot.TeleBot
register_message_reaction_count_handler() method), 169
(telebot.async_telebot.AsyncTeleBot method), remove_user_verification() (tele-
260 bot.async_telebot.AsyncTeleBot method),
register_message_reaction_count_handler() 263
(telebot.TeleBot method), 165 remove_user_verification() (telebot.TeleBot
register_message_reaction_handler() (tele- method), 169
bot.async_telebot.AsyncTeleBot method), remove_webhook() (telebot.async_telebot.AsyncTeleBot
260 method), 263
register_message_reaction_handler() (tele- remove_webhook() (telebot.TeleBot method), 169
bot.TeleBot method), 166 removed_chat_boost_handler() (tele-
register_middleware_handler() (telebot.TeleBot bot.async_telebot.AsyncTeleBot method),
method), 166 263
register_my_chat_member_handler() (tele- removed_chat_boost_handler() (telebot.TeleBot
bot.async_telebot.AsyncTeleBot method), method), 169
261 reopen_forum_topic() (tele-
register_my_chat_member_handler() (tele- bot.async_telebot.AsyncTeleBot method),
bot.TeleBot method), 166 263
register_next_step_handler() (telebot.TeleBot reopen_forum_topic() (telebot.TeleBot method), 170
method), 167 reopen_general_forum_topic() (tele-
register_next_step_handler_by_chat_id() (tele- bot.async_telebot.AsyncTeleBot method),
bot.TeleBot method), 167 264
register_poll_answer_handler() (tele- reopen_general_forum_topic() (telebot.TeleBot
bot.async_telebot.AsyncTeleBot method), method), 170
261 replace_sticker_in_set() (tele-
register_poll_answer_handler() (telebot.TeleBot bot.async_telebot.AsyncTeleBot method),
method), 167 264

336 Index
pyTelegramBotAPI, Release 4.25.0

replace_sticker_in_set() (telebot.TeleBot method), send_contact() (telebot.async_telebot.AsyncTeleBot

170 method), 272
REPLY_MARKUP_TYPES (in module telebot), 118 send_contact() (telebot.TeleBot method), 178
reply_to() (telebot.async_telebot.AsyncTeleBotsend_dice() (telebot.async_telebot.AsyncTeleBot
method), 264 method), 273
reply_to() (telebot.TeleBot method), 170 send_dice() (telebot.TeleBot method), 179
ReplyKeyboardMarkup (class in telebot.types), 97 send_document() (telebot.async_telebot.AsyncTeleBot
ReplyKeyboardRemove (class in telebot.types), 98 method), 274
ReplyParameters (class in telebot.types), 99 send_document() (telebot.TeleBot method), 180
reset_data() (telebot.async_telebot.AsyncTeleBotsend_game() (telebot.async_telebot.AsyncTeleBot
method), 265 method), 275
reset_data() (telebot.TeleBot method), 171 send_game() (telebot.TeleBot method), 181
restrict_chat_member() (tele-
send_gift() (telebot.async_telebot.AsyncTeleBot
bot.async_telebot.AsyncTeleBot method), method), 276
265 send_gift() (telebot.TeleBot method), 182
restrict_chat_member() (telebot.TeleBot method), send_invoice() (telebot.async_telebot.AsyncTeleBot
171 method), 277
retrieve_data() (telebot.async_telebot.AsyncTeleBot send_invoice() (telebot.TeleBot method), 182
method), 266 send_location() (telebot.async_telebot.AsyncTeleBot
retrieve_data() (telebot.TeleBot method), 172 method), 278
RevenueWithdrawalState (class in telebot.types), 100 send_location() (telebot.TeleBot method), 184
RevenueWithdrawalStateFailed (class in tele- send_media_group() (tele-
bot.types), 100 bot.async_telebot.AsyncTeleBot method),
RevenueWithdrawalStatePending (class in tele- 280
bot.types), 100 send_media_group() (telebot.TeleBot method), 186
RevenueWithdrawalStateSucceeded (class in tele- send_message() (telebot.async_telebot.AsyncTeleBot
bot.types), 100 method), 281
revoke_chat_invite_link() (tele-
send_message() (telebot.TeleBot method), 186
bot.async_telebot.AsyncTeleBot method),send_paid_media() (tele-
266 bot.async_telebot.AsyncTeleBot method),
revoke_chat_invite_link() (telebot.TeleBot 282
method), 172 send_paid_media() (telebot.TeleBot method), 188
row() (telebot.types.InlineKeyboardMarkup method), 44 send_photo() (telebot.async_telebot.AsyncTeleBot
row() (telebot.types.ReplyKeyboardMarkup method), 98 method), 283
run_webhooks() (telebot.async_telebot.AsyncTeleBot send_photo() (telebot.TeleBot method), 189
method), 267 send_poll() (telebot.async_telebot.AsyncTeleBot
run_webhooks() (telebot.TeleBot method), 173 method), 284
send_poll() (telebot.TeleBot method), 190
S send_sticker() (telebot.async_telebot.AsyncTeleBot
save_prepared_inline_message() (tele- method), 286
bot.async_telebot.AsyncTeleBot method), send_sticker() (telebot.TeleBot method), 191
267 send_venue() (telebot.async_telebot.AsyncTeleBot
save_prepared_inline_message() (telebot.TeleBot method), 287
method), 173 send_venue() (telebot.TeleBot method), 192
send_animation() (telebot.async_telebot.AsyncTeleBot send_video() (telebot.async_telebot.AsyncTeleBot
method), 268 method), 288
send_animation() (telebot.TeleBot method), 174 send_video() (telebot.TeleBot method), 194
send_audio() (telebot.async_telebot.AsyncTeleBot send_video_note() (tele-
method), 269 bot.async_telebot.AsyncTeleBot method),
send_audio() (telebot.TeleBot method), 175 289
send_chat_action() (tele- send_video_note() (telebot.TeleBot method), 195
bot.async_telebot.AsyncTeleBot method), send_voice() (telebot.async_telebot.AsyncTeleBot
271 method), 291
send_chat_action() (telebot.TeleBot method), 177 send_voice() (telebot.TeleBot method), 196

Index 337
pyTelegramBotAPI, Release 4.25.0

SentWebAppMessage (class in telebot.types), 101 set_my_description() (tele-

set_chat_administrator_custom_title() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 296
292 set_my_description() (telebot.TeleBot method), 202
set_chat_administrator_custom_title() (tele- set_my_name() (telebot.async_telebot.AsyncTeleBot
bot.TeleBot method), 198 method), 297
set_chat_description() (tele- set_my_name() (telebot.TeleBot method), 202
bot.async_telebot.AsyncTeleBot method), set_my_short_description() (tele-
292 bot.async_telebot.AsyncTeleBot method),
set_chat_description() (telebot.TeleBot method), 297
198 set_my_short_description() (telebot.TeleBot
set_chat_menu_button() (tele- method), 202
bot.async_telebot.AsyncTeleBot method), set_state() (telebot.async_telebot.AsyncTeleBot
293 method), 297
set_chat_menu_button() (telebot.TeleBot method), set_state() (telebot.TeleBot method), 203
198 set_sticker_emoji_list() (tele-
set_chat_permissions() (tele- bot.async_telebot.AsyncTeleBot method),
bot.async_telebot.AsyncTeleBot method), 298
293 set_sticker_emoji_list() (telebot.TeleBot method),
set_chat_permissions() (telebot.TeleBot method), 203
199 set_sticker_keywords() (tele-
set_chat_photo() (telebot.async_telebot.AsyncTeleBot bot.async_telebot.AsyncTeleBot method),
method), 293 298
set_chat_photo() (telebot.TeleBot method), 199 set_sticker_keywords() (telebot.TeleBot method),
set_chat_sticker_set() (tele- 204
bot.async_telebot.AsyncTeleBot method), set_sticker_mask_position() (tele-
294 bot.async_telebot.AsyncTeleBot method),
set_chat_sticker_set() (telebot.TeleBot method), 298
199 set_sticker_mask_position() (telebot.TeleBot
set_chat_title() (telebot.async_telebot.AsyncTeleBot method), 204
method), 294 set_sticker_position_in_set() (tele-
set_chat_title() (telebot.TeleBot method), 200 bot.async_telebot.AsyncTeleBot method),
set_custom_emoji_sticker_set_thumbnail() 298
(telebot.async_telebot.AsyncTeleBot method), set_sticker_position_in_set() (telebot.TeleBot
294 method), 204
set_custom_emoji_sticker_set_thumbnail() set_sticker_set_thumb() (tele-
(telebot.TeleBot method), 200 bot.async_telebot.AsyncTeleBot method),
set_game_score() (telebot.async_telebot.AsyncTeleBot 299
method), 295 set_sticker_set_thumb() (telebot.TeleBot method),
set_game_score() (telebot.TeleBot method), 200 204
set_message_reaction() (tele- set_sticker_set_thumbnail() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
295 299
set_message_reaction() (telebot.TeleBot method), set_sticker_set_thumbnail() (telebot.TeleBot
201 method), 205
set_my_commands() (tele- set_sticker_set_title() (tele-
bot.async_telebot.AsyncTeleBot method), bot.async_telebot.AsyncTeleBot method),
296 299
set_my_commands() (telebot.TeleBot method), 201 set_sticker_set_title() (telebot.TeleBot method),
set_my_default_administrator_rights() (tele- 205
bot.async_telebot.AsyncTeleBot method), set_update_listener() (tele-
296 bot.async_telebot.AsyncTeleBot method),
set_my_default_administrator_rights() (tele- 300
bot.TeleBot method), 202 set_update_listener() (telebot.TeleBot method), 205

338 Index
pyTelegramBotAPI, Release 4.25.0

set_user_emoji_status() (tele- T
bot.async_telebot.AsyncTeleBot method), telebot
300 module, 117
set_user_emoji_status() (telebot.TeleBot method), TeleBot (class in telebot), 118
205 telebot.async_telebot
set_webhook() (telebot.async_telebot.AsyncTeleBot module, 216
method), 300 telebot.asyncio_filters
set_webhook() (telebot.TeleBot method), 206 module, 306
setup_middleware() (tele- telebot.asyncio_handler_backends
bot.async_telebot.AsyncTeleBot method), module, 309
301 telebot.callback_data
setup_middleware() (telebot.TeleBot method), 207 module, 310
SharedUser (class in telebot.types), 101 telebot.custom_filters
shipping_query_handler() (tele- module, 211
bot.async_telebot.AsyncTeleBot method), telebot.formatting
301 module, 317
shipping_query_handler() (telebot.TeleBot method), telebot.handler_backends
207 module, 215
ShippingAddress (class in telebot.types), 101 telebot.types
ShippingOption (class in telebot.types), 102 module, 3
ShippingQuery (class in telebot.types), 102 telebot.util
SimpleCustomFilter (class in telebot.asyncio_filters), module, 311
307 TextContainsFilter (class in telebot.asyncio_filters),
SimpleCustomFilter (class in telebot.custom_filters), 308
213 TextContainsFilter (class in telebot.custom_filters),
skip_updates() (telebot.async_telebot.AsyncTeleBot 213
method), 302 TextFilter (class in telebot.asyncio_filters), 308
SkipHandler (class in tele- TextFilter (class in telebot.custom_filters), 214
bot.asyncio_handler_backends), 310 TextMatchFilter (class in telebot.asyncio_filters), 309
SkipHandler (class in telebot.handler_backends), 216 TextMatchFilter (class in telebot.custom_filters), 214
smart_split() (in module telebot.util), 315 TextQuote (class in telebot.types), 106
split_string() (in module telebot.util), 315 TextStartsFilter (class in telebot.asyncio_filters),
StarTransaction (class in telebot.types), 103 309
StarTransactions (class in telebot.types), 103 TextStartsFilter (class in telebot.custom_filters), 214
StateFilter (class in telebot.asyncio_filters), 308 thumb (telebot.types.Animation property), 4
StateFilter (class in telebot.custom_filters), 213 thumb (telebot.types.Audio property), 5
Sticker (class in telebot.types), 103 thumb (telebot.types.Document property), 34
StickerSet (class in telebot.types), 104 thumb (telebot.types.InputMediaAnimation property), 68
stop_bot() (telebot.TeleBot method), 207 thumb (telebot.types.InputMediaAudio property), 69
stop_message_live_location() (tele- thumb (telebot.types.InputMediaDocument property), 70
bot.async_telebot.AsyncTeleBot method), thumb (telebot.types.InputMediaVideo property), 71
302 thumb (telebot.types.Sticker property), 104
stop_message_live_location() (telebot.TeleBot thumb (telebot.types.StickerSet property), 105
method), 207 thumb (telebot.types.Video property), 114
stop_poll() (telebot.async_telebot.AsyncTeleBot thumb (telebot.types.VideoNote property), 115
method), 302 thumb_height (telebot.types.InlineQueryResultArticle
stop_poll() (telebot.TeleBot method), 208 property), 45
stop_polling() (telebot.TeleBot method), 208 thumb_height (telebot.types.InlineQueryResultContact
Story (class in telebot.types), 105 property), 54
SuccessfulPayment (class in telebot.types), 105 thumb_height (telebot.types.InlineQueryResultDocument
SwitchInlineQueryChosenChat (class in tele- property), 56
bot.types), 106 thumb_height (telebot.types.InlineQueryResultLocation
property), 58

Index 339
pyTelegramBotAPI, Release 4.25.0

thumb_height (telebot.types.InlineQueryResultVenue U
property), 61 unban_chat_member() (tele-
thumb_mime_type (telebot.types.InlineQueryResultGif bot.async_telebot.AsyncTeleBot method),
property), 57 303
thumb_mime_type (tele- unban_chat_member() (telebot.TeleBot method), 208
bot.types.InlineQueryResultMpeg4Gif prop- unban_chat_sender_chat() (tele-
erty), 59 bot.async_telebot.AsyncTeleBot method),
thumb_url (telebot.types.InlineQueryResultArticle prop- 303
erty), 45 unban_chat_sender_chat() (telebot.TeleBot method),
thumb_url (telebot.types.InlineQueryResultContact 208
property), 55 unhide_general_forum_topic() (tele-
thumb_url (telebot.types.InlineQueryResultDocument bot.async_telebot.AsyncTeleBot method),
property), 56 303
thumb_url (telebot.types.InlineQueryResultGif prop- unhide_general_forum_topic() (telebot.TeleBot
erty), 57 method), 209
thumb_url (telebot.types.InlineQueryResultLocation unpin_all_chat_messages() (tele-
property), 58 bot.async_telebot.AsyncTeleBot method),
thumb_url (telebot.types.InlineQueryResultMpeg4Gif 303
property), 59 unpin_all_chat_messages() (telebot.TeleBot
thumb_url (telebot.types.InlineQueryResultPhoto prop- method), 209
erty), 60 unpin_all_forum_topic_messages() (tele-
thumb_url (telebot.types.InlineQueryResultVenue prop- bot.async_telebot.AsyncTeleBot method),
erty), 61 304
thumb_url (telebot.types.InlineQueryResultVideo prop- unpin_all_forum_topic_messages() (tele-
erty), 63 bot.TeleBot method), 209
thumb_width (telebot.types.InlineQueryResultArticle unpin_all_general_forum_topic_messages()
property), 45 (telebot.async_telebot.AsyncTeleBot method),
thumb_width (telebot.types.InlineQueryResultContact 304
property), 55 unpin_all_general_forum_topic_messages()
thumb_width (telebot.types.InlineQueryResultDocument (telebot.TeleBot method), 209
property), 56 unpin_chat_message() (tele-
thumb_width (telebot.types.InlineQueryResultLocation bot.async_telebot.AsyncTeleBot method),
property), 58 304
thumb_width (telebot.types.InlineQueryResultVenue unpin_chat_message() (telebot.TeleBot method), 210
property), 61 Update (class in telebot.types), 109
to_dict() (telebot.types.CopyTextButton method), 33 update_sensitive (tele-
to_dict() (telebot.types.InputPaidMedia method), 71 bot.asyncio_handler_backends.BaseMiddleware
to_dict() (telebot.types.InputPaidMediaVideo attribute), 310
method), 72 update_sensitive (tele-
to_dict() (telebot.types.InputPollOption method), 73 bot.handler_backends.BaseMiddleware at-
to_list_of_dicts() (telebot.types.MessageEntity tribute), 215
static method), 87 update_types (in module telebot.util), 315
TransactionPartner (class in telebot.types), 107 upload_sticker_file() (tele-
TransactionPartnerAffiliateProgram (class in bot.async_telebot.AsyncTeleBot method),
telebot.types), 107 305
TransactionPartnerFragment (class in telebot.types), upload_sticker_file() (telebot.TeleBot method), 210
107 User (class in telebot.types), 111
TransactionPartnerOther (class in telebot.types), 108 user (telebot.async_telebot.AsyncTeleBot property), 305
TransactionPartnerTelegramAds (class in tele- user (telebot.TeleBot property), 210
bot.types), 108 user_id (telebot.types.UsersShared property), 113
TransactionPartnerTelegramApi (class in tele- user_ids (telebot.types.UsersShared property), 113
bot.types), 108 user_link() (in module telebot.util), 316
TransactionPartnerUser (class in telebot.types), 109 user_shared (telebot.types.Message property), 86
UserChatBoosts (class in telebot.types), 112

340 Index
pyTelegramBotAPI, Release 4.25.0

UserProfilePhotos (class in telebot.types), 112

UsersShared (class in telebot.types), 112

V
validate_token() (in module telebot.util), 316
validate_web_app_data() (in module telebot.util),
316
Venue (class in telebot.types), 113
verify_chat() (telebot.async_telebot.AsyncTeleBot
method), 305
verify_chat() (telebot.TeleBot method), 211
verify_user() (telebot.async_telebot.AsyncTeleBot
method), 305
verify_user() (telebot.TeleBot method), 211
Video (class in telebot.types), 113
VideoChatEnded (class in telebot.types), 114
VideoChatParticipantsInvited (class in tele-
bot.types), 114
VideoChatScheduled (class in telebot.types), 114
VideoChatStarted (class in telebot.types), 114
VideoNote (class in telebot.types), 115
Voice (class in telebot.types), 115
voice_chat_ended (telebot.types.Message property), 86
voice_chat_participants_invited (tele-
bot.types.Message property), 86
voice_chat_scheduled (telebot.types.Message prop-
erty), 86
voice_chat_started (telebot.types.Message property),
86
VoiceChatEnded (class in telebot.types), 115
VoiceChatParticipantsInvited (class in tele-
bot.types), 116
VoiceChatScheduled (class in telebot.types), 116
VoiceChatStarted (class in telebot.types), 116

W
WebAppData (class in telebot.types), 116
WebAppInfo (class in telebot.types), 116
webhook_google_functions() (in module tele-
bot.util), 316
WebhookInfo (class in telebot.types), 116
WriteAccessAllowed (class in telebot.types), 117

Index 341