Telegram 生态开发全栈指南 - 涵盖 Bot API、Mini Apps (Web Apps)、MTProto 客户端开发。包括消息处理、支付、内联模式、Webhook、认证、存储、传感器 API 等完整开发资源。
复制下面这句话，粘贴给 Claude Code、Codex、Cursor 等 AI 编程工具，它会读取安装说明并在你确认后完成安装。
请阅读 https://ai.atlankj.com/install/asset/gh-telegram-dev-4027e10a3559 ，按照其中的说明把「telegram-dev」安装到你（当前 AI 工具）中。执行前先告诉我将运行的命令和写入的位置，等我确认。
查看 AI 将读取的安装说明正在读取 GitHub 原文…
内容来自 GitHub 原始文件，由原作者维护。在 GitHub 查看
全面的 Telegram 开发指南，涵盖 Bot 开发、Mini Apps (Web Apps)、客户端开发的完整技术栈。
当需要以下帮助时使用此技能：
Bot API - 创建机器人程序
Mini Apps API (Web Apps) - 创建 Web 应用
Telegram API & TDLib - 创建客户端
API 端点：
https://api.telegram.org/bot<TOKEN>/METHOD_NAME
获取 Bot Token：
/newbot第一个 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
更新管理：
getUpdates - 长轮询获取更新setWebhook - 设置 WebhookdeleteWebhook - 删除 WebhookgetWebhookInfo - 查询 Webhook 状态消息操作：
sendMessage - 发送文本消息sendPhoto / sendVideo / sendDocument - 发送媒体sendAudio / sendVoice - 发送音频sendLocation / sendVenue - 发送位置editMessageText - 编辑消息deleteMessage - 删除消息forwardMessage / copyMessage - 转发/复制消息交互元素：
sendPoll - 发送投票（最多 12 个选项）answerCallbackQuery - 响应回调查询文件操作：
getFile - 获取文件信息downloadFile - 下载文件支付功能：
sendInvoice - 发送发票answerPreCheckoutQuery - 处理支付设置 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 要求：
创建内联键盘：
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}
)
HTML 模板：
<!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>
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) // 分享链接
主按钮 (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();
云存储：
// 保存数据
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
从键盘按钮：
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
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()
特点：
错误处理
try:
response = requests.post(url, json=data, timeout=10)
response.raise_for_status()
except requests.exceptions.RequestException as e:
print(f"请求失败: {e}")
速率限制
使用 Webhook 而非长轮询
数据验证
响应式设计
// 监听主题变化
tg.onEvent('themeChanged', () => {
document.body.style.backgroundColor = tg.themeParams.bg_color;
});
// 监听视口变化
tg.onEvent('viewportChanged', () => {
console.log('新高度:', tg.viewportHeight);
});
性能优化
用户体验
安全考虑
python-telegram-bot - 功能强大的 Bot 框架aiogram - 异步 Bot 框架telethon / pyrogram - MTProto 客户端node-telegram-bot-api - Bot API 包装器telegraf - 现代 Bot 框架grammy - 轻量级框架telegram-bot-sdktelegram-bot-apiTelegramBotsTelegram.Bot此技能包含详细的 Telegram 开发资源索引和完整实现模板：
这些精简指南提供了核心的 Telegram Bot 开发解决方案：
使用此技能掌握 Telegram 生态的全栈开发！