Advanced Features
7. Advanced Features
Telebot Creator offers powerful advanced features that extend basic bot functionality. This section explores these capabilities, including custom data storage, scheduled tasks, integration with external systems, and managing user interactions, among others.
7.1 Scheduled Commands
Telebot Creator allows you to schedule commands to run at specific intervals, creating chatbots that can perform time-based tasks.
Bot.runCommandAfter
The Bot.runCommandAfter
function lets you schedule a command to run after a specific time delay.
Function Syntax:
Bot.runCommandAfter(
delay_seconds: float,
command: str,
user_id: Optional[str] = None,
chat_id: Optional[str] = None,
params: Optional[str] = None,
bot_id: Optional[str] = None,
api_key: Optional[str] = None
)
New in 4.9.0:
Maximum timeout extended to 1 year (365 days)
Minimum timeout reduced to 0.1 seconds
Smart rate limiting: For ultra-fast commands (under 0.4 seconds), a limit of 5 executions within 5 seconds to prevent abuse
Increased maximum scheduled commands per user from 20 to 100
Parameters:
delay_seconds
(float): The delay in seconds before executing the command. Range: 0.1 to 31,536,000 (365 days).command
(str): The command to execute after the delay.user_id
(Optional[str]): The user ID for which to execute the command.chat_id
(Optional[str]): The chat ID in which to execute the command.params
(Optional[str]): Parameters to pass to the command.bot_id
(Optional[str]): The bot ID for which to schedule the command.api_key
(Optional[str]): The API key for authentication with external bots.
Examples:
Basic Scheduling:
Bot.runCommandAfter(300, "reminder") # Run the reminder command after 5 minutes
User-Specific Scheduling:
Bot.runCommandAfter(3600, "daily_check", user_id=12345) # Run for specific user after 1 hour
With Parameters:
Bot.runCommandAfter(60, "send_reminder", params="meeting") # Pass parameters to the command
Long-term Scheduling:
# Schedule a command to run in 30 days (new in 4.9.0) Bot.runCommandAfter(2592000, "monthly_report")
Ultra-fast Task:
# Quick follow-up message (subject to rate limiting in 4.9.0) Bot.runCommandAfter(0.2, "send_followup")
7.2 Command Chaining for Workflows
Command chaining allows bots to create step-by-step workflows, guiding users through complex processes such as registration, surveys, or multi-step forms.
Example: Multi-Step Registration
Start the Workflow:
bot.sendMessage("Welcome! Let's start with your name.") Bot.handleNextCommand("get_name")
Process Name:
name = msg User.saveData("name", name) bot.sendMessage(f"Thanks, {name}! What is your email?") Bot.handleNextCommand("get_email")
Complete Registration:
email = msg User.saveData("email", email) bot.sendMessage("Your registration is complete!")
7.3 Custom API Integrations
With libs.customHTTP
, bots can interact with external APIs, enabling dynamic data fetching or triggering external processes.
Example: Weather Bot:
http_client = libs.customHTTP()
response = http_client.get("https://api.weatherapi.com/v1/current.json?key=API_KEY&q=New York")
weather_data = response.json()
bot.sendMessage(f"The current temperature in New York is {weather_data['current']['temp_c']}°C.")
http_client.close()
7.4 Webhook Management
The libs.Webhook
library facilitates real-time event handling, such as receiving external updates or triggering bot commands.
Example: Webhook for Payment Confirmation:
webhook_url = libs.Webhook.getUrlFor("payment_received", user_id=12345)
bot.sendMessage(f"Webhook URL: {webhook_url}")
7.5 Bot.Transfer Function
The Bot.Transfer
function allows you to transfer a bot from one Telebot Creator account to another. It ensures that the transferred bot retains its commands, configurations, and status while validating points and ownership.
Function Syntax
Bot.Transfer(email: str, bot_id: str, bot_token: Optional[str] = None, run_now: Optional[bool] = False) -> dict
Parameters
email
: The email address of the new owner.bot_id
: The unique ID of the bot to be transferred.bot_token
(optional): The Telegram Bot API token. Required ifrun_now
isTrue
.run_now
(optional): IfTrue
, starts the bot immediately under the new owner.
Validation and Requirements
The transferring user must own the bot (
bot_id
) being transferred.The new owner's email must exist on Telebot Creator.
The original account must have at least 200 points to initiate the transfer.
Usage Example
try:
result = Bot.Transfer(
email="<newowner>@example.com",
bot_id="123456",
bot_token="YOUR_BOT_API_TOKEN",
run_now=True
)
bot.sendMessage(f"Bot successfully transferred to {result['bot_id']}!")
except Exception as e:
bot.sendMessage(f"Error during transfer: {e}")
7.6 Bot.info() Function
The Bot.info()
function retrieves detailed information about a specific bot, including its status, owner details, points, and usage statistics.
Function Syntax
Bot.info(bot_id: Optional[str] = None, api_key: Optional[str] = None) -> dict
Parameters
bot_id
(optional): The ID of the bot to retrieve information for. If not provided, retrieves info for the current bot.api_key
(optional): The API key of the bot owner. Used for validation ifbot_id
is provided.
Information Returned
token
: The bot's API token.bot_id
: The unique ID of the bot.owner_email
: The email of the current bot owner.status
: The bot's current status (e.g., "Working", "Stopped").username
: The bot's Telegram username.first_name
: The bot's first name.account_points
: Remaining points in the owner's account.userstat
: Number of users interacting with the bot.
Usage Example
try:
details = Bot.info()
bot.sendMessage(f"Bot Name: {details.first_name}, Status: {details.status}")
except Exception as e:
bot.sendMessage(f"Error fetching bot info: {e}")
Validation
Returns structured and human-readable details about the bot.
7.7 Multi-Bot Management
For users managing multiple bots, Telebot Creator allows seamless integration between them.
Example: Interaction Between Two Bots
Bot A triggers Bot B via a webhook:
webhook_url = libs.Webhook.getUrlFor("bot_b_command", user_id=12345) bot.sendMessage(f"Triggering Bot B: {webhook_url}")
Bot B handles the webhook and sends a response:
bot.sendMessage("Response from Bot B!")
7.8 Advanced Error Handling
Implement advanced error-handling techniques to ensure smooth workflows.
Example:
try:
response = libs.customHTTP().get("https://invalid.url")
response.raise_for_status()
except Exception as e:
bot.sendMessage(f"Error occurred: {str(e)}")
7.9 Bot.Transfer (Expanded Use Cases)
1. Bot Migration Between Users
The Bot.Transfer
function allows seamless migration of bots from one account to another, ensuring no loss of functionality or data.
Real-World Scenario:
Use Case: A developer transfers a bot to a business partner who will manage the bot moving forward.
Example:
try: result = Bot.Transfer( email="[email protected]", bot_id="123456", bot_token="API_TOKEN", run_now=True ) bot.sendMessage(f"Bot successfully transferred! New Bot ID: {result['bot_id']}") except Exception as e: bot.sendMessage(f"Transfer failed: {e}")
2. Batch Transfer
Use the Bot.Transfer
function for multiple bots by iterating through bot IDs.
bots_to_transfer = ["123456", "654321"]
for bot_id in bots_to_transfer:
try:
Bot.Transfer(email="[email protected]", bot_id=bot_id, run_now=False)
bot.sendMessage(f"Bot ID {bot_id} transferred successfully.")
except Exception as e:
bot.sendMessage(f"Failed to transfer Bot ID {bot_id}: {e}")
7.10 Bot.info() (Expanded Details)
The Bot.info()
function is a powerful tool for retrieving comprehensive bot details. It provides insight into bot usage, configurations, and ownership.
Advanced Usage Scenarios
Bot Status Monitoring:
Periodically fetch and log bot statuses for analytics or troubleshooting.
details = Bot.info(bot_id="123456", api_key="VALID_API_KEY") bot.sendMessage(f"Bot {details.first_name} is currently {details.status}.")
Ownership Verification:
Verify bot ownership before performing sensitive operations.
details = Bot.info(bot_id="123456", api_key="VALID_API_KEY") if details.owner_email == "[email protected]": bot.sendMessage("Ownership verified.")
Integration with Dashboards:
Fetch bot stats for visual dashboards.
bot_stats = Bot.info(bot_id="123456", api_key="VALID_API_KEY") bot.sendMessage(f"Bot Username: {bot_stats.username}, Points Remaining: {bot_stats.account_points}")
7.11 Advanced API Integrations
1. Fetch and Process Data
Integrate third-party APIs dynamically using libs.customHTTP
.
Example: Fetching cryptocurrency prices.
http_client = libs.customHTTP()
response = http_client.get("https://api.coindesk.com/v1/bpi/currentprice/BTC.json")
price_data = response.json()
bot.sendMessage(f"Current Bitcoin Price: {price_data['bpi']['USD']['rate']}")
http_client.close()
2. Post Data to External Systems
Use POST requests to send data to external APIs.
http_client = libs.customHTTP()
response = http_client.post("https://api.example.com/submit", json={"user": "123", "action": "register"})
if response.status_code == 200:
bot.sendMessage("Data successfully submitted!")
http_client.close()
3. Automate Tasks Using Webhooks
Automatically trigger bot actions based on webhook updates.
webhook_url = libs.Webhook.getUrlFor("update_action", user_id=12345)
bot.sendMessage(f"Webhook URL for updates: {webhook_url}")
7.12 Multi-Bot Management (Expanded)
1. Orchestrating Bots
Enable communication between bots for advanced workflows.
Scenario: Bot A collects user data and triggers Bot B to send notifications.
Example:
Bot A collects data and calls Bot B's webhook:
webhook_url = libs.Webhook.getUrlFor( "notify_points", user_id=12345, # Don't add user_id if you don't want user specific webhook url bot_id="another_bot_id", api_key="another_bot_api_key" ) bot.sendMessage(f"Webhook URL for another bot: {webhook_url}")
Bot B processes the webhook:
bot.sendMessage("Notification sent via Bot B!")
2. Delegating Tasks
Use a primary bot to assign tasks to secondary bots.
bot_ids = ["bot_123", "bot_456"]
for bot_id in bot_ids:
Bot.runCommand(bot_id, "execute_task")
7.13 Enhanced Error Handling
Logging Errors for Debugging
Save errors to a persistent log for later review.
try:
risky_task()
except Exception as e:
error_message = f"An error occurred: {str(e)}"
Bot.saveData("last_error", error_message)
bot.sendMessage(error_message)
Custom Error Handlers
Define custom actions for specific errors.
try:
execute_critical_task()
except ValueError as ve:
bot.sendMessage(f"Value Error: {ve}")
except Exception as e:
bot.sendMessage(f"Unhandled Error: {e}")
7.14 Combining Features for Real-World Applications
Use Case: Survey Bot with API Integration
Step 1: Collect User Input
bot.sendMessage("What is your name?") Bot.handleNextCommand("collect_name")
Step 2: Process and Store Data
name = msg User.saveData("name", name) bot.sendMessage(f"Thank you, {name}. What's your email?") Bot.handleNextCommand("collect_email")
Step 3: Send Data to an API
email = msg User.saveData("email", email) http_client = libs.customHTTP() response = http_client.post( "https://api.example.com/register", json={"name": User.getData("name"), "email": email} ) if response.status_code == 200: bot.sendMessage("Registration successful!") http_client.close()
Use Case: Reward Bot with Multi-Bot Management
Bot A verifies user actions and updates points.
User.saveData("points", User.getData("points") + 10) bot.sendMessage("You've earned 10 points!")
Bot B notifies the user via a secondary bot:
webhook_url = libs.Webhook.getUrlFor("notify_points", user_id=12345) bot.sendMessage(f"Notification sent via webhook: {webhook_url}")
Last updated