/telegram-dev

TRANSLATED CONTENT: --- name: telegram-dev description: Telegram 生态开发全栈指南 - 涵盖 Bot API、Mini Apps (Web Apps)、MTProto 客户端开发。包括消息处理、支付、内联模式、Webhook、认证、存储、传感器 API 等完整开发资源。 ---

Telegram 生态开发技能

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

何时使用此技能

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

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

Telegram 开发生态概览

三大核心 API

1. **Bot API** - 创建机器人程序

• HTTP 接口，简单易用
• 自动处理加密和通信
• 适合：聊天机器人、自动化工具

2. **Mini Apps API** (Web Apps) - 创建 Web 应用

• JavaScript 接口
• 在 Telegram 内运行
• 适合：小程序、游戏、电商

3. **Telegram API & TDLib** - 创建客户端

• 完整的 Telegram 协议实现
• 支持所有平台
• 适合：自定义客户端、企业应用

Bot API 开发

快速开始

**API 端点：**

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

**获取 Bot Token：** 1. 与 @BotFather 对话 2. 发送 `/newbot` 3. 按提示设置名称 4. 获取 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 模板：**

<!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.st