Telegram 生态开发全栈指南 - 涵盖 Bot API、Mini Apps (Web Apps)、MTProto 客户端开发。包括消息处理、支付、内联模式、Webhook、认证、存储、传感器 API 等完整开发资源。。
全面的 Telegram 开发指南，涵盖 Bot 开发、Mini Apps (Web Apps)、客户端开发的完整技术栈。
当需要以下帮助时使用此技能：
Bot API - 创建机器人程序
Mini Apps API (Web Apps) - 创建 Web 应用
Telegram API & TDLib - 创建客户端
Bot 菜单按钮 (Menu Button)
Bot 菜单按钮是 Telegram 在聊天界面提供的简化入口，让用户可以快速启动 Mini App。
设置菜单按钮（Bot Father）：
1. 与 @BotFather 对话
2. 发送 /setmenubutton
3. 选择你的 Bot
4. 提供菜单按钮类型和 URL
菜单按钮类型：
# 类型 1: Web App 按钮
await bot.set_chat_menu_button(
menu_button={
'type': 'web_app',
'text': '打开应用',
'web_app': {'url': 'https://your-mini-app.com'}
}
)
# 类型 2: 默认按钮（恢复默认）
await bot.set_chat_menu_button(menu_button={'type': 'default'})
# 类型 3: 命令按钮（快速执行命令）
await bot.set_chat_menu_button(
menu_button={
'type': 'commands',
'text': '命令列表'
}
)
# 查询当前菜单按钮
menu_button_info = await bot.get_chat_menu_button()
print(menu_button_info)
深度链接 (Deep Links)
深度链接允许用户通过点击链接直接与 Bot 交互，并传递参数。
创建深度链接：
# 格式: https://t.me/{bot_username}?start={parameter}
# 参数: 64 字符以内的字符串（A-Z, a-z, 0-9, _, -）
invite_link = f"https://t.me/{bot_username}?start=user_12345"
# 生成邀请链接（群组）
group_link = await bot.create_chat_invite_link(
chat_id=group_chat_id,
name='加入我们的群组',
creates_join_request=True # 需要管理员审核
)
print(group_link.invite_link)
处理深度链接：
内联深度链接：
# 格式: https://t.me/{bot_username}?startapp={parameter}
# 用于 Mini Apps 的内联深度链接
@bot.command('start')
async def start_with_app(update: Update, context: ContextTypes.DEFAULT_TYPE):
if context.args and context.args[0].startswith('app_'):
# 这是一个 Mini App 深度链接
app_parameter = context.args[0][4:]
# 创建内联键盘打开 Mini App
keyboard = {
'inline_keyboard': [[
{
'text': '打开应用',
'web_app': {
'url': f'https://your-mini-app.com?param={app_parameter}'
}
}
]]
}
await update.message.reply_text(
'点击按钮打开应用',
reply_markup=keyboard
)
Telegram Stars 支付
Telegram Stars 是 Telegram 的虚拟货币系统，支持小额支付。
创建 Stars 发票：
from telegram import LabeledPrice
await bot.send_invoice(
chat_id=chat_id,
title='高级订阅',
description='1 个月的高级功能访问',
payload='premium_subscription',
provider_token='', # Telegram Stars 支付不需要
currency='XTR', # XTR = Telegram Stars
prices=[
LabeledPrice('1 个月', 100), # 100 Stars
LabeledPrice('3 个月', 250), # 250 Stars（优惠）
],
start_parameter='premium_start',
photo_url='https://example.com/premium.jpg',
photo_size=800,
photo_width=800,
photo_height=800,
is_flexible=False # 价格不可变
)
处理预结账查询：
from telegram import PreCheckoutQuery
@bot.pre_checkout_query_handler
async def pre_checkout_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
query = update.pre_checkout_query
# 验证订单
if await validate_order(query.invoice_payload, query.from_user.id):
await query.answer(ok=True)
else:
await query.answer(
ok=False,
error_message='订单验证失败，请联系客服'
)
async def validate_order(payload: str, user_id: int) -> bool:
"""验证订单有效性"""
# 检查用户是否有权限购买
# 检查订单是否已处理
# 检查价格是否正确
return True
处理支付成功：
@bot.message_handler(content_types=['successful_payment'])
async def successful_payment_handler(message: Message):
payment = message.successful_payment
# 解析支付信息
user_id = message.chat.id
payload = payment.invoice_payload
currency = payment.currency # XTR
total_amount = payment.total_amount # Stars 数量
# 验证并处理支付
await process_payment(user_id, payload, total_amount)
await message.reply_text(
f'✅ 支付成功！\n'
f'支付: {total_amount} {currency}\n'
f'订单: {payload}'
)
async def process_payment(user_id: int, payload: str, amount: int):
"""处理支付后的业务逻辑"""
if payload == 'premium_subscription':
# 激活高级功能
await activate_premium(user_id, duration_days=30)
elif payload == 'credits':
# 充值积分
await add_credits(user_id, amount)
在 Mini App 中发起支付：
const tg = window.Telegram.WebApp;
// 打开发票链接
tg.openInvoice("https://t.me/$invoice_link", (status) => {
if (status === "paid") {
console.log("支付成功");
// 通知 Bot 支付完成
tg.sendData(
JSON.stringify({
action: "payment_completed",
invoice_id: "...",
})
);
} else if (status === "cancelled") {
console.log("支付取消");
} else if (status === "pending") {
console.log("支付处理中");
} else if (status === "failed") {
console.log("支付失败");
}
});
消息编辑限制
Telegram 允许编辑消息，但有 48 小时的限制。
import datetime
from telegram.error import BadRequest
async def edit_message_safely(chat_id: int, message_id: int, new_text: str):
"""安全编辑消息，处理时间限制"""
try:
# 尝试编辑消息
await bot.edit_message_text(
chat_id=chat_id,
message_id=message_id,
text=new_text
)
return True
except BadRequest as e:
error_msg = str(e)
if 'message is not modified' in error_msg:
# 消息内容未改变
print('消息内容未修改')
return True
elif 'message to edit not found' in error_msg:
# 消息已被删除
print('消息不存在')
return False
elif "message can't be edited" in error_msg:
# 超过 48 小时编辑限制
print('消息超过 48 小时，无法编辑')
# 替代方案：发送新消息
await bot.send_message(
chat_id=chat_id,
text=f"（更新）{new_text}"
)
return False
else:
print(f"编辑失败: {e}")
return False
获取消息信息：
# 获取原始消息时间戳
message = await bot.send_message(chat_id, "测试消息")
message_time = message.date # datetime 对象
# 计算是否可编辑
now = datetime.datetime.now()
can_edit = (now - message_time).total_seconds() < 48 * 3600 # 48 小时
if can_edit:
await message.edit_text("更新后的文本")
else:
await bot.send_message(chat_id, "新消息（原消息已过期无法编辑）")
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)
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("主按钮被点击");
});
