名称：Telegram机器人构建器描述：此技能应在用户询问“创建Telegram机器人”、“构建Telegram聊天机器人”、“设置Telegram webhook”、“向机器人添加内联键盘”、“处理Telegram回调查询”、“实现Telegram支付”、“通过Telegram机器人发送媒体”、“配置Telegram机器人命令”、“部署Telegram机器人”或提及Telegram Bot API、telegram机器人令牌、getUpdates、setWebhook或机器人框架如node-telegram-bot-api、grammy、python-telegram-bot、aiogram时使用。提供使用Node.js和Python构建生产就绪Telegram机器人的全面指导。

Telegram机器人构建器

使用Bot API（v9.4）构建Telegram机器人的全面指导。涵盖Node.js和Python生态系统，提供生产就绪的模式，用于身份验证、消息处理、键盘、媒体处理、支付、内联模式、webhook和部署。

何时使用此技能

使用此技能当：

从头开始构建新Telegram机器人
将Telegram消息集成到现有应用程序中
设置webhook或长轮询以获取机器人更新
创建带内联键盘和回调查询的交互菜单
处理媒体（照片、视频、文档、贴纸）
实现Telegram支付或Telegram Stars
构建内联模式功能
通过机器人管理群组、频道或论坛主题
部署机器人到生产环境（Docker、PM2、服务器less）

核心概念

身份验证

每个机器人都有从@BotFather获取的唯一令牌。令牌格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。

所有API调用发送至：https://api.telegram.org/bot<TOKEN>/METHOD_NAME

# .env 文件
BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

将令牌存储在环境变量中。切勿提交到源代码。

接收更新：轮询与Webhook

长轮询 (getUpdates) - 更简单，无需HTTPS，适合开发：

// Node.js with node-telegram-bot-api
const bot = new TelegramBot(process.env.BOT_TOKEN, { polling: true });

# Python with python-telegram-bot
app = Application.builder().token(os.getenv("BOT_TOKEN")).build()
app.run_polling()

Webhook (setWebhook) - 更适合生产，延迟更低，需要HTTPS（端口443、80、88或8443）：

bot.setWebHook('https://yourdomain.com/webhook', { secret_token: SECRET });

选择轮询进行开发和小型机器人。选择webhook进行处理高流量的生产部署。

消息类型与格式化

使用sendMessage发送文本。支持的解析模式：

HTML：<b>粗体</b>, <i>斜体</i>, <code>代码</code>, <pre>块</pre>, <a href="url">链接</a>, <tg-spoiler>剧透</tg-spoiler>
MarkdownV2：*粗体*, _斜体_, `代码`, ```块```, [链接](url), ||剧透||。需要转义：_*[]()~>#+-=|{}.!

优先使用HTML以简化转义。当简单格式化足够时使用MarkdownV2。

键盘与交互元素

内联键盘 - 附加到消息的按钮：

bot.sendMessage(chatId, '选择：', {
  reply_markup: {
    inline_keyboard: [
      [{ text: '选项A', callback_data: 'a' }, { text: '选项B', callback_data: 'b' }],
      [{ text: '访问网站', url: 'https://example.com' }]
    ]
  }
});

回复键盘 - 输入字段下方的自定义键盘：

bot.sendMessage(chatId, '选择：', {
  reply_markup: {
    keyboard: [[{ text: '📊 统计' }, { text: '⚙️ 设置' }]],
    resize_keyboard: true,
    one_time_keyboard: true
  }
});

使用callback_query处理内联按钮按下。callback_data字段限制为64字节。始终调用answerCallbackQuery以消除加载指示器。

发送媒体

// 照片（file_id、URL或上传）
bot.sendPhoto(chatId, 'https://example.com/photo.jpg', { caption: '一张照片' });

// 文档
bot.sendDocument(chatId, fs.createReadStream('./file.pdf'), { caption: '报告' });

// 相册（2-10个项目）
bot.sendMediaGroup(chatId, [
  { type: 'photo', media: 'https://example.com/1.jpg', caption: '第一张' },
  { type: 'photo', media: 'https://example.com/2.jpg' }
]);

指定文件的三种方式：file_id（重用先前上传）、HTTP URL（Telegram下载）或多部分上传。文件限制：50MB上传，通过Bot API下载20MB。

对话状态

对于多步交互（注册、表单、向导），维护每个聊天的对话状态：

Node.js：使用Map或Redis跟踪每个chatId的{ step, data }
Python：使用python-telegram-bot中的ConversationHandler（内置状态机）

参见reference/patterns_and_examples.md获取完整对话流实现。

错误处理

处理常见错误场景：

429 请求过多：从响应中读取retry_after，等待后重试
403 禁止访问：机器人被用户阻止或从聊天中移除
400 错误请求：无效参数（检查description字段）
409 冲突：另一个机器人实例使用相同令牌进行轮询

速率限制：约30条消息/秒到不同聊天，约20条消息/分钟到同一群组。实现指数退避进行重试。

机器人命令

注册在Telegram菜单中可见的命令：

bot.setMyCommands([
  { command: 'start', description: '启动机器人' },
  { command: 'help', description: '显示帮助' },
  { command: 'settings', description: '机器人设置' }
]);

命令可以使用BotCommandScope限定到特定聊天、用户或语言。

常见模式

快速开始（Node.js）

mkdir my-bot && cd my-bot
npm init -y
npm install node-telegram-bot-api dotenv
echo "BOT_TOKEN=your_token_here" > .env

快速开始（Python）

mkdir my-bot && cd my-bot
pip install python-telegram-bot python-dotenv
echo "BOT_TOKEN=your_token_here" > .env

流行库

语言	库	风格	最佳用途
Node.js	`node-telegram-bot-api`	基于回调	简单机器人、快速原型
Node.js	`grammy`	基于中间件	复杂机器人、插件
Node.js	`telegraf`	基于中间件	成熟生态系统
Python	`python-telegram-bot`	基于处理器	功能完整、对话
Python	`aiogram`	异步优先	高性能异步机器人

关键API方法类别

类别	关键方法
消息	`sendMessage`, `sendPhoto`, `sendVideo`, `sendDocument`, `editMessageText`, `deleteMessage`
键盘	`InlineKeyboardMarkup`, `ReplyKeyboardMarkup`, `answerCallbackQuery`
聊天管理	`getChat`, `banChatMember`, `promoteChatMember`, `setChatPermissions`
文件	`getFile`, `sendMediaGroup`, `sendDocument`
内联模式	`answerInlineQuery`与`InlineQueryResult*`类型
支付	`sendInvoice`, `answerPreCheckoutQuery`（使用`currency: "XTR"`用于Telegram Stars）
机器人配置	`setMyCommands`, `setMyDescription`, `setWebhook`

部署选项

PM2：pm2 start bot.js --name telegram-bot - 带自动重启的进程管理器
Docker：使用docker-compose的容器化部署
服务器less：作为Vercel/AWS Lambda函数的webhook处理器
VPS：使用systemd服务的直接部署

参见reference/patterns_and_examples.md获取Docker、PM2和服务器less部署配置。

安全清单

将BOT_TOKEN存储在环境变量中
在webhook端点上验证X-Telegram-Bot-Api-Secret-Token
验证管理员命令的用户ID
实现每用户速率限制
在数据库存储前清理用户输入
对所有webhook端点使用HTTPS
将allowed_updates限制为仅需类型

参考文件

有关详细API文档和实现模式，请参考：

reference/api_methods.md - 100多个Bot API方法的完整列表，按类别组织（消息、聊天管理、贴纸、支付、内联模式、游戏、论坛主题、礼物、护照等）
reference/api_types.md - 200多个Bot API类型的完整列表，包含所有字段（更新、消息、聊天、用户、键盘、媒体类型、支付类型、聊天成员、反应等）
reference/patterns_and_examples.md - 生产就绪的实现模式，适用于Node.js和Python，包括：内联键盘、webhook、媒体处理、对话状态管理、数据库集成、管理面板、多语言支持、Docker/PM2/服务器less部署、Telegram Stars支付和内联模式

构建机器人时，从SKILL.md开始了解核心概念，然后根据需要加载适当的参考文件以获取详细API信息或实现模式。