Telegram Bot API 初学者指南 (2026)

2026年 Telegram Bot API 入门指南

Telegram 机器人可以自动执行任务、发送通知、处理支付、运行测验，甚至充当全能的 AI 助手——这一切都通过 Telegram Bot API 实现。凭借超过 9 亿的月活跃用户，Telegram 是构建真正有人使用的机器人的最佳平台之一。

本指南将带你从零开始创建一个 Telegram 机器人，涵盖从获取机器人 Token 到处理命令、发送媒体文件以及部署到生产环境的所有内容。

Telegram 机器人能做什么？

在编写代码之前，以下是 Bot API 支持的功能：

能力	描述
文本消息	发送和接收纯文本及富文本格式的消息
命令	处理 /start、/help 及自定义命令
内联键盘 (Inline keyboards)	消息内嵌的交互式按钮
媒体文件	发送照片、视频、音频、文档和贴纸
支付	通过 Telegram 内置的支付系统接受付款
Webhooks	通过 HTTP 回调实时接收更新
群组管理	管理群组、置顶消息、封禁用户
内联模式 (Inline mode)	允许用户通过 @yourbot 查询词 在任何聊天中调用你的机器人
迷你应用 (Mini Apps)	在 Telegram 内部运行的全功能 Web 应用程序

第一步：使用 BotFather 创建机器人

每个 Telegram 机器人都是从 BotFather 开始的，它是管理机器人的官方机器人。

1. 打开 Telegram 并搜索 @BotFather。
2. 发送 /newbot。
3. 选择显示名称（例如：“My First Bot”）。
4. 选择以 bot 结尾的用户名（例如：my_first_demo_bot）。
5. BotFather 会回复你的 HTTP API token。它看起来像这样：

7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

请妥善保存此 Token。任何拥有此 Token 的人都可以控制你的机器人。

第二步：发送你的第一条消息

你可以使用简单的 HTTP 请求与 Bot API 交互。让我们用 cURL 测试一下：

# 将 YOUR_BOT_TOKEN 替换为来自 BotFather 的 Token
# 将 CHAT_ID 替换为你的 Telegram 用户 ID

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage" \
  -d "chat_id=CHAT_ID" \
  -d "text=来自我的第一个机器人的问候！"

要查找你的 Chat ID，请给你的机器人发任意消息，然后调用：

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates"

在响应中寻找 chat.id 字段。

第三步：使用 Python 构建机器人

python-telegram-bot 库是 Telegram Bot API 最流行的 Python 封装库。

安装库

pip install python-telegram-bot

带有命令处理器的基础机器人

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

# 命令处理器
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        "欢迎！我是你的机器人。使用 /help 查看我可以做什么。"
    )

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    help_text = """
可用命令：
/start - 启动机器人
/help - 显示此帮助信息
/echo <文本> - 复读你的消息
/weather <城市> - 获取天气信息
    """
    await update.message.reply_text(help_text)

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_text = " ".join(context.args) if context.args else "你什么也没说！"
    await update.message.reply_text(user_text)

# 处理常规文本消息
async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    text = update.message.text
    await update.message.reply_text(f"你说的是：{text}")

def main():
    app = Application.builder().token("YOUR_BOT_TOKEN").build()

    # 注册处理器
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("help", help_command))
    app.add_handler(CommandHandler("echo", echo))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))

    # 开始轮询更新
    print("机器人正在运行...")
    app.run_polling()

if __name__ == "__main__":
    main()

运行机器人：

python bot.py

打开 Telegram，找到你的机器人并发送 /start。它应该会立即做出响应。

第四步：添加内联键盘

内联键盘允许你在消息中添加交互式按钮：

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import CallbackQueryHandler, ContextTypes

async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [
            InlineKeyboardButton("选项 1", callback_data="option_1"),
            InlineKeyboardButton("选项 2", callback_data="option_2"),
        ],
        [
            InlineKeyboardButton("访问网站", url="https://example.com"),
        ],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text("请选择一个选项：", reply_markup=reply_markup)

async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    await query.answer()  # 确认按钮点击

    if query.data == "option_1":
        await query.edit_message_text("你选择了选项 1！")
    elif query.data == "option_2":
        await query.edit_message_text("你选择了选项 2！")

# 注册处理器
app.add_handler(CommandHandler("menu", menu))
app.add_handler(CallbackQueryHandler(button_callback))

第五步：发送媒体文件

机器人可以发送照片、视频、文档等：

async def send_photo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # 通过 URL 发送
    await update.message.reply_photo(
        photo="https://example.com/image.jpg",
        caption="这是一张来自网络的照片！"
    )

async def send_document(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # 发送本地文件
    with open("report.pdf", "rb") as doc:
        await update.message.reply_document(
            document=doc,
            caption="这是你的报告。"
        )

async def send_video(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_video(
        video="https://example.com/video.mp4",
        caption="看看这个视频！"
    )

第六步：使用 Node.js 构建机器人

如果你偏好 JavaScript，telegraf 库是最流行的选择：

npm install telegraf

const { Telegraf, Markup } = require("telegraf");

const bot = new Telegraf("YOUR_BOT_TOKEN");

// 命令处理器
bot.start((ctx) => {
  ctx.reply("欢迎！使用 /help 查看可用命令。");
});

bot.help((ctx) => {
  ctx.reply(`可用命令：
/start - 启动机器人
/help - 显示帮助
/menu - 显示选项菜单`);
});

// 内联键盘示例
bot.command("menu", (ctx) => {
  ctx.reply(
    "请选择一个选项：",
    Markup.inlineKeyboard([
      [Markup.button.callback("选项 A", "action_a")],
      [Markup.button.callback("选项 B", "action_b")],
      [Markup.button.url("访问网站", "https://example.com")],
    ])
  );
});

// 处理按钮回调
bot.action("action_a", (ctx) => {
  ctx.answerCbQuery();
  ctx.editMessageText("你选择了选项 A！");
});

bot.action("action_b", (ctx) => {
  ctx.answerCbQuery();
  ctx.editMessageText("你选择了选项 B！");
});

// 处理文本消息
bot.on("text", (ctx) => {
  ctx.reply(`你说的是：${ctx.message.text}`);
});

bot.launch();
console.log("机器人正在运行...");

// 优雅停机
process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

第七步：在生产环境中设置 Webhooks

轮询 (Polling) 适用于开发阶段，但生产环境的机器人应使用 Webhooks 以获得更好的性能：

# 在 python-telegram-bot 中使用 webhooks
from telegram.ext import Application

app = Application.builder().token("YOUR_BOT_TOKEN").build()

# 在此注册你的处理器...

# 启动 webhook
app.run_webhook(
    listen="0.0.0.0",
    port=8443,
    url_path="YOUR_BOT_TOKEN",
    webhook_url=f"https://your-domain.com/{YOUR_BOT_TOKEN}"
)

或者手动设置 Webhook：

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook" \
  -d "url=https://your-domain.com/webhook/YOUR_BOT_TOKEN"

部署选项

平台	费用	设置难度	最佳用途
Railway	免费层级	简单	快速部署
Render	免费层级	简单	简单机器人
AWS Lambda	免费层级	中等	事件驱动型机器人
Google Cloud Run	免费层级	中等	可扩展机器人
VPS (Hetzner, DigitalOcean)	$4-5/月	中等	完全控制
Fly.io	免费层级	简单	全球化部署

部署到 Railway

# 安装 Railway CLI
npm install -g @railway/cli

# 登录并部署
railway login
railway init
railway up

在 Railway 控制面板中将你的 BOT_TOKEN 添加为环境变量。

Bot API 速率限制

在构建机器人时，请记住以下限制：

限制项	数值
发给单一用户的消息	每秒 30 条
发给群组的消息	每分钟 20 条
群发消息	所有聊天总计每秒 30 条
文件上传	最大 50 MB
文件下载	最大 20 MB
内联查询结果	最多 50 条结果

常见问题解答

Telegram Bot API 收费吗？ Telegram Bot API 完全免费。没有使用费、没有按速率计费，也没有高级层级。

我的机器人可以访问聊天历史记录吗？ 机器人只能看到被添加到群组后发送的消息，且前提是它拥有相应的权限。它无法读取之前的历史消息。

如何让我的机器人在群组中工作？ 将你的机器人添加到群组并确保它拥有必要的权限。使用 MessageHandler 来响应消息，或者设置机器人仅响应命令。

我可以通过机器人接受付款吗？ 可以，Telegram 通过 Stripe 和其他支付提供商支持原生支付。使用 sendInvoice 方法来创建付款请求。

如何保证我机器人 Token 的安全？ 永远不要在源代码中硬编码 Token。使用环境变量或密钥管理器。如果你的 Token 泄露，请立即通过 BotFather 使用 /revoke 命令重新生成。

总结

Telegram Bot API 是目前对开发者最友好的机器人平台之一。凭借免费的无限使用、卓越的文档支持，以及从简单命令机器人到全功能迷你应用的支持，它是构建自动化工具和服务的理想平台。

如果你正在构建一个可以生成 AI 媒体（如图像、视频或数字人头像）的 Telegram 机器人，可以免费试用 Hypereal AI —— 提供 35 个额度，无需信用卡。其 API 可以轻松与任何 Telegram 机器人集成，实现按需生成 AI 内容。