> For the complete documentation index, see [llms.txt](https://help.telebotcreator.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.telebotcreator.com/core-reference/tpy-language-reference.md).
# TPY Language Reference
*Telebot Creator Documentation — Platform v7.1.2 · Telegram Bot API 10.1*
*Last updated: June 2026 | Maintained by Telebot Creator Team*
### **4. TPY Language Reference**
TPY (Telebot Python) is the main programming language used in Telebot Creator (TBC). It is a simplified version of Python specifically designed for building Telegram bots. TPY offers a safe, efficient, and powerful environment for creating bots with built-in functions, global variables, and libraries.
#### **4.1 Overview of TPY**
* **Purpose**: TPY makes it easy to create bots by providing essential tools and structures to interact with users, manage data, and connect with external services.
* **Environment**: TPY runs in a secure, controlled environment to ensure your bots operate safely and efficiently.
* **Key Features**:
* **Built-in Libraries**: Pre-made modules for blockchain, payments, randomness, and more.
* **Pre-defined Globals**: Ready-to-use variables and functions for handling user interactions and bot tasks.
* **Command Chaining and Scheduling**: Run commands in a sequence or at specific times.
* **Telegram Update Handling**: Simplified system for processing both standard and special update types.
#### **4.1.1 Security and Restrictions**
TPY operates in a sandboxed environment for security reasons. Important security restrictions include:
* **No `eval()` or `exec()`**: These functions, which can execute arbitrary code at runtime, are deliberately unavailable to prevent security vulnerabilities.
* **No Access to System Modules**: Modules like `os`, `sys`, `subprocess`, etc., that could interact with the host system are restricted.
* **Limited File Access**: Files can only be accessed through provided APIs, not direct filesystem access.
* **Isolated Execution**: Each bot runs in its own isolated environment to prevent interference between bots.
These restrictions are not limitations but security features designed to:
1. Protect the TBC platform infrastructure
2. Prevent malicious code execution
3. Ensure one bot cannot access data from other bots
4. Provide a stable, reliable environment for all bots
You'll find that all legitimate bot functionality is available through safe, controlled APIs and the extensive library of available functions and globals.
#### **4.2 Allowed Built-ins**
TPY includes a limited set of Python's built-in functions to keep things simple and secure.
* **Data Types**: `str`, `int`, `float`, `bool`, `dict`, `list`, `set`
* **Utilities**: `len()`, `all()`, `any()`, `sum()`, `min()`, `max()`, `round()`, `sorted()`, `reversed()`, `enumerate()`
* **Type Checks**: `isinstance()`
* **Exceptions**: `ValueError`, `TypeError`, `IndexError`, `KeyError`, `NameError`, `ZeroDivisionError`
* **Math and Iteration**: `range()`, `abs()`, `zip()`, `ord()`
* **Other**: `map()`, `slice()`
| Built-in | Description |
| ---------------- | ------------------------------------------------------------------------ |
| **`abs`** | Returns the absolute value of a number. |
| **`all`** | Returns `True` if all elements in an iterable are true. |
| **`any`** | Returns `True` if any element in an iterable is true. |
| **`bin`** | Converts an integer to a binary string. |
| **`bool`** | Converts a value to a Boolean (`True` or `False`). |
| **`callable`** | Checks if an object is callable (e.g., a function). |
| **`chr`** | Converts an integer to a character. |
| **`divmod`** | Returns a tuple of the quotient and remainder when dividing two numbers. |
| **`enumerate`** | Returns an enumerator object with index-value pairs for an iterable. |
| **`filter`** | Filters elements in an iterable based on a function. |
| **`float`** | Converts a value to a floating-point number. |
| **`format`** | Formats a value using a specified format string. |
| **`getattr`** | Returns the value of an attribute for an object. |
| **`hasattr`** | Checks if an object has a specific attribute. |
| **`hash`** | Returns the hash value of an object. |
| **`hex`** | Converts an integer to a hexadecimal string. |
| **`id`** | Returns the unique identifier of an object. |
| **`int`** | Converts a value to an integer. |
| **`isinstance`** | Checks if an object is an instance of a specific class or type. |
| **`issubclass`** | Checks if a class is a subclass of another class. |
| **`iter`** | Returns an iterator for an iterable object. |
| **`len`** | Returns the length of an iterable object. |
| **`list`** | Creates a list from an iterable. |
| **`map`** | Applies a function to every item in an iterable. |
| **`max`** | Returns the largest item in an iterable. |
| **`min`** | Returns the smallest item in an iterable. |
| **`next`** | Retrieves the next item from an iterator. |
| **`oct`** | Converts an integer to an octal string. |
| **`ord`** | Returns the Unicode code point of a character. |
| **`pow`** | Returns the result of raising a number to a power. |
| **`range`** | Generates a sequence of numbers. |
| **`reversed`** | Returns a reversed iterator for a sequence. |
| **`round`** | Rounds a number to a specified number of decimal places. |
| **`set`** | Creates a set from an iterable. |
| **`slice`** | Creates a slice object for use in slicing operations. |
| **`sorted`** | Returns a sorted list from an iterable. |
| **`str`** | Converts a value to a string. |
| **`sum`** | Returns the sum of an iterable of numbers. |
| **`tuple`** | Creates a tuple from an iterable. |
| **`type`** | Returns the type of an object. |
| **`zip`** | Combines multiple iterables into a single iterable of tuples. |
#### **4.3 Allowed Globals**
TPY provides global objects and functions to help you build your bot without needing to define everything from scratch.
| **Global** | **Description** |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| **`msg`** | Contains the raw text content of an incoming message. |
| **`message`** | Represents the full Telegram update, including sender, chat, and message details. |
| **`bot`** | Low-level bot object for interacting with the Telegram Bot API. |
| **`Bot`** | High-level bot object with additional methods like broadcasting, saving data, etc. |
| **`base64`** | Provides utilities for encoding and decoding base64 data. |
| **`binascii`** | Contains functions to convert binary data to ASCII and vice versa. |
| **`hashlib`** | Provides secure hash functions like SHA256 and MD5. |
| **`User`** | A class for managing user-specific data (e.g., `User.saveData`, `User.getData`). |
| **`time`** | Provides utilities for working with time, including delays and timestamps. |
| **`bot_token`** | The current bot's Telegram Bot API token. |
| **`HTTP`** | A custom HTTP client for making API requests to external services. |
| **`regex` / `re`** | Allows pattern matching and regular expressions. |
| **`update_type`** | Indicates the type of the current update (e.g., "message", "callback\_query"). |
| **`CSV`** | A library for managing CSV files in the bot. |
| **`bunchify`** | Converts a dictionary into an object, allowing access via attributes. |
| **`bot_id`** | The unique identifier of the bot being used. |
| **`params`** | Stores additional parameters passed to a command (e.g., `/start referral_id`). |
| **`u`** | Represents the ID of the current user interacting with the bot. |
| **`options`** | Contains data passed to commands, such as webhook responses or additional input parameters. |
| **`left_points`** | Tracks the remaining points available for the bot in the current month. |
| **`isNumeric`** | A helper function to check if a value is numeric. |
| **`MembershipCheck`** | Verifies user membership in a group or channel. |
| **`encodejson`** | Encodes a dictionary into a JSON string. |
| **`bf_json`** | Converts JSON strings into Python dictionaries and vice versa. |
| **`ReturnCommand`** | Returns the output of a command to the bot. |
| **`parse_qs`** | Parses query strings into key-value pairs. |
| **`rawurlencode`** | Encodes URLs to ensure safe transmission of data. |
| **`decodeURIComponent`** | Decodes URI components into readable strings. |
| **`encodeURIComponent`** | Encodes URI components for safe transmission. |
| **`web3_`** | Provides tools for interacting with Ethereum-compatible blockchains. |
| **`md5`** | Generates MD5 hashes for data. |
| **`libs`** | Accesses libraries like `libs.CSV`, `libs.Coinbase`, `libs.Polygon`, etc. |
| **`jsondumps`** | Serializes Python objects into JSON strings. |
#### **4.4 TPY Classes**
TPY includes several classes that help manage different aspects of your bot. Below are the main classes with their methods and explanations.
**4.4.1 Bot Class (High-level)**
The `Bot` class offers advanced methods to manage bots, handle broadcasts, manage data, and more.
| **Method** | **Arguments** | **Description** |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Transfer` | `email` (Required), `bot_id` (Required), `bot_token` (Optional, default=None), `run_now` (Optional, default=False) | Moves a bot to another account and optionally starts it. |
| `broadcast` | `code` (Optional), `command` (Optional), `callback_url` (Optional), `bot_id` (Optional), `api_key` (Optional), `function` (Optional), `warnings` (Optional), `**kwargs` (Required) | Starts a broadcast or executes code for multiple users. |
| `clearBroadcast` | `broadcast_id` (Optional) | Clears broadcast records, optionally for a specific broadcast. |
| `deleteData` | `name` (Optional) | Removes a stored global data entry by name. |
| `genCaptcha` | `mode` (Required), `captcha` (Optional) | Creates a captcha (manual or automatic) and returns its info. |
| `genId` | None | Generates a unique numeric identifier. |
| `genRandomErrorId` | None | Creates a random error ID for logging or tracking. |
| `genRandomId` | None | Generates a random ID, often for new bots or references. |
| `getAllBroadcasts` | None | Retrieves a list of all broadcasts associated with the bot. |
| `getBroadcastStatus` | `broadcast_id` (Required) | Gets the current status of a specific broadcast. |
| `getData` | `name` (Optional) | Retrieves a stored global data value by name. |
| `getIpnUrl` | `command` (Required), `user_id` (Optional), `url` (Optional) | Provides an IPN URL for a command, useful for payments or callbacks. |
| `getIpnUrlForCoinbase` | `command` (Required) | Generates a Coinbase-specific IPN URL for a command. |
| `handleNextCommand` | `command` (Required), `options` (Optional), `cancel_at_command`(Optional) | Sets up a future command to run after the user's next response. |
| `info` | `bot_id` (Optional), `api_key` (Optional) | Provides detailed information about the bot's setup and status. |
| `runCommand` | `command` (Required), `options` (Optional) | Executes another command within the same bot, optionally with options. |
| `runCommandAfter` | `timeout` (Required), `command` (Required), `options` (Optional), `id`(Optional) | Schedules a command to run after a certain delay. |
| `saveData` | `name` (Required), `data` (Required) | Stores global data under a specific name. |
| `start` | `bot_id` (Required), `api_key` (Required) | Starts a bot if conditions like sufficient points are met. |
| `status` | `bot_id` (Required), `api_key` (Required) | Checks or updates the bot's current status. |
| `stop` | `bot_id` (Required), `api_key` (Required) | Stops a running bot. |
| `stopBroadcast` | `broadcast_id` (Required) | Stops an ongoing broadcast. |
| `getDataFile` | `name` (Required), `output_format` (Optional, default="txt") | Retrieves global data as a file that can be sent to users. |
| `getAllData` | `name` (Required), `output_format` (Optional, default="json") | Retrieves all global data entries matching a name pattern as a file. Note: Only works with data saved after 4.7.0 update. |
| `getBotUsersFile` | `output_format` (Optional, default="json"), `include_creation_date` (Optional, default=False), `include_last_active_date` (Optional, default=False) | Retrieves information about all bot users as a file (CSV or JSON). |
**Example Usage:**
```python
# Transfer a bot to another account and start it
bot.Transfer(email="user@example.com", bot_id="12345", run_now=True)
# Start a broadcast
bot.broadcast(command="send_newsletter", function="broadcast_news")
# Generate a unique ID
unique_id = bot.genId()
```
**4.4.2 Bot Class (Low-level)**
The low-level `bot` class provides methods for more specific actions like managing stickers, handling queries, and interacting with chats. While **camelCase** is the preferred naming convention for methods, **snake\_case** is also supported.
| **Method** | **Arguments** | **Description** |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `addStickerToSet` | `user_id` (Required), `name` (Required), `emojis` (Required), `png_sticker` (Optional), `tgs_sticker` (Optional), `webm_sticker` (Optional), `mask_position` (Optional), `sticker`(Optional) | Adds a new sticker to an existing sticker set. |
| `answerCallbackQuery` | `callback_query_id` (Required), `text` (Optional), `show_alert`(Optional), `url` (Optional), `cache_time` (Optional) | Replies to a callback query from an inline keyboard. |
| `answerInlineQuery` | `inline_query_id` (Required), `results` (Required), `cache_time`(Optional), `is_personal` (Optional), `next_offset` (Optional), `switch_pm_text` (Optional), `switch_pm_parameter` (Optional), `button` (Optional) | Sends results for an inline query. |
| `answerPreCheckoutQuery` | `pre_checkout_query_id` (Required), `ok` (Required), `error_message` (Optional) | Responds to a pre-checkout query during payment. |
| `answerShippingQuery` | `shipping_query_id` (Required), `ok` (Required), `shipping_options` (Optional), `error_message` (Optional) | Replies to a shipping query with options or an error. |
| `answerWebAppQuery` | `web_app_query_id` (Required), `result` (Required) | Provides a result to a Web App query. |
| `approveChatJoinRequest` | `chat_id` (Required), `user_id` (Required) | Approves a user's request to join a chat. |
| `banChatMember` | `chat_id` (Required), `user_id` (Required), `until_date`(Optional), `revoke_messages` (Optional) | Bans a user from a chat. |
| `banChatSenderChat` | `chat_id` (Required), `sender_chat_id` (Required) | Bans a channel or chat sender from a group or channel. |
| `close` | None | Closes the bot's session if needed. |
| `closeForumTopic` | `chat_id` (Required), `message_thread_id` (Required) | Closes a forum topic in a chat. |
| `closeGeneralForumTopic` | `chat_id` (Required) | Closes the general forum topic in a chat. |
| `copyMessage` | `chat_id` (Required), `from_chat_id` (Required), `message_id`(Required), `caption` (Optional), `parse_mode` (Optional), `caption_entities` (Optional), `disable_notification`(Optional), `protect_content` (Optional), `reply_to_message_id` (Optional), `allow_sending_without_reply` (Optional), `reply_markup`(Optional), `timeout` (Optional), `message_thread_id` (Optional), `reply_parameters` (Optional), `show_caption_above_media`(Optional), `allow_paid_broadcast` (Optional) | Copies a single message to another chat without sending a link. |
| `copyMessages` | `chat_id` (Required), `from_chat_id` (Required), `message_ids`(Required), `disable_notification` (Optional), `message_thread_id` (Optional), `protect_content` (Optional), `remove_caption` (Optional) | Copies multiple messages to another chat. |
| `createChatInviteLink` | `chat_id` (Required), `name` (Optional), `expire_date` (Optional), `member_limit` (Optional), `creates_join_request` (Optional) | Creates a new chat invite link with optional limits. |
| `createChatSubscriptionInviteLink` | `chat_id` (Required), `subscription_period` (Required), `subscription_price` (Required), `name` (Optional) | Creates a subscription-based chat invite link. |
| `createForumTopic` | `chat_id` (Required), `name` (Required), `icon_color` (Optional), `icon_custom_emoji_id` (Optional) | Creates a forum topic in a chat. |
| `createInvoiceLink` | `title` (Required), `description` (Required), `invoice_payload`(Required), `provider_token` (Required), `currency` (Required), `prices` (Required), `max_tip_amount` (Optional), `suggested_tip_amounts` (Optional), `provider_data`(Optional), `photo_url` (Optional), `photo_size` (Optional), `photo_width` (Optional), `photo_height` (Optional), `need_name`(Optional), `need_phone_number` (Optional), `need_email`(Optional), `need_shipping_address` (Optional), `send_phone_number_to_provider` (Optional), `send_email_to_provider` (Optional), `is_flexible` (Optional) | Generates a link for an invoice, allowing external payment. |
| `createNewStickerSet` | `user_id` (Required), `name` (Required), `title` (Required), `emojis`(Optional), `png_sticker` (Optional), `tgs_sticker` (Optional), `webm_sticker` (Optional), `contains_masks` (Optional), `sticker_type` (Optional), `mask_position` (Optional), `needs_repainting` (Optional), `stickers` (Optional), `sticker_format` (Optional) | This method wouldn't work on TBC for now we expect it to work in next updates.
Creates a new sticker set under a user's account.
|
| `declineChatJoinRequest` | `chat_id` (Required), `user_id` (Required) | Declines a pending join request to a chat. |
| `deleteChatPhoto` | `chat_id` (Required) | Deletes a chat's profile photo. |
| `deleteChatStickerSet` | `chat_id` (Required) | Removes a sticker set from a chat. |
| `deleteForumTopic` | `chat_id` (Required), `message_thread_id` (Required) | Deletes an entire forum topic. |
| `deleteMessage` | `chat_id` (Required), `message_id` (Required), `timeout`(Optional) | Removes a single message from a chat. |
| `deleteMessages` | `chat_id` (Required), `message_ids` (Required) | Removes multiple messages from a chat. |
| `deleteMyCommands` | `scope` (Optional), `language_code` (Optional) | Deletes the bot's current list of commands. |
| `deleteStickerFromSet` | `sticker` (Required) | Removes a sticker from a sticker set. |
| `deleteStickerSet` | `name` (Required) | Deletes an entire sticker set. |
| `downloadFile` | `file_path` (Required) | Downloads a file from Telegram servers. |
| `editChatInviteLink` | `chat_id` (Required), `invite_link` (Optional), `name` (Optional), `expire_date` (Optional), `member_limit` (Optional), `creates_join_request` (Optional) | Modifies an existing chat invite link's parameters. |
| `editChatSubscriptionInviteLink` | `chat_id` (Required), `invite_link` (Required), `name` (Optional) | Updates a subscription invite link's properties. |
| `editForumTopic` | `chat_id` (Required), `message_thread_id` (Required), `name`(Optional), `icon_custom_emoji_id` (Optional) | Edits forum topic details like name or icon. |
| `editGeneralForumTopic` | `chat_id` (Required), `name` (Required) | Edits the general forum topic's name in a chat. |
| `editMessageCaption` | `caption` (Required), `optional parameters` | Changes the caption of a sent message. |
| `editMessageLiveLocation` | `latitude` (Required), `longitude` (Required), `optional parameters` | Updates the coordinates of a live location message. |
| `editMessageMedia` | `media` (Required), `optional parameters` | Replaces the media of an existing message. |
| `editMessageReplyMarkup` | `optional parameters` | Updates the inline keyboard markup of a message. |
| `editMessageText` | `text` (Required), `optional parameters` | Modifies the text content of a sent message. |
| `exportChatInviteLink` | `chat_id` (Required) | Generates a new primary invite link for a chat. |
| `forwardMessage` | `chat_id` (Required), `from_chat_id` (Required), `message_id`(Required), `optional parameters` | Forwards a single message from one chat to another. |
| `forwardMessages` | `chat_id` (Required), `from_chat_id` (Required), `message_ids`(Required), `optional parameters` | Forwards multiple messages to another chat. |
| `getBusinessConnection` | `business_connection_id` (Required) | Retrieves information about a specific business connection. |
| `getChat` | `chat_id` (Required) | Fetches details about a chat. |
| `getChatAdministrators` | `chat_id` (Required) | Lists chat administrators. |
| `getChatMember` | `chat_id` (Required), `user_id` (Required) | Retrieves information about a specific chat member. |
| `getChatMemberCount` | `chat_id` (Required) | Gets the number of members in a chat. |
| `getChatMembersCount` | `chat_id` (Required) | Provides the chat member count (legacy method). |
| `getChatMenuButton` | `chat_id` (Optional) | Retrieves the current menu button in a chat. |
| `getCustomEmojiStickers` | `custom_emoji_ids` (Required) | Fetches stickers for given custom emoji IDs. |
| `getFile` | `file_id` (Required) | Obtains file information for a given file ID. |
| `getFileUrl` | `file_id` (Required) | Generates a direct download URL for a file. |
| `getForumTopicIconStickers` | None | Retrieves stickers suitable for forum topic icons. |
| `getGameHighScores` | `user_id` (Required), `optional parameters` | Gets high scores of users in a game. |
| `getMyCommands` | `scope` (Optional), `language_code` (Optional) | Retrieves the bot's currently set commands. |
| `getMyDefaultAdministratorRights` | `for_channels` (Optional) | Obtains the bot's default admin rights. |
| `getMyDescription` | `language_code` (Optional) | Gets the bot's description text. |
| `getMyName` | `language_code` (Optional) | Retrieves the bot's configured name. |
| `getMyShortDescription` | `language_code` (Optional) | Gets the bot's short description. |
| `getStarTransactions` | `offset` (Optional), `limit` (Optional) | Retrieves recorded star transactions (platform-specific). |
| `getStickerSet` | `name` (Required) | Fetches the details of a sticker set. |
| `getUserChatBoosts` | `chat_id` (Required), `user_id` (Required) | Gets chat boost information for a user. |
| `getUserProfilePhotos` | `user_id` (Required), `offset` (Optional), `limit` (Optional) | Retrieves a user's profile photos. |
| `hideGeneralForumTopic` | `chat_id` (Required) | Hides the general forum topic from view. |
| `kickChatMember` | `chat_id` (Required), `user_id` (Required), `optional parameters` | Kicks a member from a chat, optionally until a future time. |
| `leaveChat` | `chat_id` (Required) | The bot leaves the specified chat. |
| `pinChatMessage` | `chat_id` (Required), `message_id` (Required), `optional parameters` | Pins a message in the chat. |
| `promoteChatMember` | `chat_id` (Required), `user_id` (Required), `optional parameters` | Promotes a user to an admin or adjusts their admin privileges. |
| `refundStarPayment` | `user_id` (Required), `telegram_payment_charge_id` (Required) | Issues a refund for a star payment (platform-specific). |
| `reopenForumTopic` | `chat_id` (Required), `message_thread_id` (Required) | Reopens a previously closed forum topic. |
| `reopenGeneralForumTopic` | `chat_id` (Required) | Reopens the general forum topic in a chat. |
| `replaceStickerInSet` | `user_id` (Required), `name` (Required), `old_sticker` (Required), `sticker` (Required) | Replaces an existing sticker in a set with another. |
| `replyPhoto` | `chat_id` (Required), `photo` (Required), `optional parameters` | Sends a photo in reply to a message. |
| `replyText` | `chat_id` (Required), `text` (Required), `optional parameters` | Sends a text message in reply to another message. |
| `replyTo` | `message` (Required), `text` (Required), `kwargs` (Required) | Quickly replies to a given message with text and options. |
| `restrictChatMember` | `chat_id` (Required), `user_id` (Required), `optional parameters` | Restricts what a user can do in a chat. |
| `revokeChatInviteLink` | `chat_id` (Required), `invite_link` (Required) | Revokes an existing chat invite link. |
| `sendAnimation` | `animation` (Required), `optional parameters` | Sends an animation (like a GIF) to a chat. |
| `sendAudio` | `audio` (Required), `optional parameters` | Sends an audio file (music, podcast) to a chat. |
| `sendChatAction` | `action` (Required), `optional parameters` | Shows a chat action (e.g., typing) to the user. |
| `sendContact` | `phone_number` (Required), `first_name` (Required), `optional parameters` | Shares a contact's information with a chat. |
| `sendDice` | `optional parameters` | Sends a dice emoji message that shows a random value. |
| `sendDocument` | `document` (Required), `optional parameters` | Sends a document or file to a chat. |
| `sendGame` | `game_short_name` (Required), `optional parameters` | Shares a game link in a chat. |
| `sendInvoice` | `title` (Required), `description` (Required), `invoice_payload`(Required), `provider_token` (Required), `currency` (Required), `prices` (Required), `optional parameters` | Sends an invoice for payment to a user. |
| `sendLocation` | `latitude` (Required), `longitude` (Required), `optional parameters` | Shares a geographic location in a chat. |
| `sendMediaGroup` | `media` (Required), `optional parameters` | Sends multiple media items as an album. |
| `sendMessage` | `text` (Required), `optional parameters` | Sends a text message to a chat. |
| `sendPaidMedia` | `star_count` (Required), `media` (Required), `optional parameters` | Sends media that requires a star payment (platform-specific). |
| `sendPhoto` | `photo` (Required), `optional parameters` | Sends a photo to a chat. |
| `sendPoll` | `question` (Required), `options` (Required), `optional parameters` | Creates and sends a poll to the chat. |
| `sendSticker` | `sticker` (Required), `optional parameters` | Sends a sticker to a chat. |
| `sendVenue` | `latitude` (Required), `longitude` (Required), `title` (Required), `address` (Required), `optional parameters` | Shares a venue's location and details. |
| `sendVideo` | `video` (Required), `optional parameters` | Sends a video file to a chat. |
| `sendVideoNote` | `data` (Required), `optional parameters` | Sends a video note (circular video) to a chat. |
| `setChatAdministratorCustomTitle` | `chat_id` (Required), `user_id` (Required), `custom_title`(Required) | Sets a custom admin title for a chat member. |
| `setChatDescription` | `chat_id` (Required), `description` (Optional) | Updates the chat's description text. |
| `setChatMenuButton` | `chat_id` (Optional), `menu_button` (Optional) | Sets the menu button for a chat or globally. |
| `setChatPermissions` | `chat_id` (Required), `permissions` (Required), `use_independent_chat_permissions` (Optional) | Configures chat-wide permissions for all members. |
| `setChatPhoto` | `chat_id` (Required), `photo` (Required) | Updates the chat's profile photo. |
| `setChatStickerSet` | `chat_id` (Required), `sticker_set_name` (Required) | Assigns a sticker set to a chat. |
| `setChatTitle` | `chat_id` (Required), `title` (Required) | Changes the chat's title. |
| `setCustomEmojiStickerSetThumbnail` | `name` (Required), `custom_emoji_id` (Optional) | Sets a custom emoji as a sticker set's thumbnail. |
| `setGameScore` | `user_id` (Required), `score` (Required), `optional parameters` | Updates the score of a user in a game. |
| `setMessageReaction` | `chat_id` (Required), `message_id` (Required), `reaction`(Optional), `is_big` (Optional) | Adds or updates a reaction (emoji) to a message. |
| `setMyCommands` | `commands` (Required), `scope` (Optional), `language_code`(Optional) | Sets the bot's list of commands. |
| `setMyDefaultAdministratorRights` | `rights` (Optional), `for_channels` (Optional) | Defines the bot's default admin rights. |
| `setMyDescription` | `description` (Optional), `language_code` (Optional) | Updates the bot's description. |
| `setMyName` | `name` (Optional), `language_code` (Optional) | Sets the bot's name. |
| `setMyShortDescription` | `short_description` (Optional), `language_code` (Optional) | Sets a short description for the bot. |
| `setStickerEmojiList` | `sticker` (Required), `emoji_list` (Required) | Assigns an emoji list to a sticker. |
| `setStickerKeywords` | `sticker` (Required), `keywords` (Optional) | Adds keywords to a sticker for better searchability. |
| `setStickerMaskPosition` | `sticker` (Required), `mask_position` (Optional) | Defines a mask position for a sticker. |
| `setStickerPositionInSet` | `sticker` (Required), `position` (Required) | Changes a sticker's position in its set. |
| `setStickerSetThumb` | `name` (Required), `user_id` (Required), `thumb` (Optional) | Sets the thumbnail for a sticker set. |
| `setStickerSetThumbnail` | `name` (Required), `user_id` (Required), `thumbnail` (Optional), `format` (Optional) | Sets or changes the thumbnail for a sticker set with extra options. |
| `setStickerSetTitle` | `name` (Required), `title` (Required) | Changes the title of a sticker set. |
| `stopMessageLiveLocation` | `optional parameters` | Stops an ongoing live location update. |
| `stopPoll` | `chat_id` (Required), `message_id` (Required), `optional parameters` | Ends a currently active poll in a chat. |
| `unbanChatMember` | `chat_id` (Required), `user_id` (Required), `only_if_banned`(Optional) | Unbans a previously banned user. |
| `unbanChatSenderChat` | `chat_id` (Required), `sender_chat_id` (Required) | Unbans a previously banned channel sender. |
| `unhideGeneralForumTopic` | `chat_id` (Required) | Makes the general forum topic visible again. |
| `unpinAllChatMessages` | `chat_id` (Required) | Unpins all pinned messages in a chat. |
| `unpinAllForumTopicMessages` | `chat_id` (Required), `message_thread_id` (Required) | Unpins all messages in a forum topic. |
| `unpinAllGeneralForumTopicMessages` | `chat_id` (Required) | Unpins all messages in the general forum topic. |
| `unpinChatMessage` | `chat_id` (Required), `message_id` (Optional), `business_connection_id` (Optional) | Unpins a specific message in the chat. |
| `uploadStickerFile` | `user_id` (Required), `png_sticker` (Optional), `sticker`(Optional), `sticker_format` (Optional) | Uploads a file for sticker creation. |
**Note:** While **camelCase** is the preferred method naming convention in TPY, **snake\_case** method names (e.g., `send_message`) are also supported for flexibility.
**Example Usage:**
```python
# Approve a user's join request
bot.approve_chat_join_request(chat_id=123456789, user_id=789012345)
# Send a welcome photo
bot.sendPhoto(chat_id=123456789, photo="https://ibb.co/kyjq5Tm", caption="Welcome to the group!")
```
**4.4.3 Telegram Bot API 8.x – 10.1 Methods**
TBC now tracks **Telegram Bot API 10.1**. The following methods were added on top of the 7.x baseline above. They follow the same naming rules — call them in **camelCase** (e.g. `bot.getAvailableGifts()`) or **snake\_case** (e.g. `bot.get_available_gifts()`). As with the rest of TBC, media parameters take a Telegram `file_id`, a public URL, or a structured `dict` — local file uploads are not supported in the sandbox.
| **Method** | **Arguments** | **Description** |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `getAvailableGifts` | None | Returns the list of gifts the bot can send. |
| `sendGift` | `gift_id` (Required), `user_id` (Optional), `chat_id` (Optional), `pay_for_upgrade` (Optional), `text` (Optional), `text_parse_mode` (Optional), `text_entities` (Optional) | Sends a gift to a user or channel chat. |
| `giftPremiumSubscription` | `user_id` (Required), `month_count` (Required), `star_count` (Required), `text` (Optional), `text_parse_mode` (Optional), `text_entities` (Optional) | Gifts a Telegram Premium subscription to a user, paid in Stars. |
| `getUserGifts` | `user_id` (Required), `exclude_unlimited` (Optional), `exclude_limited_upgradable` (Optional), `exclude_limited_non_upgradable` (Optional), `exclude_from_blockchain` (Optional), `exclude_unique` (Optional), `sort_by_price` (Optional), `offset` (Optional), `limit` (Optional) | Lists gifts received by a user. |
| `convertGiftToStars` | `business_connection_id` (Required), `owned_gift_id` (Required) | Converts a received gift back into Telegram Stars. |
| `upgradeGift` | `business_connection_id` (Required), `owned_gift_id` (Required), `keep_original_details` (Optional), `star_count` (Optional) | Upgrades a regular gift to a unique gift. |
| `transferGift` | `business_connection_id` (Required), `owned_gift_id` (Required), `new_owner_chat_id` (Required), `star_count` (Optional) | Transfers an owned unique gift to another chat. |
| `postStory` | `business_connection_id` (Required), `content` (Required), `active_period` (Required), `caption` (Optional), `parse_mode` (Optional), `caption_entities` (Optional), `areas` (Optional), `post_to_chat_page` (Optional), `protect_content` (Optional) | Posts a story on behalf of a managed business account. |
| `editStory` | `business_connection_id` (Required), `story_id` (Required), `content` (Required), `caption` (Optional), `parse_mode` (Optional), `caption_entities` (Optional), `areas` (Optional) | Edits a previously posted story. |
| `deleteStory` | `business_connection_id` (Required), `story_id` (Required) | Deletes a story posted by a business account. |
| `readBusinessMessage` | `business_connection_id` (Required), `chat_id` (Required), `message_id` (Required) | Marks an incoming business-account message as read. |
| `setBusinessAccountName` | `business_connection_id` (Required), `first_name` (Required), `last_name` (Optional) | Sets the connected business account's name. |
| `setBusinessAccountUsername` | `business_connection_id` (Required), `username` (Optional) | Sets the business account's username. |
| `setBusinessAccountBio` | `business_connection_id` (Required), `bio` (Optional) | Sets the business account's bio. |
| `setBusinessAccountProfilePhoto` | `business_connection_id` (Required), `photo` (Required), `is_public` (Optional) | Sets the business account's profile photo. |
| `removeBusinessAccountProfilePhoto` | `business_connection_id` (Required), `is_public` (Optional) | Removes the business account's profile photo. |
| `setBusinessAccountGiftSettings` | `business_connection_id` (Required), `show_gift_button` (Required), `accepted_gift_types` (Required) | Configures which gift types the business account accepts. |
| `getBusinessAccountStarBalance` | `business_connection_id` (Required) | Returns the business account's Star balance. |
| `transferBusinessAccountStars` | `business_connection_id` (Required), `star_count` (Required) | Transfers Stars from the business account to the bot. |
| `sendChecklist` | `business_connection_id` (Required), `checklist` (Required), `chat_id` (Optional), `disable_notification` (Optional), `protect_content` (Optional), `message_effect_id` (Optional), `reply_parameters` (Optional), `reply_markup` (Optional) | Sends a checklist message (business accounts). |
| `editMessageChecklist` | `business_connection_id` (Required), `message_id` (Required), `checklist` (Required), `chat_id` (Optional), `reply_markup` (Optional) | Edits an existing checklist message. |
| `approveSuggestedPost` | `chat_id` (Required), `message_id` (Required), `send_date` (Optional) | Approves a suggested post in a direct-messages channel. |
| `declineSuggestedPost` | `chat_id` (Required), `message_id` (Required), `comment` (Optional) | Declines a suggested post. |
| `verifyUser` | `user_id` (Required), `custom_description` (Optional) | Verifies a user on behalf of an organization. |
| `verifyChat` | `chat_id` (Required), `custom_description` (Optional) | Verifies a chat on behalf of an organization. |
| `removeUserVerification` | `user_id` (Required) | Removes a user's verification. |
| `removeChatVerification` | `chat_id` (Required) | Removes a chat's verification. |
| `getMyStarBalance` | None | Returns the bot's own Telegram Star balance. |
| `editUserStarSubscription` | `user_id` (Required), `telegram_payment_charge_id` (Required), `is_canceled` (Required) | Cancels or re-enables a user's Star subscription. |
| `deleteMessageReaction` | `chat_id` (Required), `message_id` (Required), `user_id` (Optional), `actor_chat_id` (Optional) | Removes a reaction from a message. |
| `deleteAllMessageReactions` | `chat_id` (Required), `user_id` (Optional), `actor_chat_id` (Optional) | Removes all reactions from a message. |
| `sendRichMessage` | `rich_message` (Required), `business_connection_id` (Optional), plus standard send options | **TBC-custom** — sends a rich (structured) message. |
| `sendLivePhoto` | `live_photo` (Required), `photo` (Required), `business_connection_id` (Optional), plus standard send options | **TBC-custom** — sends a live photo. |
> **Note:** Gift, Story, and Business-account methods require a **business connection** (`business_connection_id`) from a user who has linked their account to your bot. `sendGift` / `getAvailableGifts` / `getMyStarBalance` work with the bot's own token.
**Example — list and send a gift:**
```python
# List the gifts the bot can send
gifts = bot.getAvailableGifts()
# Send the first available gift to the current user
if gifts and gifts.gifts:
bot.sendGift(gift_id=gifts.gifts[0].id, user_id=u, text="Enjoy! 🎁")
# Check the bot's Star balance
balance = bot.getMyStarBalance()
bot.sendMessage(f"Bot Star balance: {balance.amount}")
```
#### **4.5 Libraries (libs)**
TPY offers various libraries to extend your bot's functionality. These libraries provide pre-built modules for tasks like payments, blockchain transactions, data handling, and more.
**1. Payment Libraries**
* **libs.Coinbase**
* `setKeys(api_key, secret)`: Sets Coinbase API keys.
* `post(api_key=None, secret=None)`: Initializes a Coinbase client.
**Example:**
```python
libs.Coinbase.setKeys("your_api_key", "your_secret_key")
client = libs.Coinbase.post()
```
* **libs.Coinpayments**
* `setKeys(public_key, private_key)`: Sets CoinPayments API credentials.
* `post()`: Returns a configured CoinPayments API client.
**Example:**
```python
libs.Coinpayments.setKeys("public_key", "private_key")
client = libs.Coinpayments.post()
```
**2. Blockchain Libraries**
* **libs.Polygon**
* `setKeys(private_key)`: Sets your private key for Polygon transactions.
* `send(value, to, contract, private_key=None)`: Sends tokens via a contract.
* `sendPolygon(value, to, private_key=None)`: Sends MATIC tokens.
**Example:**
```python
libs.Polygon.setKeys("your_private_key")
libs.Polygon.sendPolygon(2.0, "recipient_wallet_address")
```
* **libs.web3lib**
* `setKeys(private_key)`: Sets your private key for web3 transactions.
* `sendETHER(value, to, contract, rpc_url, gasPrice=None, private_key=None)`: Sends Ether or tokens.
* `sendPolygon(value, to, private_key=None)`: Sends MATIC tokens.
**Example:**
```python
libs.web3lib.setKeys("your_private_key")
libs.web3lib.sendETHER(1, "recipient_wallet_address", "contract_address", "https://rpc_url")
```
**3. Utility Libraries**
* **libs.Random**
* `randomInt(min, max)`: Returns a random integer.
* `randomStr(length, char_set=None)`: Generates a random string.
* `randomFloat(min, max)`: Returns a random float.
* `randomAscii(length)`: Returns a random ASCII string.
**Example:**
```python
random_number = libs.Random.randomInt(1, 100)
bot.sendMessage(f"Your random number is: {random_number}")
random_string = libs.Random.randomStr(8)
bot.sendMessage(f"Your random string is: {random_string}")
```
* **libs.CSV**
* `create_csv(headers)`: Creates a CSV file.
* `add_row(row)`: Adds a row to the CSV.
* `edit_row(row_index, row)`: Edits an existing row.
* `get()`: Retrieves information about the CSV file.
* `delete()`: Deletes the CSV file.
**Example:**
```python
csv = libs.CSV.CSVHandler("data.csv")
csv.create_csv(["Name", "Points", "Date"])
csv.add_row({"Name": "Alice", "Points": 100, "Date": "2025-01-01"})
```
#### **4.6 Examples**
Here are some examples of how to use TPY to create and manage your bots effectively.
**1. Sending a Welcome Message**
```python
bot.sendMessage("Welcome to the bot!")
```
**2. Get User Points**
```python
points = left_points
bot.sendMessage(f"You have {points} points remaining.")
```
**3. Scheduling a Reminder**
in the /set\_reminder command:
```python
bot.sendMessage("Reminder set for 5 seconds later.")
bot.runCommandAfter(5, "send_reminder")
```
In the send\_reminder command:
```python
bot.sendMessage("This is your reminder!")
```
#### **4.7 Handling Telegram Updates**
TPY provides a structured system for handling different types of Telegram updates. Understanding how to process these updates is essential for creating responsive and versatile bots.
**4.7.1 Update Types in Telegram**
Telegram sends various types of updates to your bot when events occur. These updates fall into two categories:
1. **Normal Updates**: The most common update types that are directly handled by standard command names
2. **Special Updates**: Less common update types that require special handler commands
**Normal Updates include:**
* `message` - Regular text or media messages sent by users
* `callback_query` - Responses from inline keyboard buttons
**Special Updates include:**
```
edited_message, channel_post, edited_channel_post, business_connection, business_message,
edited_business_message, deleted_business_messages, message_reaction, message_reaction_count,
inline_query, chosen_inline_result, shipping_query, pre_checkout_query, purchased_paid_media,
poll, poll_answer, my_chat_member, chat_member, chat_join_request, chat_boost, removed_chat_boost
```
**4.7.2 Handling Normal Updates**
Normal updates (`message` and `callback_query`) can be handled directly using standard command names:
```python
# /start command handles message updates with text "/start"
# Command name in TBC: /start
bot.sendMessage("Welcome to my bot!")
# /joined command handles new chat join events
# Command name in TBC: /joined
bot.sendMessage("Welcome to the group!")
# command for handling callback queries named "show_profile"
# Command name in TBC: show_profile (callback data name)
bot.answerCallbackQuery(callback_query_id=message.id, text="Loading profile...")
```
**4.7.3 Handling Special Updates**
Special updates require specific handler commands using the pattern: `/handler_`
For example:
```python
# Command name in TBC: /handler_edited_message
# This processes edited_message updates
edited_text = message.text
bot.sendMessage(f"You edited your message to: {edited_text}")
```
```python
# Command name in TBC: /handler_inline_query
# This processes inline_query updates
query = message.query
results = [...] # Define your inline results
bot.answerInlineQuery(inline_query_id=message.id, results=results)
```
```python
# Command name in TBC: /handler_chat_join_request
# Handles chat join requests
user_id = message.from_user.id
bot.approveChatJoinRequest(chat_id=message.chat.id, user_id=user_id)
```
**4.7.4 Handling All Special Updates**
If you want a single command to handle all special update types, you can create a command named `/handler_special_updates`:
```python
# Command name in TBC: /handler_special_updates
# This processes all special update types
update_type = update_type # The global variable that contains the current update type
if update_type == "edited_message":
# Handle edited messages
bot.sendMessage("You edited a message")
elif update_type == "inline_query":
# Handle inline queries
query = message.query
results = [...] # Define your inline results
bot.answerInlineQuery(inline_query_id=message.id, results=results)
elif update_type == "chat_join_request":
# Handle join requests
bot.approveChatJoinRequest(chat_id=message.chat.id, user_id=message.from_user.id)
# Add handlers for other special update types as needed
```
**4.7.5 Accessing Update Type Information**
In any command, you can access the current update type using the global variable `update_type`. This is especially useful in the `/handler_special_updates` command:
```python
# Check what kind of update we're processing
current_update = update_type
bot.sendMessage(f"Processing update type: {current_update}")
```
This system gives you flexible control over how your bot handles different Telegram events, allowing for more interactive and responsive bot experiences.
#### **Summary**
TPY is a simple yet powerful language designed for building Telegram bots with Telebot Creator. By using its built-in functions, global variables, and libraries, you can create interactive and feature-rich bots tailored to your needs.
***
**4.4.3 User Class**
The `User` class provides methods for managing user-specific data.
| **Method** | **Arguments** | **Description** |
| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `saveData` | `name` (Required), `data` (Required), `user` (Optional) | Saves user-specific data under a given name. |
| `getData` | `name` (Required), `user` (Optional) | Retrieves user-specific data by name. |
| `deleteData` | `name` (Required), `user` (Optional) | Removes user-specific data by name. |
| `getDataFile` | `name` (Required), `user` (Optional), `output_format` (Optional, default="txt") | Retrieves user data as a file that can be sent to users. |
| `getAllData` | `name` (Required), `output_format` (Optional, default="json") | Gets all data entries that match a specific name pattern as a file. |
| `getAllDataOfUser` | `user` (Required), `output_format` (Optional, default="json") | Retrieves all data associated with a specific user as a file. |
**Example Usage:**
```python
# Save user data
User.saveData("profile", {"name": "Alice", "age": 30})
# Get user data
profile = User.getData("profile")
bot.sendMessage(f"User profile: {profile}")
# Get user data as a file
profile_file = User.getDataFile("profile")
bot.sendDocument(profile_file)
# Get all data for a specific user
all_user_data = User.getAllDataOfUser("12345678")
bot.sendDocument(all_user_data)
```
***