# TPY Language Reference
### **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.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.Paytm**
* `setKeys(key, mid, token)`: Sets Paytm credentials.
* `send(amount, number, description=None)`: Transfers funds via Paytm.
**Example:**
```python
libs.Paytm.setKeys("merchant_key", "merchant_id", "auth_token")
libs.Paytm.send(100, "9876543210", "Payment for services")
```
**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)
```
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.telebotcreator.com/tpy-language-reference.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.