# Botlify Cloud — Complete Developer Documentation & API Reference

> Full-text consolidated knowledge base for AI agents, LLM tool executors, and developers.
> Platform: Botlify Cloud (https://botlify.cloud)
> Documentation: https://docs.botlify.cloud
> Last Updated: 2026-10-07 05:42:08 UTC

---

# 1. Welcome to Botlify Cloud

**Category:** Getting Started  
**URL:** https://docs.botlify.cloud/?page=overview  
**Summary:** High-performance, zero-config cloud hosting and developer studio for Telegram bots. (3 min read)  

## What is Botlify Cloud?

      

**Botlify Cloud** is a modern, enterprise-grade cloud hosting and orchestration platform built specifically for Telegram bots. It eliminates the traditional headaches of server provisioning, SSL certificates, webhook registration, and database management, allowing you to deploy production-ready bots in under 60 seconds.

      
> [!TIP]
> **Instant Live Webhooks**
> Botlify automatically configures HTTPS SSL webhooks with Telegram's servers the instant you provide a token. No manual webhook URLs or SSL certificates needed!

      

## Core Platform Highlights

      
        
- **Zero-Config PHP 8.2+ Runtime:** High-speed execution with OPcache and native cURL optimization.

        
- **Isolated Per-Bot Sandboxes:** Each bot runs in its own directory with dedicated files, dependencies, and independent storage quotas (15 MB+ per bot).

        
- **Embedded SQLite 3 Studio:** Integrated database engine running WAL mode for lightning-fast concurrent reads and writes with zero database configuration.

        
- **AI Model Context Protocol (MCP) Server:** Connect your favorite AI IDEs (Cursor, Windsurf, Claude Desktop, Antigravity) to manage bots, edit code, query databases, and deploy autonomously.

        
- **Integrated Webhook Simulator:** Test bot commands, simulated `/start` payloads, and inspect error logs without triggering live Telegram messages.

        
- **Automated Cron Scheduler:** Schedule background workers (e.g. daily claim resets, cleanup tasks, notifications) down to 1-minute intervals.

      

      

## Platform Architecture at a Glance

      
        
| Component | Specification | Description |
| --- | --- | --- |
| Runtime | PHP 8.2+ / 8.3 CLI & FPM | Isolated sandbox process with strict error reporting and fast execution. |
| Storage | NVMe SSD Isolated Folders | 15 MB default dedicated quota per bot; upgradable via referrals and admin. |
| Database | SQLite 3 with WAL Mode | Zero-maintenance relational database included with every bot (database.db). |
| AI Integration | MCP (Model Context Protocol) | Standard JSON-RPC 2.0 / SSE endpoint at /mcp.php for AI agents. |
| Security | Protected .env & Sandboxing | Hardware-isolated credentials with automatic access control and secret masking. |

---

# 2. 60-Second Quickstart

**Category:** Getting Started  
**URL:** https://docs.botlify.cloud/?page=quickstart  
**Summary:** Deploy your first Telegram bot from scratch to live production in 60 seconds. (2 min read)  

## Prerequisites

      

Before launching your first bot, ensure you have:

      
        
- An active account on [Botlify Cloud](https://botlify.cloud/login.php).

        
- A Telegram account to chat with **@BotFather**.

      

      

## Step 1: Obtain Bot Token from @BotFather

      

Open Telegram and search for `@BotFather`. Send the command `/newbot` and follow the interactive prompts:

      
      
```php
/newbot
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
My First Cloud Bot
Good. Now let's choose a username for your bot. It must end in 'bot'. Like this, for example: TetrisBot or tetris_bot.
my_first_cloud_bot
Done! Congratulations on your new bot. You will find it at t.me/my_first_cloud_bot.
Use this token to access the HTTP API:
7123456789:AAHq_EXAMPLE_TOKEN_ABC123XYZ
```

      

## Step 2: Deploy on Botlify Cloud

      
        
- Navigate to your [Botlify Dashboard](https://botlify.cloud/dashboard.php).

        
- Click the **Deploy Bot** (or **+ New Bot**) button in the top navigation bar.

        
- Paste your Telegram Bot Token into the input field.

        
- Select your preferred bot scaffold (e.g. *Styled Keyboards & Dashboard* or *Refer-to-Earn Bot*).

        
- Click **Deploy Bot Now**.

      

      
> [!TIP]
> **Instant Webhook Activation**
> Botlify immediately registers the Telegram Webhook and sets up the native menu button. Click the generated t.me/... link and press /start to interact with your live bot!

---

# 3. Configuring @BotFather

**Category:** Getting Started  
**URL:** https://docs.botlify.cloud/?page=botfather  
**Summary:** Complete guide to setting bot profile photo, descriptions, slash commands, and privacy settings. (4 min read)  

## Essential @BotFather Commands

      

Telegram's official `@BotFather` provides extensive settings to brand and configure your bot. Here is the master command cheatsheet:

      
        
| Command | Purpose | Example / Usage |
| --- | --- | --- |
| /setname | Changes the public display name of your bot. | Botlify Demo Bot |
| /setdescription | Sets the text shown on the empty chat screen before pressing Start. | Introduces features and why users should tap Start. |
| /setabouttext | Sets the bio shown on the bot's profile card. | Brief 120-character summary. |
| /setuserpic | Uploads the avatar profile picture for your bot. | Send a high-resolution square image. |
| /setcommands | Registers the slash command autocomplete popup. | start - Launch bot help - Support |
| /setjoingroups | Controls whether your bot can be added to Telegram groups. | Enable or Disable. |
| /setprivacy | Toggles group privacy mode (receive all messages vs mentions only). | Disable if your bot must read all group chat text. |

      

      
> [!NOTE]
> **Automated Command Registration**
> Botlify bots automatically call setMyCommands and setChatMenuButton on startup, so your slash commands and blue [Menu] button are configured automatically without manual setup!

---

# 4. Obtaining Telegram Admin Chat ID

**Category:** Getting Started  
**URL:** https://docs.botlify.cloud/?page=admin-chat-id  
**Summary:** How to find your numeric User ID and link it to your Botlify account for full administrative control. (2 min read)  

## Why is Admin Chat ID Required?

      

In Telegram, every account has a permanent numeric identifier (e.g. `7642872720`). Unlike usernames (which can be changed anytime), numeric IDs never change.

      

Botlify injects your `ADMIN_CHAT_ID` into your bot's `.env` file. When an incoming message arrives, your bot compares `$from['id'] === ADMIN_CHAT_ID` to grant privileged admin powers, such as:

      
        
- Broadcasting messages to all bot users.

        
- Viewing financial withdrawals, balances, and system stats.

        
- Approving or rejecting user tasks.

        
- Accessing hidden administrative slash commands (e.g. `/admin`, `/stats`).

      

      

## How to Find Your Numeric ID

      
        
- Open Telegram and search for [@chat_id_echo_bot](https://t.me/chat_id_echo_bot) or [@userinfobot](https://t.me/userinfobot).

        
- Send `/start`.

        
- The bot will reply with your exact numeric ID (e.g. `Your ID: 7642872720`).

        
- Copy this number, visit your **Account & API Key** tab in Botlify Dashboard, and paste it into **Telegram Admin ID**.

---

# 5. Code Studio & Web IDE

**Category:** Bot Studio & Development  
**URL:** https://docs.botlify.cloud/?page=editor  
**Summary:** Edit multi-file codebases in real-time with syntax highlighting, automatic linting, and zero deployment latency. (4 min read)  

## The In-Browser Cloud IDE

      

Botlify includes a full-featured web code editor located in **Bot Studio → Code Editor**. You can view, create, edit, and organize multiple files right from your browser or mobile device.

      

## Key Studio Features

      
        
- **Multi-File Project Support:** Create modular projects with helper files (e.g. `includes/database.php`, `handlers/callback.php`).

        
- **Real-Time Syntax Validation:** Before saving, Botlify runs strict PHP syntax checks. If a parse or syntax error is found, it warns you immediately to prevent breaking live production webhooks.

        
- **Zero-Restart Hot Reloading:** Changes saved to `index.php` are active immediately on the next incoming Telegram update. No server restarts or redeployment delays required!

      

      

## Standard Starter Template Structure

      
```php

```

---

# 6. SQLite 3 Studio & Data Explorer

**Category:** Bot Studio & Development  
**URL:** https://docs.botlify.cloud/?page=sqlite-studio  
**Summary:** Built-in zero-maintenance relational database engine with visual SQL query console and automatic WAL mode. (4 min read)  

## Zero-Maintenance Database Architecture

      

Every bot on Botlify Cloud comes pre-provisioned with its own dedicated SQLite 3 database located at `database.db`. Unlike MySQL or PostgreSQL, SQLite requires no external ports, usernames, or passwords. It operates at native memory speed right on high-speed NVMe SSDs.

      

## Connecting via PDO in PHP

      
```php
$db = new PDO('sqlite:' . __DIR__ . '/database.db', null, null, [
    PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC
]);

// Enable WAL Mode for High Concurrency
$db->exec("PRAGMA journal_mode = WAL;");
$db->exec("PRAGMA busy_timeout = 5000;");

// Create Standard Users Table
$db->exec("CREATE TABLE IF NOT EXISTS users (
    chat_id TEXT PRIMARY KEY,
    username TEXT,
    first_name TEXT,
    balance REAL DEFAULT 0.00,
    interactions INTEGER DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);");
```

      

## Using the Visual Database Studio

      

Inside **Bot Studio → Database**, you have access to:

      
        
- **Schema Explorer:** View all tables, column types, and primary keys.

        
- **Interactive SQL Console:** Run any query (`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `ALTER TABLE`) with formatted result tables.

        
- **Live Data Browser:** Inspect user records, balances, and interaction logs with pagination and search.

---

# 7. Automated Cron Scheduler

**Category:** Bot Studio & Development  
**URL:** https://docs.botlify.cloud/?page=cron-jobs  
**Summary:** Schedule background workers, reset daily rewards, and send automated notifications without external cron services. (3 min read)  

## Platform Cron Engine

      

Bots often need to execute background operations at recurring intervals — such as resetting daily login streaks at midnight, executing pending payouts, or cleaning up expired sessions.

      

Botlify includes a native Cron Scheduler running at 1-minute intervals. You can configure cron jobs directly in **Bot Studio → Variables & Cron**.

      

## Supported Crontab Expressions

      
        
| Expression | Frequency | Description |
| --- | --- | --- |
| * * * * * | Every 1 Minute | Runs once every minute (minimum platform interval). |
| */5 * * * * | Every 5 Minutes | Standard for transaction monitoring and queue processing. |
| 0 * * * * | Hourly | Runs at minute 0 of every hour. |
| 0 0 * * * | Daily Midnight | Runs once per day at 00:00 UTC (ideal for daily bonus resets). |

      

      

## Writing a Standalone Cron Script

      

Create a dedicated file such as `cron_worker.php` in your bot's folder:

      
      
```php

```

---

# 8. Webhook Manager & Test Simulator

**Category:** Bot Studio & Development  
**URL:** https://docs.botlify.cloud/?page=webhook-diagnostics  
**Summary:** Simulate Telegram webhook payloads, test logic in-browser, and inspect live execution errors. (3 min read)  

## The Test Simulator

      

Debugging webhook endpoints usually requires sending messages on Telegram and checking remote error logs. With Botlify's built-in **Webhook Test Simulator**, you can simulate updates instantly inside Bot Studio.

      

## How Simulation Works

      
        
- Open **Bot Studio → Overview** or **Variables & Cron**.

        
- Click **Simulate /start Webhook**.

        
- Botlify sends an authentic Telegram update payload to your bot's `index.php` script via local execution.

        
- The simulator displays the full execution output, runtime duration, memory usage, and the last 10 lines of `error.log`.

      

      
> [!WARNING]
> **Inspect error.log Instantly**
> If your bot code throws a fatal exception or uncaught error, it is recorded in error.log. The studio flags the bot card with a red alert badge so you can resolve issues immediately.

---

# 9. Native Commands & [Menu] Button

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=commands-menu  
**Summary:** Configure slash command autocompletes, admin-only command scopes, and the persistent blue [Menu] button. (4 min read)  

## Registering Commands with setMyCommands

      

Telegram allows bots to register slash commands that appear in a popup menu when the user types `/`. In Botlify, we configure them automatically or on demand using `setMyCommands`:

      
```php
function setup_bot_commands(): void {
    // 1. General User Commands (All Private Chats)
    bot('setMyCommands', [
        'commands' => [
            ['command' => 'start',    'description' => '🚀 Launch main dashboard'],
            ['command' => 'menu',     'description' => '📋 Open interactive menu'],
            ['command' => 'balance',  'description' => '💰 View account balance'],
            ['command' => 'support',  'description' => '💬 Contact live support']
        ],
        'scope' => ['type' => 'all_private_chats']
    ]);

    // 2. Admin Only Commands
    bot('setMyCommands', [
        'commands' => [
            ['command' => 'admin',     'description' => '👑 Open Admin Control Center'],
            ['command' => 'broadcast', 'description' => '📢 Send mass broadcast to users'],
            ['command' => 'stats',     'description' => '📊 View platform telemetrics']
        ],
        'scope' => ['type' => 'chat', 'chat_id' => ADMIN_CHAT_ID]
    ]);

    // 3. Set the Persistent Blue [Menu] Button
    bot('setChatMenuButton', [
        'menu_button' => ['type' => 'commands']
    ]);
}
```

---

# 10. Animated Message Reactions

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=reactions  
**Summary:** React to incoming user messages with animated emojis (👍, 🔥, 🎉, ❤️, ⚡) using setMessageReaction. (3 min read)  

## The setMessageReaction Method

      

Telegram Bot API supports adding emoji reactions directly to user messages. This provides instant visual feedback before sending text replies.

      
```php
function react(string|int $chatId, int $messageId, string $emoji = '👍', bool $isBig = true): array {
    return bot('setMessageReaction', [
        'chat_id'    => $chatId,
        'message_id' => $messageId,
        'reaction'   => [
            ['type' => 'emoji', 'emoji' => $emoji]
        ],
        'is_big'     => $isBig
    ]);
}

// Usage Example on user message
if (!empty($msg['text'])) {
    react($chatId, $msg['message_id'], '🔥', true);
}
```

      

## Popular Supported Emojis

      

Standard Unicode emojis supported by Telegram reactions: 👍, 👎, ❤️, 🔥, 🎉, 🤩, 👏, 😁, 🤔, 🤯, 😱, 🤬, 💩, ⚡, 🍌, 🍓, 🍾.

---

# 11. Mandatory Force-Subscribe System

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=force-subscribe  
**Summary:** Protect bot features by requiring users to join your official Telegram channel or group before proceeding. (4 min read)  

## How Force-Subscribe Works

      
        
- Add your bot as an **Administrator** in your official channel or group.

        
- When a user sends `/start`, call `getChatMember` with your channel ID and the user's ID.

        
- Inspect the returned `status`. If status is `left` or `kicked`, block access and present a Join Channel button with a *"Check Membership"* callback.

      

      
```php
function is_subscribed(string|int $userId, string|int $channelId): bool {
    $res = bot('getChatMember', [
        'chat_id' => $channelId,
        'user_id' => $userId
    ]);
    if (empty($res['ok'])) return false;
    $status = $res['result']['status'] ?? '';
    return in_array($status, ['creator', 'administrator', 'member', 'restricted'], true);
}

// In your webhook handler:
define('REQUIRED_CHANNEL', '@BotlifyOfficial');

if (!is_subscribed($chatId, REQUIRED_CHANNEL)) {
    bot('sendMessage', [
        'chat_id'    => $chatId,
        'text'       => "⚠️ Access Restricted!

You must join our official channel to use this bot.",
        'parse_mode' => 'HTML',
        'reply_markup' => [
            'inline_keyboard' => [
                [['text' => '📢 Join Channel', 'url' => 'https://t.me/BotlifyOfficial']],
                [['text' => '🔄 Verify Membership', 'callback_data' => 'check_sub']]
            ]
        ]
    ]);
    exit('ok');
}
```

---

# 12. Telegram Stars & Paid Subscriptions

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=stars-subscriptions  
**Summary:** Accept Telegram Stars digital currency and configure recurring subscription periods using createInvoiceLink. (4 min read)  

## Monetizing with Telegram Stars

      

Telegram Stars (⭐️) allow users to pay for digital goods, services, and monthly subscriptions inside bots without third-party payment gateways.

      
```php
function create_stars_subscription(string $title, string $description, int $starsPrice, int $periodSeconds = 2592000): string {
    $res = bot('createInvoiceLink', [
        'title'               => $title,
        'description'         => $description,
        'payload'             => 'sub_' . bin2hex(random_bytes(8)),
        'currency'            => 'XTR', // Official Telegram Stars Currency Code
        'prices'              => [
            ['label' => $title, 'amount' => $starsPrice]
        ],
        'subscription_period' => $periodSeconds // 2592000 = 30 days recurring
    ]);
    return $res['result'] ?? '';
}
```

---

# 13. Full-Screen Message Effects

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=message-effects  
**Summary:** Trigger full-screen celebration fireworks, flames, and hearts using message_effect_id. (2 min read)  

## The message_effect_id Parameter

      

Telegram Bot API 8.x introduced full-screen animation effects that cover the entire chat screen when a message arrives. Use the `message_effect_id` parameter in `sendMessage`.

      
        
| Effect ID | Animation Type | Best Used For |
| --- | --- | --- |
| 5046509860389126442 | 🎉 Celebration & Confetti | Welcome bonuses, payment completions, winning rewards. |
| 5104841245755180586 | 🔥 Burning Flames | Level ups, high streaks, hot broadcasts. |
| 5107584321108051014 | ❤️ Floating Hearts | Thank you messages, donations, gifts. |
| 5104858069142078847 | 👍 Thumbs Up Explosion | Approvals, confirmed orders, task completions. |

      

      
```php
function send_effect(string|int $chatId, string $text, string $effectId = '5046509860389126442'): array {
    return bot('sendMessage', [
        'chat_id'           => $chatId,
        'text'              => $text,
        'parse_mode'        => 'HTML',
        'message_effect_id' => $effectId
    ]);
}
```

---

# 14. Model Context Protocol (MCP) Integration

**Category:** AI Agent & MCP Integration  
**URL:** https://docs.botlify.cloud/?page=mcp-overview  
**Summary:** Supercharge your development workflow by connecting AI assistants directly to your Botlify Cloud workspace. (5 min read)  

## What is the Botlify MCP Server?

      

The **Model Context Protocol (MCP)** is an open standard that allows AI models (in Cursor, Windsurf, Claude Desktop, Antigravity) to safely interface with external developer tools and data stores.

      

Botlify Cloud includes a built-in MCP server endpoint located at `https://botlify.cloud/mcp.php?api_key=YOUR_API_KEY`. When connected, AI agents can autonomously:

      
        
- Inspect and list your active hosted bots.

        
- Read, write, edit, and create multi-file bot projects.

        
- Run live SQLite database queries (`SELECT`, `INSERT`, `UPDATE`) directly on bot databases.

        
- Simulate webhook updates to verify that generated code works with 0 syntax errors.

        
- Manage environment variables, scheduled cron jobs, and mass broadcasts.

      

      

## Connecting Your Favorite AI Editor

      
```php
{
  "mcpServers": {
    "botlify-cloud": {
      "url": "https://botlify.cloud/mcp.php?api_key=YOUR_BOTLIFY_API_KEY"
    }
  }
}
```

      
> [!TIP]
> **Find Your API Key**
> Open your Botlify Dashboard → Account & API Key to copy your unique personal developer key.

---

# 15. Complete MCP Tool Catalog

**Category:** AI Agent & MCP Integration  
**URL:** https://docs.botlify.cloud/?page=mcp-tools  
**Summary:** Comprehensive reference of all 20+ Model Context Protocol tools supported by the Botlify Cloud engine. (6 min read)  

## Master Tool Reference

      

AI assistants have access to the following categorized tools over JSON-RPC 2.0:

      
        
| Tool Name | Arguments | Description |
| --- | --- | --- |
| list_bots | status (optional: all, active, paused) | Lists all hosted bots with usernames, IDs, webhooks, and storage metrics. |
| get_bot | bot (ID or @username) | Fetches complete metadata, files, environment variables, and database info. |
| create_bot | bot_token, admin_chat_id | Provisions a new isolated bot sandbox with webhook auto-configured. |
| list_files | bot, dir (optional) | Lists files and directories inside the bot's workspace. |
| read_file | bot, file | Reads file contents (e.g. index.php, config.php). |
| write_file | bot, file, content | Overwrites or creates a file with automatic PHP syntax linting. |
| db_query | bot, query, params | Executes SQL queries against the bot's live SQLite database.db. |
| test_bot_webhook | bot, update (optional) | Simulates a webhook execution and returns stdout and error logs. |
| get_bot_making_guide | None | Retrieves the 50-section Telegram Bot API master guide for AI reasoning. |

---

# 16. Dedicated Per-Bot Storage Architecture

**Category:** Storage & Architecture  
**URL:** https://docs.botlify.cloud/?page=per-bot-storage  
**Summary:** Understanding Botlify's isolated storage quota model and NVMe SSD sandbox limits. (3 min read)  

## Independent Per-Bot Quotas

      

In Botlify Cloud, storage limits are **allocated individually per bot**, not shared across your entire fleet.

      
      
> [!NOTE]
> **Default Quota: 15 MB Per Bot**
> If you have 10 bots, you receive 10 separate 15 MB environments (totaling 150 MB across your fleet). Each bot operates with its own file and database limits independently.

      

## What Counts Towards Bot Storage?

      
        
- **PHP Source Code & Assets:** `index.php`, custom scripts, helper classes, icons, or JSON files.

        
- **SQLite Database:** The file size of `database.db` and its temporary WAL journal files.

        
- **Error Logs:** Output recorded in `error.log`.

      

      

## Upgrading Storage Quotas

      

Need more storage for media-heavy bots or large SQLite databases? You can expand your per-bot quota by:

      
        
- **Inviting Referrals:** Every active referral adds extra storage and bot slots to your account.

        
- **Contacting Support:** Administrators can assign custom high-capacity quotas (50 MB, 100 MB, 500 MB+) per user or per bot.

---

# 17. Styled Keyboards & Buttons

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=keyboards  
**Summary:** Create interactive inline buttons, reply keyboards, pagination, and multi-row grids. (4 min read)  

## Inline vs. Reply Keyboards

      

Telegram supports two types of interactive keyboards:

      
        
- **Inline Keyboards:** Attached directly below specific messages. Tapping them triggers callback queries (`callback_query`) or opens external URLs.

        
- **Reply Keyboards:** Displayed in place of the user's regular device keyboard. Tapping them sends regular text messages or requests special data (contacts, location, users).

      

      

## Rich Inline Keyboard Grid Example

      
```php
bot('sendMessage', [
    'chat_id'      => $chatId,
    'text'         => "🎛 Control Panel Dashboard:
Select an option below:",
    'parse_mode'   => 'HTML',
    'reply_markup' => [
        'inline_keyboard' => [
            [
                ['text' => '💰 Balance', 'callback_data' => 'view_balance'],
                ['text' => '🎁 Daily Bonus', 'callback_data' => 'claim_bonus']
            ],
            [
                ['text' => '👥 Referrals', 'callback_data' => 'referrals'],
                ['text' => '🏆 Leaderboard', 'callback_data' => 'leaderboard']
            ],
            [
                ['text' => '🌐 Open Web App', 'web_app' => ['url' => 'https://botlify.cloud']],
                ['text' => '💬 Support', 'url' => 'https://t.me/botlify_support']
            ]
        ]
    ]
]);
```

      

## Answering Callback Queries

      

When a user taps an inline button, always call `answerCallbackQuery` immediately to dismiss Telegram's loading spinner:

      
```php
if (isset($update['callback_query'])) {
    $cb = $update['callback_query'];
    bot('answerCallbackQuery', [
        'callback_query_id' => $cb['id'],
        'text'              => 'Action processed successfully!',
        'show_alert'        => false
    ]);
}
```

---

# 18. Media, Videos & Stickers

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=media-stickers  
**Summary:** Send photos, audio, videos with custom covers and start timestamps, and animated stickers. (3 min read)  

## Enhanced Video Controls (API 8.x)

      

Telegram allows setting custom video cover thumbnails and opening videos at a specific playback second:

      
```php
bot('sendVideo', [
    'chat_id'         => $chatId,
    'video'           => 'https://example.com/demo.mp4',
    'caption'         => '🎬 Watch Product Demo (Starts at 15s)',
    'parse_mode'      => 'HTML',
    'cover'           => 'https://example.com/thumbnail.jpg',
    'start_timestamp' => 15 // Starts playback at 00:15
]);
```

      

## Sending Animated & Static Stickers

      

Stickers can be sent using their permanent Telegram `file_id`:

      
```php
bot('sendSticker', [
    'chat_id' => $chatId,
    'sticker' => 'CAACAgIAAxkBAAE...sticker_file_id...'
]);
```

---

# 19. Seamless Telegram Web OAuth Login

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=web-oauth  
**Summary:** Authenticate Telegram users onto web applications seamlessly with one tap using login_url. (3 min read)  

## The login_url Parameter

      

Instead of requiring users to enter passwords or 2FA codes on your website, you can attach a `login_url` button in Telegram chat. When clicked, Telegram securely prompts the user and passes verified user data via GET parameters to your auth endpoint.

      
```php
bot('sendMessage', [
    'chat_id'      => $chatId,
    'text'         => "🔐 Access Your Web Dashboard:
Click below to log in securely without entering credentials.",
    'parse_mode'   => 'HTML',
    'reply_markup' => [
        'inline_keyboard' => [
            [
                [
                    'text'      => '🚀 One-Click Web Login',
                    'login_url' => [
                        'url'                => 'https://botlify.cloud/login.php?telegram_oauth=1',
                        'forward_text'       => 'Log in to Botlify Cloud',
                        'request_write_access' => true
                    ]
                ]
            ]
        ]
    ]
]);
```

---

# 20. Chat Join Requests & Auto-Approval

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=join-requests  
**Summary:** Automatically approve or decline private channel and group join requests with instant welcome direct messages. (3 min read)  

## The chat_join_request Update

      

When users request to join private channels or invite-only groups, Telegram sends a `chat_join_request` update to your bot rather than a regular message.

      
```php
// Detect and Process Join Requests
if (isset($update['chat_join_request'])) {
    $req = $update['chat_join_request'];
    $chatId = $req['chat']['id'];
    $userId = $req['from']['id'];
    $userName = htmlspecialchars($req['from']['first_name'] ?? 'Friend', ENT_QUOTES, 'UTF-8');

    // 1. Instantly Approve the Join Request
    bot('approveChatJoinRequest', [
        'chat_id' => $chatId,
        'user_id' => $userId
    ]);

    // 2. Send Personalized Welcome Direct Message
    bot('sendMessage', [
        'chat_id'    => $userId,
        'text'       => "🎉 Welcome {$userName}!
Your request to join our channel has been automatically approved.",
        'parse_mode' => 'HTML',
        'reply_markup' => [
            'inline_keyboard' => [
                [['text' => '🚀 Launch Bot Dashboard', 'url' => 'https://t.me/' . BOT_USERNAME]]
            ]
        ]
    ]);

    exit('ok');
}
```

      

## Decline Join Requests

      

If a user is banned or does not meet membership conditions, you can call `declineChatJoinRequest`:

      
```php
bot('declineChatJoinRequest', [
    'chat_id' => $chatId,
    'user_id' => $userId
]);
```

---

# 21. Complete Master API Reference (A to Z)

**Category:** Telegram Bot API (A-Z)  
**URL:** https://docs.botlify.cloud/?page=api-matrix  
**Summary:** Comprehensive reference matrix covering all 100+ Telegram Bot API 8.x methods. (8 min read)  

## Alphabetical Methods Directory

      

The following table lists the most frequently implemented Telegram Bot API methods supported on Botlify Cloud:

      
        
| Method Name | HTTP Type | Description |
| --- | --- | --- |
| answerCallbackQuery | POST | Sends response to callback button tap to clear spinner. |
| approveChatJoinRequest | POST | Approves user request to join channel or group. |
| banChatMember | POST | Bans user from group, supergroup, or channel. |
| copyMessage / copyMessages | POST | Copies messages without link to original author. |
| createChatInviteLink | POST | Generates dynamic invite link with expiration/join limits. |
| createInvoiceLink | POST | Creates payment link for Telegram Stars or crypto invoices. |
| deleteMessage | POST | Deletes bot or user message in chat. |
| editMessageText | POST | Edits text and inline keyboard of existing message. |
| forwardMessage / forwardMessages | POST | Forwards messages from any chat. |
| getChatMember | POST | Checks user status in chat (crucial for Force-Subscribe). |
| getFile | POST | Retrieves file path for downloading photos, audio, documents. |
| getUserProfilePhotos | POST | Fetches user avatar profile pictures. |
| sendChatAction | POST | Shows 'typing...', 'upload_photo' indicators to users. |
| sendGift | POST | Sends Telegram digital gift to user or channel. |
| sendMessage | POST | Primary method to dispatch text messages with HTML/Markdown. |
| sendPhoto | POST | Sends images with optional caption and buttons. |
| sendSticker | POST | Sends animated (TGS), video (WEBM), or static stickers. |
| sendVideo | POST | Sends MP4 videos with custom cover and start timestamps. |
| setChatMenuButton | POST | Configures persistent bottom-left menu button in chat. |
| setMessageReaction | POST | Adds animated emoji reaction (👍, 🔥, ❤️) to message. |
| setMyCommands | POST | Registers slash command list for autocomplete popup. |

---

# 22. Autonomous AI Bot Building Guide

**Category:** AI Agent & MCP Integration  
**URL:** https://docs.botlify.cloud/?page=ai-workflow  
**Summary:** How to prompt AI assistants to build, test, and deploy Telegram bots with zero syntax errors. (5 min read)  

## The Zero-Error Deployment Pipeline

      

When interacting with AI models through Botlify's MCP Server, AI agents follow a strict 4-step deployment cycle:

      
        
- **Retrieve Platform Context:** The agent calls `get_bot_making_guide` to access the 50-section Telegram Bot API master guide and scaffold rules.

        
- **Generate Modular Code:** The agent constructs code using strict types, cURL dispatchers, and SQLite WAL database storage.

        
- **Pre-Deployment Lint Check:** Before writing to disk, the agent or platform runs `php -l` syntax validation. If any syntax error exists, the deployment is blocked.

        
- **Webhook Test Simulation:** The agent executes `test_bot_webhook` to simulate an incoming `/start` message and verify that stdout is clean and `error.log` has no fatal exceptions.

      

      

## Sample Prompt for AI Assistants

      
```php
"Use Botlify MCP tools to inspect my bot @my_demo_bot.
Build a complete Refer-to-Earn bot with:
1. Daily claim reward ($0.50 / 24h)
2. Referral system ($1.00 / invite) with dynamic links
3. SQLite users and transactions schema
4. Native /start, /balance, /help slash commands and Telegram [Menu] button
5. Message reactions (👍, 🔥) and typing indicators
Validate the code syntax, write it to index.php, and run test_bot_webhook to verify."
```

---

# 23. REST API Overview & Authentication

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-auth  
**Summary:** Complete developer REST API overview, base URL, request methods, and API key authentication headers. (4 min read)  

## Endpoint & Base URL

      

Botlify Cloud exposes a unified REST API allowing external applications, CI/CD systems, and scripts to manage bots, files, crons, and databases:

      
```php
https://botlify.cloud/user_api.php
```

      

All endpoints accept both `GET` and `POST` requests (supporting `application/json`, `multipart/form-data`, and `application/x-www-form-urlencoded`).

      

## Authentication Methods

      

Every request requires your personal API key (obtainable in Dashboard → **Account & API Key**):

      
        
- **Method 1: Custom Header (Recommended)**`X-API-KEY: fbh_usr_YOUR_KEY`

        
- **Method 2: Bearer Token**`Authorization: Bearer fbh_usr_YOUR_KEY`

        
- **Method 3: Query Parameter**`https://botlify.cloud/user_api.php?api_key=fbh_usr_YOUR_KEY&action=...`

      

      

## Health Check (Ping)

      
```php
curl -s "https://botlify.cloud/user_api.php?action=ping&api_key=YOUR_API_KEY"
```

---

# 24. User Profile & Account APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-profile  
**Summary:** Retrieve account quotas, bot slots, Telegram ID, per-bot storage limits, and referral links. (3 min read)  

## Get User Profile & Account Quotas

      

Action: `get_profile` or `profile` or `me`

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"action": "get_profile"}'
```

      

Returns complete account details: `chat_id`, `username`, `first_name`, `email`, `bot_limit`, `used_bots`, `available_slots`, `storage_mb` (per-bot quota), and `refer_link`.

---

# 25. Complete Bot Management APIs (A-Z)

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-bots  
**Summary:** List, create, deploy, update, restart, soft-delete, restore, and check webhooks remotely. (5 min read)  

## 1. List Hosted Bots (list_bots)

      

Parameters: `status` (optional: `all`, `active`, `deleted`)

      
```php
curl -s "https://botlify.cloud/user_api.php?action=list_bots&api_key=YOUR_KEY"
```

      

## 2. Get Bot Details (get_bot)

      

Parameters: `bot_id` (Numeric ID or `@username`)

      

Returns storage used, database size, error log line count, webhook URL, and masked token.

      

## 3. Deploy New Bot (create_bot)

      

Parameters: `token` (BotFather token), `admin_chat_id` (optional)

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "create_bot",
    "token": "7123456789:AAHxyz...",
    "admin_chat_id": "7642872720"
  }'
```

      

## 4. Restart & Sync Webhook (restart_bot)

      

Parameters: `bot_id`. Forces re-registration of the HTTPS webhook with Telegram servers.

      

## 5. Toggle Webhook (toggle_webhook)

      

Parameters: `bot_id`, `action_type` (`start`, `stop`, or `toggle`). Pauses or activates live message receiving without altering bot code.

      

## 6. Check Live Webhook Info (webhook_info)

      

Parameters: `bot_id`. Calls Telegram's `getWebhookInfo` API to return pending update counts, last error dates, and SSL handshake status.

      

## 7. Soft-Delete & Restore (delete_bot / restore_bot)

      

Parameters: `bot_id`. Deleting moves the bot into a 30-day recycle bin; restore recovers the full codebase, database, and settings.

---

# 26. Bot Code Transfer System (A-Z)

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-transfers  
**Summary:** Securely transfer bot source code and architecture between Botlify users with automatic credential sanitization. (5 min read)  

## How Bot Transfer Works

      

The Bot Transfer Engine allows developers to clone and transfer bot projects to clients or other developers safely. Sensitive credentials (`.env` tokens and live `database.db`) are automatically sanitized and kept private.

      

## 1. Create Transfer Offer (create_transfer)

      

Action: `create_transfer`

      Parameters: `bot_id`, `target_recipient` (Telegram `@username` or numeric ID)

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "create_transfer",
    "bot_id": 14,
    "target_recipient": "@client_username"
  }'
```

      

Returns a secure 72-hour transfer code: `{"ok": true, "transfer_code": "TR-14-8F92A1BC"}`.

      

## 2. List Pending Transfers (list_transfers)

      

Action: `list_transfers` or `transfers`

      Returns incoming offers awaiting your acceptance as well as outgoing offers you created.

      

## 3. Inspect Transfer Details (get_transfer)

      

Action: `get_transfer`

      Parameters: `transfer_code`

      Returns the bot display name, code file count, sender handle, and expiration timestamp.

      

## 4. Accept Bot Transfer (accept_transfer)

      

Action: `accept_transfer`

      Parameters:

      
        
- `transfer_code`: The transfer verification code (e.g. `TR-14-8F92A1BC`).

        
- `token`: Recipient's new Telegram BotFather token.

        
- `admin_chat_id` (optional): Recipient's admin chat ID.

      
      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: RECIPIENT_API_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "accept_transfer",
    "transfer_code": "TR-14-8F92A1BC",
    "token": "7987654321:AAHnew_recipient_token..."
  }'
```

      

## 5. Reject Bot Transfer (reject_transfer)

      

Action: `reject_transfer`

      Parameters: `transfer_id` (Numeric ID from `list_transfers`).

---

# 27. File System & Code Editor APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-files  
**Summary:** List, read, write, create, upload, delete, and rename files inside the isolated bot sandbox. (5 min read)  

## 1. List Files (list_files)

      

Action: `list_files`

      Parameters: `bot_id`, `path` (optional subdirectory)

      

## 2. Read File (read_file)

      

Action: `read_file`

      Parameters: `bot_id`, `file` (e.g. `index.php` or `includes/db.php`)

      

## 3. Write / Save Code with Syntax Linting (write_file)

      

Action: `write_file` or `save_code`

      Parameters: `bot_id`, `file`, `content`

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "write_file",
    "bot_id": 14,
    "file": "index.php",
    "content": "
```

      
> [!TIP]
> **Syntax Validation Guard**
> write_file automatically lints your code using php -l. If a PHP syntax error is detected, the write is rejected to protect live bots.

      

## 4. Create File & Folder (create_file / create_folder)

      

Action: `create_file` (params: `bot_id`, `name`, `path`, `content`)

      Action: `create_folder` (params: `bot_id`, `name`, `path`)

      

## 5. Rename & Delete (rename_file / delete_file)

      

Action: `rename_file` (params: `bot_id`, `old_path`, `new_name`)

      Action: `delete_file` (params: `bot_id`, `file`). Critical system files (`.env`, `database.db`) are protected against accidental deletion.

---

# 28. Environment Variables (.env) APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-env  
**Summary:** Manage bot environment variables, API secrets, and configuration keys securely. (3 min read)  

## 1. Get Environment Variables (get_env)

      

Action: `get_env`

      Parameters: `bot_id`

      Returns a key-value dictionary of environment variables.

      

## 2. Set Single Variable (set_env_variable)

      

Action: `set_env_variable` or `set_env_var`

      Parameters: `bot_id`, `key`, `value`

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "set_env_variable",
    "bot_id": 14,
    "key": "PAYMENT_API_KEY",
    "value": "sk_live_9876543210"
  }'
```

      

## 3. Delete Variable (delete_env_variable)

      

Action: `delete_env_variable`

      Parameters: `bot_id`, `key`

---

# 29. Automated Cron Scheduler APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-crons  
**Summary:** Schedule recurring tasks, daily bonuses, and background worker scripts down to 1-minute intervals. (4 min read)  

## 1. List Cron Jobs (list_crons)

      

Action: `list_crons`

      Parameters: `bot_id`

      Returns array of scheduled crons with their ID, crontab expression, target file, and execution status.

      

## 2. Create Cron Job (create_cron)

      

Action: `create_cron`

      Parameters: `bot_id`, `cron_name`, `schedule` (e.g. `0 0 * * *` for midnight), `target_file` (e.g. `cron.php`)

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "create_cron",
    "bot_id": 14,
    "cron_name": "Daily Reward Reset",
    "schedule": "0 0 * * *",
    "target_file": "cron.php"
  }'
```

      

## 3. Toggle & Delete (toggle_cron / delete_cron)

      

Action: `toggle_cron` (params: `bot_id`, `cron_id`)

      Action: `delete_cron` (params: `bot_id`, `cron_id`)

      

## 4. Trigger Immediate Run (run_cron)

      

Action: `run_cron` (params: `bot_id`, `cron_id`). Manually triggers the worker and returns stdout output and execution duration.

---

# 30. SQLite Database Operations APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-database  
**Summary:** Query bot SQLite databases remotely with parameterized queries and schema inspection. (4 min read)  

## 1. Database Schema & Info (db_info)

      

Action: `db_info`

      Parameters: `bot_id`

      Returns database file size, SQLite version, journal mode (WAL), table names, schemas, and row counts.

      

## 2. Run SQL Query (db_query)

      

Action: `db_query`

      Parameters: `bot_id`, `query` (SQL statement), `params` (optional array of prepared statement values)

      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "db_query",
    "bot_id": 14,
    "query": "SELECT chat_id, username, balance FROM users WHERE balance > ? ORDER BY balance DESC LIMIT 10",
    "params": [5.0]
  }'
```

      

Supports `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE` statements.

---

# 31. Mass Broadcast & Telemetry APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-broadcast  
**Summary:** Send high-speed mass broadcasts to all bot subscribers with inline buttons and delivery stats. (3 min read)  

## 1. Broadcast Audience Stats (broadcast_stats)

      

Action: `broadcast_stats`

      Parameters: `bot_id`

      Returns total subscribers and active user counts in the bot database.

      

## 2. Dispatch Broadcast (send_broadcast)

      

Action: `send_broadcast`

      Parameters:

      
        
- `bot_id`: Target bot ID

        
- `message`: HTML or Markdown formatted text

        
- `audience`: `all` or `active7d` (active in last 7 days)

        
- `photo_url` (optional): Image URL to attach

        
- `keyboard` (optional): Inline button grid

      
      
```php
curl -X POST https://botlify.cloud/user_api.php   -H "X-API-KEY: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "action": "send_broadcast",
    "bot_id": 14,
    "message": "🔥 Special Announcement!
New features are live.",
    "audience": "all"
  }'
```

---

# 32. Scaffolding, Validation & Webhook Testing APIs

**Category:** REST API Reference  
**URL:** https://docs.botlify.cloud/?page=api-scaffold-test  
**Summary:** Automate bot generation, syntax verification, local webhook simulation, and atomic deployment. (4 min read)  

## 1. Get Bot Scaffolds (scaffold_bot)

      

Action: `scaffold_bot`

      Parameters: `type` (`styled_keyboard`, `database_bot`, `shop_bot`), `bot_name` (optional)

      Returns fully formed, linted PHP code ready for production.

      

## 2. Validate PHP Syntax (validate_code)

      

Action: `validate_code`

      Parameters: `code`

      Verifies that PHP code contains zero syntax errors without writing to disk.

      

## 3. Test Webhook Simulator (test_webhook)

      

Action: `test_webhook`

      Parameters: `bot_id`, `update` (optional custom Telegram update payload)

      Simulates execution locally, capturing output, runtime duration, and fatal errors from `error.log`.

      

## 4. Build, Validate & Deploy in One Step (build_and_deploy_bot)

      

Action: `build_and_deploy_bot` or `deploy_bot`

      Parameters: `bot_id`, `code` (or `type`)

      Atomically performs syntax linting, writes to `index.php`, and runs a test simulation.

---

# 33. Anti-Flood & Rate Limiting Rules

**Category:** Storage & Architecture  
**URL:** https://docs.botlify.cloud/?page=rate-limits  
**Summary:** How Botlify Cloud protects your bots against spam, DoS attacks, and high traffic spikes. (3 min read)  

## Built-in Protection Engines

      

Telegram webhooks can experience sudden surges in traffic during mass marketing campaigns or spam attacks. Botlify employs multi-tier traffic filtering:

      
        
- **Per-IP & Per-User Throttling:** Spammers sending more than 30 messages per second from a single chat are automatically queued or dropped.

        
- **Cloudflare DDoS Shielding:** High-bandwidth volumetric attacks are absorbed before reaching backend PHP workers.

        
- **Memory Isolation:** Memory limits (128 MB per request) prevent runaway scripts from affecting other bots on the node.

---

# 34. Troubleshooting & Error Diagnostics

**Category:** Troubleshooting & Support  
**URL:** https://docs.botlify.cloud/?page=troubleshooting  
**Summary:** Common errors, how to read error.log, and fixing webhook handshake issues. (4 min read)  

## 1. The Bot Does Not Respond to /start

      

If your bot is not replying to messages, check these 3 common causes:

      
        
- **Check Webhook Status:** Ensure the status badge in Bot Studio displays ACTIVE. If paused, click **Re-Sync Webhook**.

        
- **Syntax Errors:** Check **Error Logs** in Bot Studio. A missing semicolon or typo in PHP will cause an immediate fatal error.

        
- **Run Webhook Simulator:** Click **Simulate /start** in Bot Studio to see the exact PHP output and stack trace.

      

      

## 2. Telegram cURL Timeouts

      

Always keep Telegram API cURL timeouts reasonable (10–15 seconds). Never execute heavy blocking operations (like large external web scrapes) synchronously inside the webhook handler; instead, delegate them to background cron jobs.

      

## 3. Official Support

      

Need personalized help from the Botlify engineering team? Reach us via:

      
        
- **Telegram Support:** [@botlify_support](https://t.me/botlify_support)

        
- **Official Channel:** [@BotlifyOfficial](https://t.me/BotlifyOfficial)

---