vibe-coding-cn/i18n/en/skills/04-dev-tools/telegram-dev/SKILL.md

---

name: telegram-dev

description: A full-stack guide to Telegram ecosystem development - covering Bot API, Mini Apps (Web Apps), and MTProto client development. Includes complete development resources for message handling, payments, inline mode, webhooks, authentication, storage, sensor APIs, and more.

Telegram Ecosystem Development Skill

A comprehensive guide to Telegram development, covering the full technology stack for Bot development, Mini Apps (Web Apps), and client development.

When to Use This Skill

Use this skill when you need help with the following:

• Developing a Telegram Bot (message bot)
• Creating Telegram Mini Apps
• Building a custom Telegram client
• Integrating Telegram payments and business features
• Implementing webhooks and long polling
• Using Telegram authentication and storage
• Handling messages, media, and files
• Implementing inline mode and keyboards

Overview of the Telegram Development Ecosystem

Three Core APIs

1. Bot API - For creating bot programs

   • Simple to use HTTP interface
   • Automatically handles encryption and communication
   • Suitable for: chatbots, automation tools

2. Mini Apps API (Web Apps) - For creating web applications

   • JavaScript interface
   • Runs inside Telegram
   • Suitable for: mini-apps, games, e-commerce

3. Telegram API & TDLib - For creating clients

   • Full implementation of the Telegram protocol
   • Supports all platforms
   • Suitable for: custom clients, enterprise applications

Bot API Development

Quick Start

API Endpoint:

https://api.telegram.org/bot<TOKEN>/METHOD_NAME

Get a Bot Token:

1. Talk to @BotFather
2. Send /newbot
3. Follow the prompts to set a name
4. Get the token

First Bot (Python):

import requests

BOT_TOKEN = "your_bot_token_here"
API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"

# Send a message
def send_message(chat_id, text):
    url = f"{API_URL}/sendMessage"
    data = {"chat_id": chat_id, "text": text}
    return requests.post(url, json=data)

# Get updates (long polling)
def get_updates(offset=None):
    url = f"{API_URL}/getUpdates"
    params = {"offset": offset, "timeout": 30}
    return requests.get(url, params=params).json()

# Main loop
offset = None
while True:
    updates = get_updates(offset)
    for update in updates.get("result", []):
        chat_id = update["message"]["chat"]["id"]
        text = update["message"]["text"]
        
        # Reply to the message
        send_message(chat_id, f"You said: {text}")
        
        offset = update["update_id"] + 1

Core API Methods

Update Management:

• getUpdates - Get updates via long polling
• setWebhook - Set a webhook
• deleteWebhook - Delete a webhook
• getWebhookInfo - Query webhook status

Message Operations:

• sendMessage - Send a text message
• sendPhoto / sendVideo / sendDocument - Send media
• sendAudio / sendVoice - Send audio
• sendLocation / sendVenue - Send a location
• editMessageText - Edit a message
• deleteMessage - Delete a message
• forwardMessage / copyMessage - Forward/copy a message

Interactive Elements:

• sendPoll - Send a poll (up to 12 options)
• Inline Keyboard (InlineKeyboardMarkup)
• Reply Keyboard (ReplyKeyboardMarkup)
• answerCallbackQuery - Respond to a callback query

File Operations:

• getFile - Get file information
• downloadFile - Download a file
• Supports files up to 2GB (in local Bot API mode)

Payment Features:

• sendInvoice - Send an invoice
• answerPreCheckoutQuery - Process a payment
• Telegram Stars payment (up to 10,000 Stars)

Webhook Configuration

Set a Webhook:

import requests

BOT_TOKEN = "your_token"
WEBHOOK_URL = "https://yourdomain.com/webhook"

requests.post(
    f"https://api.telegram.org/bot{BOT_TOKEN}/setWebhook",
    json={"url": WEBHOOK_URL}
)

Flask Webhook Example:

from flask import Flask, request
import requests

app = Flask(__name__)
BOT_TOKEN = "your_token"

@app.route('/webhook', methods=['POST'])
def webhook():
    update = request.get_json()
    
    chat_id = update["message"]["chat"]["id"]
    text = update["message"]["text"]
    
    # Send a reply
    requests.post(
        f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
        json={"chat_id": chat_id, "text": f"Received: {text}"}
    )
    
    return "OK"

if __name__ == '__main__':
    app.run(port=5000)

Webhook Requirements:

• Must use HTTPS
• Supports TLS 1.2+
• Ports: 443, 80, 88, 8443
• Publicly accessible URL

Inline Keyboard

Create an Inline Keyboard:

def send_inline_keyboard(chat_id):
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "Button 1", "callback_data": "btn1"},
                {"text": "Button 2", "callback_data": "btn2"}
            ],
            [
                {"text": "Open Link", "url": "https://example.com"}
            ]
        ]
    }
    
    requests.post(
        f"{API_URL}/sendMessage",
        json={
            "chat_id": chat_id,
            "text": "Choose an option:",
            "reply_markup": keyboard
        }
    )

Handle Callbacks:

def handle_callback_query(callback_query):
    query_id = callback_query["id"]
    data = callback_query["data"]
    chat_id = callback_query["message"]["chat"]["id"]
    
    # Respond to the callback
    requests.post(
        f"{API_URL}/answerCallbackQuery",
        json={"callback_query_id": query_id, "text": f"You clicked {data}"}
    )
    
    # Update the message
    requests.post(
        f"{API_URL}/editMessageText",
        json={
            "chat_id": chat_id,
            "message_id": callback_query["message"]["message_id"],
            "text": f"You chose: {data}"
        }
    )

Inline Mode

Configure Inline Mode: Talk to @BotFather and send /setinline

Handle Inline Queries:

def handle_inline_query(inline_query):
    query_id = inline_query["id"]
    query_text = inline_query["query"]
    
    # Create results
    results = [
        {
            "type": "article",
            "id": "1",
            "title": "Result 1",
            "input_message_content": {
                "message_text": f"You searched for: {query_text}"
            }
        }
    ]
    
    requests.post(
        f"{API_URL}/answerInlineQuery",
        json={"inline_query_id": query_id, "results": results}
    )

Mini Apps (Web Apps) Development

Initialize a Mini App

HTML Template:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
    <title>My Mini App</title>
</head>
<body>
    <h1>Telegram Mini App</h1>
    <button id="mainBtn">Main Button</button>
    
    <script>
        // Get the Telegram WebApp object
        const tg = window.Telegram.WebApp;
        
        // Notify Telegram that the app is ready
        tg.ready();
        
        // Expand to full screen
        tg.expand();
        
        // Display user information
        const user = tg.initDataUnsafe?.user;
        if (user) {
            console.log("Username:", user.first_name);
            console.log("User ID:", user.id);
        }
        
        // Configure the main button
        tg.MainButton.text = "Submit";
        tg.MainButton.show();
        tg.MainButton.onClick(() => {
            // Send data to the Bot
            tg.sendData(JSON.stringify({action: "submit"}));
        });
        
        // Add a back button
        tg.BackButton.show();
        tg.BackButton.onClick(() => {
            tg.close();
        });
    </script>
</body>
</html>

Mini App Core API

WebApp Object Main Properties:

// Initialization data
tg.initData           // Raw initialization string
tg.initDataUnsafe     // Parsed object

// User and theme
tg.initDataUnsafe.user       // User information
tg.themeParams                // Theme colors
tg.colorScheme                // 'light' or 'dark'

// Status
tg.isExpanded         // Whether it's full screen
tg.isFullscreen       // Whether it's full screen
tg.viewportHeight     // Viewport height
tg.platform           // Platform type

// Version
tg.version            // WebApp version

Main Methods:

// Window control
tg.ready()            // Mark the app as ready
tg.expand()           // Expand to full height
tg.close()            // Close the Mini App
tg.requestFullscreen() // Request full screen

// Data sending
tg.sendData(data)     // Send data to the Bot

// Navigation
tg.openLink(url)      // Open an external link
tg.openTelegramLink(url) // Open a Telegram link

// Dialogs
tg.showPopup(params, callback)  // Show a popup
tg.showAlert(message)           // Show an alert
tg.showConfirm(message)         // Show a confirmation

// Sharing
tg.shareMessage(message)        // Share a message
tg.shareUrl(url)                // Share a link

UI Controls

Main Button (MainButton):

tg.MainButton.setText("Click Me");
tg.MainButton.show();
tg.MainButton.enable();
tg.MainButton.showProgress();  // Show loading
tg.MainButton.hideProgress();

tg.MainButton.onClick(() => {
    console.log("Main button clicked");
});

Secondary Button (SecondaryButton):

tg.SecondaryButton.setText("Cancel");
tg.SecondaryButton.show();
tg.SecondaryButton.onClick(() => {
    tg.close();
});

Back Button (BackButton):

tg.BackButton.show();
tg.BackButton.onClick(() => {
    // Back logic
});

Haptic Feedback:

tg.HapticFeedback.impactOccurred('light');  // light, medium, heavy
tg.HapticFeedback.notificationOccurred('success'); // success, warning, error
tg.HapticFeedback.selectionChanged();

Storage API

Cloud Storage:

// Save data
tg.CloudStorage.setItem('key', 'value', (error, success) => {
    if (success) console.log('Saved successfully');
});

// Get data
tg.CloudStorage.getItem('key', (error, value) => {
    console.log('Value:', value);
});

// Delete data
tg.CloudStorage.removeItem('key');

// Get all keys
tg.CloudStorage.getKeys((error, keys) => {
    console.log('All keys:', keys);
});

Local Storage:

// Normal local storage
localStorage.setItem('key', 'value');
const value = localStorage.getItem('key');

// Secure storage (requires biometrics)
tg.SecureStorage.setItem('secret', 'value', callback);
tg.SecureStorage.getItem('secret', callback);

Biometric Authentication

const bioManager = tg.BiometricManager;

// Initialize
bioManager.init(() => {
    if (bioManager.isInited) {
        console.log('Supported type:', bioManager.biometricType);
        // 'finger', 'face', 'unknown'
        
        if (bioManager.isAccessGranted) {
            // Already authorized, can be used
        } else {
            // Request authorization
            bioManager.requestAccess({reason: 'Need to verify identity'}, (success) => {
                if (success) {
                    console.log('Authorization successful');
                }
            });
        }
    }
});

// Perform authentication
bioManager.authenticate({reason: 'Confirm action'}, (success, token) => {
    if (success) {
        console.log('Authentication successful, token:', token);
    }
});

Location and Sensors

Get Location:

tg.LocationManager.init(() => {
    if (tg.LocationManager.isInited) {
        tg.LocationManager.getLocation((location) => {
            console.log('Latitude:', location.latitude);
            console.log('Longitude:', location.longitude);
        });
    }
});

Accelerometer:

tg.Accelerometer.start({refresh_rate: 100}, (started) => {
    if (started) {
        tg.Accelerometer.onEvent((event) => {
            console.log('Acceleration:', event.x, event.y, event.z);
        });
    }
});

// Stop
tg.Accelerometer.stop();

Gyroscope:

tg.Gyroscope.start({refresh_rate: 100}, callback);
tg.Gyroscope.onEvent((event) => {
    console.log('Rotation speed:', event.x, event.y, event.z);
});

Device Orientation:

tg.DeviceOrientation.start({refresh_rate: 100}, callback);
tg.DeviceOrientation.onEvent((event) => {
    console.log('Orientation:', event.absolute, event.alpha, event.beta, event.gamma);
});

Payment Integration

Initiate a Payment (Telegram Stars):

tg.openInvoice('https://t.me/$invoice_link', (status) => {
    if (status === 'paid') {
        console.log('Payment successful');
    } else if (status === 'cancelled') {
        console.log('Payment cancelled');
    } else if (status === 'failed') {
        console.log('Payment failed');
    }
});

Data Validation

Server-side Validation of initData (Python):

import hmac
import hashlib
from urllib.parse import parse_qs

def validate_init_data(init_data, bot_token):
    # Parse the data
    parsed = parse_qs(init_data)
    received_hash = parsed.get('hash', [''])[0]
    
    # Remove the hash
    data_check_arr = []
    for key, value in parsed.items():
        if key != 'hash':
            data_check_arr.append(f"{key}={value[0]}")
    
    # Sort
    data_check_arr.sort()
    data_check_string = '\n'.join(data_check_arr)
    
    # Calculate the secret key
    secret_key = hmac.new(
        b"WebAppData",
        bot_token.encode(),
        hashlib.sha256
    ).digest()
    
    # Calculate the hash
    calculated_hash = hmac.new(
        secret_key,
        data_check_string.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return calculated_hash == received_hash

Launching a Mini App

From a Keyboard Button:

keyboard = {
    "keyboard": [[ 
        {
            "text": "Open App",
            "web_app": {"url": "https://yourdomain.com/app"}
        }
    ]],
    "resize_keyboard": True
}

requests.post(
    f"{API_URL}/sendMessage",
    json={
        "chat_id": chat_id,
        "text": "Click the button to open the app",
        "reply_markup": keyboard
    }
)

From an Inline Button:

keyboard = {
    "inline_keyboard": [[
        {
            "text": "Launch App",
            "web_app": {"url": "https://yourdomain.com/app"}
        }
    ]]
}

From the Menu Button: Talk to @BotFather:

/setmenubutton
→ Choose your Bot
→ Provide URL: https://yourdomain.com/app

Client Development (TDLib)

Using TDLib

Python Example (python-telegram):

from telegram.client import Telegram

tg = Telegram(
    api_id='your_api_id',
    api_hash='your_api_hash',
    phone='+1234567890',
    database_encryption_key='changeme1234',
)

tg.login()

# Send a message
result = tg.send_message(
    chat_id=123456789,
    text='Hello from TDLib!'
)

# Get chat list
result = tg.get_chats()
result.wait()
chats = result.update

print(chats)

tg.stop()

MTProto Protocol

Features:

• End-to-end encryption
• High performance
• Supports all Telegram features
• Requires API ID/Hash (from https://my.telegram.org)

Best Practices

Bot Development

1. Error Handling

   try:
       response = requests.post(url, json=data, timeout=10)
       response.raise_for_status()
   except requests.exceptions.RequestException as e:
       print(f"Request failed: {e}")
   

2. Rate Limiting

   • Group messages: max 20/minute
   • Private messages: max 30/second
   • Global limits: avoid being too frequent

3. Use Webhooks instead of Long Polling

   • More efficient
   • Lower latency
   • Better scalability

4. Data Validation

   • Always validate initData
   • Don't trust client-side data
   • Server-side validation for all operations

Mini Apps Development

1. Responsive Design

   // Listen for theme changes
   tg.onEvent('themeChanged', () => {
       document.body.style.backgroundColor = tg.themeParams.bg_color;
   });
       
   // Listen for viewport changes
   tg.onEvent('viewportChanged', () => {
       console.log('New height:', tg.viewportHeight);
   });
   

2. Performance Optimization

   • Minimize JavaScript bundle size
   • Use lazy loading
   • Optimize images and resources

3. User Experience

   • Adapt to dark/light themes
   • Use native UI controls (MainButton, etc.)
   • Provide haptic feedback
   • Respond quickly to user actions

4. Security Considerations

   • HTTPS is mandatory
   • Validate initData
   • Don't store sensitive information on the client
   • Use SecureStorage for secrets

Common Libraries and Tools

Python

• python-telegram-bot - A powerful Bot framework
• aiogram - An asynchronous Bot framework
• telethon / pyrogram - MTProto clients

Node.js

• node-telegram-bot-api - Bot API wrapper
• telegraf - Modern Bot framework
• grammy - Lightweight framework

Other Languages

• PHP: telegram-bot-sdk
• Go: telegram-bot-api
• Java: TelegramBots
• C#: Telegram.Bot

Reference Resources

Official Documentation

• Bot API: https://core.telegram.org/bots/api
• Mini Apps: https://core.telegram.org/bots/webapps
• Mini Apps Platform: https://docs.telegram-mini-apps.com
• Telegram API: https://core.telegram.org

GitHub Repositories

• Bot API Server: https://github.com/tdlib/telegram-bot-api
• Android Client: https://github.com/DrKLO/Telegram
• Desktop Client: https://github.com/telegramdesktop/tdesktop
• Official Organization: https://github.com/orgs/TelegramOfficial/repositories

Tools

• @BotFather - Create and manage Bots
• https://my.telegram.org - Get API ID/Hash
• Telegram Web App test environment

Reference Files

This skill includes a detailed index of Telegram development resources and complete implementation templates:

• index.md - A complete index of resources and quick navigation
• Telegram_Bot_按钮和键盘实现模板.md - An implementation guide for interactive buttons and keyboards (404 lines, 12 KB)
  • Detailed explanation of three button types (Inline/Reply/Command Menu)
  • Comparison of implementations with python-telegram-bot and Telethon
  • Complete ready-to-use code examples and project structure
  • Handler system, error handling, and deployment方案
• 动态视图对齐实现文档.md - A guide to data display in Telegram (407 lines, 12 KB)
  • Intelligent dynamic alignment algorithm (three-step method, O(n×m) complexity)
  • Perfect alignment solution for monospaced font environments
  • Intelligent numerical formatting system (automatic B/M/K abbreviation)
  • Professional display for leaderboards and data tables

These concise guides provide core solutions for Telegram Bot development:

• All implementation methods for button and keyboard interaction
• Professional formatting and display of messages and data
• Practical best practices and quick references

---

Master full-stack development of the Telegram ecosystem with this skill!