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/METHOD_NAME

获取 Bot Token：

与 @BotFather 对话 发送 /newbot 按提示设置名称 获取 token

第一个 Bot (Python)：

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

核心 API 方法

更新管理：

getUpdates - 长轮询获取更新 setWebhook - 设置 Webhook deleteWebhook - 删除 Webhook getWebhookInfo - 查询 Webhook 状态

消息操作：

sendMessage - 发送文本消息 sendPhoto / sendVideo / sendDocument - 发送媒体 sendAudio / sendVoice - 发送音频 sendLocation / sendVenue - 发送位置 editMessageText - 编辑消息 deleteMessage - 删除消息 forwardMessage / copyMessage - 转发/复制消息

交互元素：

sendPoll - 发送投票（最多 12 个选项） 内联键盘 (InlineKeyboardMarkup) 回复键盘 (ReplyKeyboardMarkup) answerCallbackQuery - 响应回调查询

文件操作：

getFile - 获取文件信息 downloadFile - 下载文件 支持最大 2GB 文件（本地 Bot API 模式）

支付功能：

sendInvoice - 发送发票 answerPreCheckoutQuery - 处理支付 Telegram Stars 支付（最高 10,000 Stars） Webhook 配置

设置 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 示例：

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)

Webhook 要求：

必须使用 HTTPS 支持 TLS 1.2+ 端口：443, 80, 88, 8443 公共可访问的 URL 内联键盘

创建内联键盘：

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

内联模式

配置内联模式： 与 @BotFather 对话，发送 /setinline

处理内联查询：

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

Mini Apps (Web Apps) 开发 初始化 Mini App

HTML 模板：

Telegram Mini App

Mini App 核心 API

WebApp 对象主要属性：

// 初始化数据 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) // 分享链接

UI 控件

主按钮 (MainButton)：

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

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

次要按钮 (SecondaryButton)：

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

返回按钮 (BackButton)：

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

触觉反馈：

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

存储 API

云存储：

// 保存数据 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); });

支付集成

发起支付 (Telegram Stars)：

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('支付失败'); } });

数据验证

服务器端验证 initData (Python)：

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

启动 Mini App

从键盘按钮：

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"} } ]] }

从菜单按钮： 与 @BotFather 对话：

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

客户端开发 (TDLib) 使用 TDLib

Python 示例 (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()

发送消息

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

获取聊天列表

result = tg.get_chats() result.wait() chats = result.update

print(chats)

tg.stop()

MTProto 协议

特点：

端到端加密 高性能 支持所有 Telegram 功能 需要 API ID/Hash（从 https://my.telegram.org 获取） 最佳实践 Bot 开发

错误处理

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 不要信任客户端数据 服务器端验证所有操作 Mini Apps 开发

响应式设计

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

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

性能优化

最小化 JavaScript 包大小 使用懒加载 优化图片和资源

用户体验

适配深色/浅色主题 使用原生 UI 控件（MainButton 等） 提供触觉反馈 快速响应用户操作

安全考虑

HTTPS 强制 验证 initData 不在客户端存储敏感信息 使用 SecureStorage 存储密钥 常用库和工具 Python python-telegram-bot - 功能强大的 Bot 框架 aiogram - 异步 Bot 框架 telethon / pyrogram - MTProto 客户端 Node.js node-telegram-bot-api - Bot API 包装器 telegraf - 现代 Bot 框架 grammy - 轻量级框架 其他语言 PHP: telegram-bot-sdk Go: telegram-bot-api Java: TelegramBots C#: Telegram.Bot 参考资源 官方文档 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 仓库 Bot API 服务器: https://github.com/tdlib/telegram-bot-api Android 客户端: https://github.com/DrKLO/Telegram Desktop 客户端: https://github.com/telegramdesktop/tdesktop 官方组织: https://github.com/orgs/TelegramOfficial/repositories 工具 @BotFather - 创建和管理 Bot https://my.telegram.org - 获取 API ID/Hash Telegram Web App 测试环境 参考文件

此技能包含详细的 Telegram 开发资源索引和完整实现模板：

index.md - 完整的资源链接和快速导航 Telegram_Bot_按钮和键盘实现模板.md - 交互式按钮和键盘实现指南（404 行，12 KB） 三种按钮类型详解（Inline/Reply/Command Menu） python-telegram-bot 和 Telethon 双实现对比 完整的即用代码示例和项目结构 Handler 系统、错误处理和部署方案 动态视图对齐实现文档.md - Telegram 数据展示指南（407 行，12 KB） 智能动态对齐算法（三步法，O(n×m) 复杂度） 等宽字体环境的完美对齐方案 智能数值格式化系统（B/M/K 自动缩写） 排行榜和数据表格专业展示

这些精简指南提供了核心的 Telegram Bot 开发解决方案：

按钮和键盘交互的所有实现方式 消息和数据的专业格式化展示 实用的最佳实践和快速参考

使用此技能掌握 Telegram 生态的全栈开发！