Telegram 开发指南：Bot机器人、Mini Apps小程序、客户端开发完整教程 | SkillsMD

Telegram 开发指南：Bot机器人、Mini Apps小程序、客户端开发完整教程

telegram-dev by 2025emma/vibe-coding-cn

130 周安装量

18,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/2025emma/vibe-coding-cn --skill telegram-dev

开发聊天机器人插件 API

🇨🇳中文介绍

Telegram 生态开发技能

全面的 Telegram 开发指南，涵盖 Bot 开发、Mini Apps (Web Apps)、客户端开发的完整技术栈。

何时使用此技能

当需要以下帮助时使用此技能：

开发 Telegram Bot（消息机器人）
创建 Telegram Mini Apps（小程序）
构建自定义 Telegram 客户端
集成 Telegram 支付和业务功能
实现 Webhook 和长轮询
使用 Telegram 认证和存储
处理消息、媒体和文件
实现内联模式和键盘

Telegram 开发生态概览

三大核心 API

Bot API - 创建机器人程序
- HTTP 接口，简单易用
- 自动处理加密和通信
- 适合：聊天机器人、自动化工具
Mini Apps API (Web Apps) - 创建 Web 应用
- JavaScript 接口
- 在 Telegram 内运行
- 适合：小程序、游戏、电商
Telegram API & TDLib - 创建客户端
- 完整的 Telegram 协议实现
- 支持所有平台
- 适合：自定义客户端、企业应用

Bot API 开发

快速开始

API 端点：

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

896,800 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

290,500 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

233,800 周安装

import requests

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

# 发送消息
def send_message(chat_id, text):
    url = f"{API_URL}/sendMessage"
    data = {"chat_id": chat_id, "text": text}
    return requests.post(url, json=data)

# 获取更新（长轮询）
def get_updates(offset=None):
    url = f"{API_URL}/getUpdates"
    params = {"offset": offset, "timeout": 30}
    return requests.get(url, params=params).json()

# 主循环
offset = None
while True:
    updates = get_updates(offset)
    for update in updates.get("result", []):
        chat_id = update["message"]["chat"]["id"]
        text = update["message"]["text"]
        
        # 回复消息
        send_message(chat_id, f"你说了：{text}")
        
        offset = update["update_id"] + 1

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}
)

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"]
    
    # 发送回复
    requests.post(
        f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
        json={"chat_id": chat_id, "text": f"收到: {text}"}
    )
    
    return "OK"

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

def send_inline_keyboard(chat_id):
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "按钮 1", "callback_data": "btn1"},
                {"text": "按钮 2", "callback_data": "btn2"}
            ],
            [
                {"text": "打开链接", "url": "https://example.com"}
            ]
        ]
    }
    
    requests.post(
        f"{API_URL}/sendMessage",
        json={
            "chat_id": chat_id,
            "text": "选择一个选项：",
            "reply_markup": keyboard
        }
    )

def handle_callback_query(callback_query):
    query_id = callback_query["id"]
    data = callback_query["data"]
    chat_id = callback_query["message"]["chat"]["id"]
    
    # 响应回调
    requests.post(
        f"{API_URL}/answerCallbackQuery",
        json={"callback_query_id": query_id, "text": f"你点击了 {data}"}
    )
    
    # 更新消息
    requests.post(
        f"{API_URL}/editMessageText",
        json={
            "chat_id": chat_id,
            "message_id": callback_query["message"]["message_id"],
            "text": f"你选择了：{data}"
        }
    )

def handle_inline_query(inline_query):
    query_id = inline_query["id"]
    query_text = inline_query["query"]
    
    # 创建结果
    results = [
        {
            "type": "article",
            "id": "1",
            "title": "结果 1",
            "input_message_content": {
                "message_text": f"你搜索了：{query_text}"
            }
        }
    ]
    
    requests.post(
        f"{API_URL}/answerInlineQuery",
        json={"inline_query_id": query_id, "results": results}
    )

<!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">主按钮</button>
    
    <script>
        // 获取 Telegram WebApp 对象
        const tg = window.Telegram.WebApp;
        
        // 通知 Telegram 应用已准备好
        tg.ready();
        
        // 展开到全屏
        tg.expand();
        
        // 显示用户信息
        const user = tg.initDataUnsafe?.user;
        if (user) {
            console.log("用户名:", user.first_name);
            console.log("用户ID:", user.id);
        }
        
        // 配置主按钮
        tg.MainButton.text = "提交";
        tg.MainButton.show();
        tg.MainButton.onClick(() => {
            // 发送数据到 Bot
            tg.sendData(JSON.stringify({action: "submit"}));
        });
        
        // 添加返回按钮
        tg.BackButton.show();
        tg.BackButton.onClick(() => {
            tg.close();
        });
    </script>
</body>
</html>

// 初始化数据
tg.initData           // 原始初始化字符串
tg.initDataUnsafe     // 解析后的对象

// 用户和主题
tg.initDataUnsafe.user       // 用户信息
tg.themeParams                // 主题颜色
tg.colorScheme                // 'light' 或 'dark'

// 状态
tg.isExpanded         // 是否全屏
tg.isFullscreen       // 是否全屏
tg.viewportHeight     // 视口高度
tg.platform           // 平台类型

// 版本
tg.version            // WebApp 版本

// 窗口控制
tg.ready()            // 标记应用准备就绪
tg.expand()           // 展开到全高度
tg.close()            // 关闭 Mini App
tg.requestFullscreen() // 请求全屏

// 数据发送
tg.sendData(data)     // 发送数据到 Bot

// 导航
tg.openLink(url)      // 打开外部链接
tg.openTelegramLink(url) // 打开 Telegram 链接

// 对话框
tg.showPopup(params, callback)  // 显示弹窗
tg.showAlert(message)           // 显示警告
tg.showConfirm(message)         // 显示确认

// 分享
tg.shareMessage(message)        // 分享消息
tg.shareUrl(url)                // 分享链接

tg.MainButton.setText("点击我");
tg.MainButton.show();
tg.MainButton.enable();
tg.MainButton.showProgress();  // 显示加载
tg.MainButton.hideProgress();

tg.MainButton.onClick(() => {
    console.log("主按钮被点击");
});

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

tg.BackButton.show();
tg.BackButton.onClick(() => {
    // 返回逻辑
});

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

// 保存数据
tg.CloudStorage.setItem('key', 'value', (error, success) => {
    if (success) console.log('保存成功');
});

// 获取数据
tg.CloudStorage.getItem('key', (error, value) => {
    console.log('值:', value);
});

// 删除数据
tg.CloudStorage.removeItem('key');

// 获取所有键
tg.CloudStorage.getKeys((error, keys) => {
    console.log('所有键:', keys);
});

// 普通本地存储
localStorage.setItem('key', 'value');
const value = localStorage.getItem('key');

// 安全存储（需要生物识别）
tg.SecureStorage.setItem('secret', 'value', callback);
tg.SecureStorage.getItem('secret', callback);

const bioManager = tg.BiometricManager;

// 初始化
bioManager.init(() => {
    if (bioManager.isInited) {
        console.log('支持的类型:', bioManager.biometricType);
        // 'finger', 'face', 'unknown'
        
        if (bioManager.isAccessGranted) {
            // 已授权，可以使用
        } else {
            // 请求授权
            bioManager.requestAccess({reason: '需要验证身份'}, (success) => {
                if (success) {
                    console.log('授权成功');
                }
            });
        }
    }
});

// 执行认证
bioManager.authenticate({reason: '确认操作'}, (success, token) => {
    if (success) {
        console.log('认证成功，token:', token);
    }
});

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

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

// 停止
tg.Accelerometer.stop();

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

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

tg.openInvoice('https://t.me/$invoice_link', (status) => {
    if (status === 'paid') {
        console.log('支付成功');
    } else if (status === 'cancelled') {
        console.log('支付取消');
    } else if (status === 'failed') {
        console.log('支付失败');
    }
});

import hmac
import hashlib
from urllib.parse import parse_qs

def validate_init_data(init_data, bot_token):
    # 解析数据
    parsed = parse_qs(init_data)
    received_hash = parsed.get('hash', [''])[0]
    
    # 移除 hash
    data_check_arr = []
    for key, value in parsed.items():
        if key != 'hash':
            data_check_arr.append(f"{key}={value[0]}")
    
    # 排序
    data_check_arr.sort()
    data_check_string = '\n'.join(data_check_arr)
    
    # 计算密钥
    secret_key = hmac.new(
        b"WebAppData",
        bot_token.encode(),
        hashlib.sha256
    ).digest()
    
    # 计算哈希
    calculated_hash = hmac.new(
        secret_key,
        data_check_string.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return calculated_hash == received_hash

keyboard = {
    "keyboard": [[
        {
            "text": "打开应用",
            "web_app": {"url": "https://yourdomain.com/app"}
        }
    ]],
    "resize_keyboard": True
}

requests.post(
    f"{API_URL}/sendMessage",
    json={
        "chat_id": chat_id,
        "text": "点击按钮打开应用",
        "reply_markup": keyboard
    }
)

keyboard = {
    "inline_keyboard": [[
        {
            "text": "启动应用",
            "web_app": {"url": "https://yourdomain.com/app"}
        }
    ]]
}

/setmenubutton
→ 选择你的 Bot
→ 提供 URL: https://yourdomain.com/app

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()

# 发送消息
result = tg.send_message(
    chat_id=123456789,
    text='Hello from TDLib!'
)

# 获取聊天列表
result = tg.get_chats()
result.wait()
chats = result.update

print(chats)

tg.stop()

错误处理

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

速率限制
- 群组消息：最多 20 条/分钟
- 私聊消息：最多 30 条/秒
- 全局限制：避免过于频繁
使用 Webhook 而非长轮询
- 更高效
- 更低延迟
- 更好的可扩展性
数据验证
- 始终验证 initData
- 不要信任客户端数据
- 服务器端验证所有操作

响应式设计

// 监听主题变化
tg.onEvent('themeChanged', () => {
    document.body.style.backgroundColor = tg.themeParams.bg_color;
});

// 监听视口变化
tg.onEvent('viewportChanged', () => {
    console.log('新高度:', tg.viewportHeight);
});

性能优化
- 最小化 JavaScript 包大小
- 使用懒加载
- 优化图片和资源
用户体验
- 适配深色/浅色主题
- 使用原生 UI 控件（MainButton 等）
- 提供触觉反馈
- 快速响应用户操作
安全考虑
- HTTPS 强制
- 验证 initData
- 不在客户端存储敏感信息
- 使用 SecureStorage 存储密钥

Telegram 开发指南：Bot机器人、Mini Apps小程序、客户端开发完整教程

🇨🇳中文介绍

Telegram 生态开发技能

何时使用此技能

Telegram 开发生态概览

三大核心 API

Bot API 开发

快速开始

相关 Skills

核心 API 方法

Webhook 配置

内联键盘

内联模式

Mini Apps (Web Apps) 开发

初始化 Mini App

Mini App 核心 API

UI 控件

存储 API

生物识别认证

位置和传感器

支付集成

数据验证

启动 Mini App

客户端开发 (TDLib)

使用 TDLib

MTProto 协议

最佳实践

Bot 开发

Mini Apps 开发

常用库和工具

Python

Node.js

其他语言

参考资源

官方文档

GitHub 仓库

工具

参考文件

最新 Skills