Telegram Bot API

Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘

· 9 分钟阅读

Telegram 内联键盘(inline keyboard)是附在机器人消息下方的一组按钮:在 sendMessage 的 reply_markup 参数中传入 InlineKeyboardMarkup 对象即可;用户点击回调按钮后,机器人会收到 callback_query 更新,必须用 answerCallbackQuery 应答。回复键盘(ReplyKeyboardMarkup)则是用预设的选项替换用户的输入法键盘。本文介绍这两种 Telegram 机器人按钮、所有按钮类型、点击后如何编辑消息,并给出完整可运行的 Python 和 JavaScript 示例。

内联键盘与回复键盘对比

内联键盘回复键盘
对象InlineKeyboardMarkupReplyKeyboardMarkup
显示位置某条消息的下方替代用户的键盘
点击效果回调查询、打开 URL、Mini App、内联模式、复制文本等把按钮文字作为消息发送,或分享联系人、位置、用户、聊天
能否事后编辑可以,使用 editMessageReplyMarkup不能,只能发送新键盘或移除
频道支持不支持

两者都放在同一个 reply_markup 参数中,此外还有 ReplyKeyboardRemove 和 ForceReply。一条消息只能带这四种对象中的一种。

发送 Telegram 内联键盘

inline_keyboard 是一个由“行”组成的数组,每一行又是一个按钮数组:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "请选择:",
    "reply_markup": {
      "inline_keyboard": [
        [{"text": "点赞", "callback_data": "like"}, {"text": "帮助", "callback_data": "help"}],
        [{"text": "Bot API 文档", "url": "https://core.telegram.org/bots/api"}]
      ]
    }
  }'

除了 text,每个按钮必须恰好有一个决定其类型的字段:

字段按钮作用
callback_data向机器人发送带有该字符串的回调查询,1–64 字节
url打开 HTTP 或 tg:// 链接
web_app启动 Mini App;仅限用户与机器人的私聊
login_url打开 HTTPS 地址,并在你的网站上为用户完成授权
switch_inline_query、switch_inline_query_current_chat、switch_inline_query_chosen_chat把机器人的用户名和查询内容填入另一个聊天、当前聊天或指定类型聊天的输入框
copy_text把 {"text": "…"}(1–256 个字符)复制到剪贴板
pay支付按钮;只能用于账单消息,且必须是第一行的第一个按钮
callback_game启动游戏;必须是第一行的第一个按钮
disabled点击后无反应的 DisabledButton(Bot API 10.3)

还有两个可选字段用于改变按钮外观(Bot API 9.4,回复键盘按钮同样适用):style,可取 "danger"(红色)、"success"(绿色)或 "primary"(蓝色);以及 icon_custom_emoji_id,在文字前显示自定义表情。自定义表情只有在机器人有权使用时才生效:机器人在 Fragment 上购买了附加用户名,或者机器人所有者开通了 Telegram Premium 且消息直接发送到私聊、群组或超级群组。

如何设计 callback_data

64 字节的限制按字节而不是字符计算,所以值要简短、便于程序解析,例如 like、page:3 或 del:8812,真实数据存放在数据库中。API 文档还提醒,收到的 data 可能在消息中根本没有对应的按钮,所以要把它当作不可信的用户输入:先解析、校验,再确认用户有权执行该操作。值过长时,发送键盘就会被拒绝,通常返回 Bad Request: BUTTON_DATA_INVALID。

每次点击都要用 answerCallbackQuery 应答

点击回调按钮会产生一个带 callback_query 字段的更新,其中包含 id、from(用户)、data,对于机器人发出的消息还有包含原始消息的 message。点击之后,Telegram 客户端会一直显示进度指示,直到机器人调用 answerCallbackQuery,所以每次都要调用,哪怕除了 id 之外不带任何参数。

参数含义
callback_query_id必填,回调查询的 id
text通知文本,0–200 个字符;不传则不显示任何内容
show_alert为 true 时显示弹窗,而不是聊天顶部的通知
url游戏 URL(用于 callback_game 按钮)或 t.me/your_bot?start=XXXX 形式的链接
cache_time结果在客户端可缓存的秒数,默认 0

应答要快:过期的查询会返回 Bad Request: query is too old and response timeout expired or query ID is invalid。详情见 answerCallbackQuery 方法参考。

点击后编辑消息

更新已有消息比发送新消息更快、更整洁,Telegram 也推荐在设置菜单和分页中这样做。从 callback_query.message 中取出 chat.id 和 message_id,然后调用:

如果新的文本和键盘与当前完全相同,API 会返回 Bad Request: message is not modified,所以编辑前先比较,或者忽略这个特定错误。

完整示例:带回调按钮的内联菜单

这个机器人收到 /start 后回复一个菜单,按消息统计点赞数,点击“帮助”时弹窗提示,每次数据变化都会编辑原消息。它使用 getUpdates 长轮询,无需 Webhook 就能在本地运行。请先在环境变量中设置 BOT_TOKEN。

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {}  # (chat_id, message_id) -> 点赞数


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def menu(count):
    return {"inline_keyboard": [
        [{"text": f"点赞 ({count})", "callback_data": "like", "style": "success"},
         {"text": "重置", "callback_data": "reset", "style": "danger"}],
        [{"text": "帮助", "callback_data": "help"},
         {"text": "Bot API 文档", "url": "https://core.telegram.org/bots/api"}],
    ]}


def on_callback(cq):
    msg, data = cq.get("message"), cq.get("data")
    if not msg or data not in ("like", "reset", "help"):
        call("answerCallbackQuery", callback_query_id=cq["id"], text="未知按钮")
        return
    if data == "help":
        call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
             text="“点赞”加一,“重置”从头计数。")
        return
    key = (msg["chat"]["id"], msg["message_id"])
    old = likes.get(key, 0)
    new = old + 1 if data == "like" else 0
    call("answerCallbackQuery", callback_query_id=cq["id"],
         text="谢谢!" if data == "like" else "计数已重置")
    if new != old:  # 避免 "message is not modified"
        likes[key] = new
        call("editMessageText", chat_id=key[0], message_id=key[1],
             text=f"点赞数:{new}", reply_markup=menu(new))


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "callback_query"])
    for update in updates:
        offset = update["update_id"] + 1
        if "callback_query" in update:
            on_callback(update["callback_query"])
        elif update.get("message", {}).get("text") == "/start":
            chat_id = update["message"]["chat"]["id"]
            call("sendMessage", chat_id=chat_id, text="点赞数:0", reply_markup=menu(0))
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> 点赞数

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

function menu(count) {
  return { inline_keyboard: [
    [{ text: `点赞 (${count})`, callback_data: "like", style: "success" },
     { text: "重置", callback_data: "reset", style: "danger" }],
    [{ text: "帮助", callback_data: "help" },
     { text: "Bot API 文档", url: "https://core.telegram.org/bots/api" }],
  ] };
}

async function onCallback(cq) {
  const msg = cq.message;
  const data = cq.data;
  if (!msg || !["like", "reset", "help"].includes(data)) {
    await call("answerCallbackQuery", { callback_query_id: cq.id, text: "未知按钮" });
    return;
  }
  if (data === "help") {
    await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
      text: "“点赞”加一,“重置”从头计数。" });
    return;
  }
  const key = `${msg.chat.id}:${msg.message_id}`;
  const old = likes.get(key) ?? 0;
  const next = data === "like" ? old + 1 : 0;
  await call("answerCallbackQuery", { callback_query_id: cq.id,
    text: data === "like" ? "谢谢!" : "计数已重置" });
  if (next !== old) { // 避免 "message is not modified"
    likes.set(key, next);
    await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
      text: `点赞数:${next}`, reply_markup: menu(next) });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", { offset, timeout: 30,
    allowed_updates: ["message", "callback_query"] });
  for (const update of updates) {
    offset = update.update_id + 1;
    if (update.callback_query) {
      await onCallback(update.callback_query);
    } else if (update.message?.text === "/start") {
      await call("sendMessage", { chat_id: update.message.chat.id, text: "点赞数:0",
        reply_markup: menu(0) });
    }
  }
}

JavaScript 版本请保存为 bot.mjs(用到了顶层 await),用 Node.js 18+ 运行。计数器保存在内存中,实际项目应存入数据库。如果想使用默认按钮颜色,去掉 style 字段即可。

Telegram 回复键盘

回复键盘提供预设的回答选项。普通文本按钮(也可以直接写成一个字符串)会把按钮文字发到聊天中,就像用户自己输入的一样,所以机器人像处理其他消息一样处理即可:

{
  "keyboard": [
    ["商品目录", "购物车"],
    [{"text": "分享手机号", "request_contact": true},
     {"text": "发送位置", "request_location": true}]
  ],
  "resize_keyboard": true,
  "one_time_keyboard": true,
  "input_field_placeholder": "请选择栏目"
}
字段效果
resize_keyboard按行数自动调整高度;默认与标准键盘一样高
one_time_keyboard点击后收起键盘;用户可以通过键盘图标再次打开
is_persistent普通键盘收起时始终显示该键盘
input_field_placeholder输入框中的占位提示,1–64 个字符
selective只对被 @提及的用户或被回复消息的发送者显示键盘

特殊按钮只能在私聊中使用:request_contact 以联系人形式发送用户的手机号,request_location 发送用户当前位置,request_poll 请用户创建投票,web_app 启动 Mini App。request_users(KeyboardButtonRequestUsers)和 request_chat(KeyboardButtonRequestChat)会打开选择器,结果通过 users_shared 和 chat_shared 服务消息返回;两者都需要 request_id,即一个在该消息内唯一的有符号 32 位整数:

{"keyboard": [[
  {"text": "选择用户", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
  {"text": "选择我的群组", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}

ReplyKeyboardRemove 与 ForceReply

回复键盘会一直显示,直到机器人发送另一个键盘。要移除它,发送一条带 {"remove_keyboard": true} 的消息。ForceReply({"force_reply": true, "input_field_placeholder": "你所在的城市"})会打开针对机器人这条消息的回复界面,就像用户点了“回复”一样。它很适合在群组中分步收集输入,因为即使开启了隐私模式,这样的回答也能送达机器人。与回复键盘一样,这两个对象在频道中都不起作用。

在 Bot API Tester 中试一试

  1. 打开 Bot API Tester 的 sendMessage,填入你的 Token 和 chat id。
  2. 把上面任意一个 JSON 键盘粘贴到 reply_markup 中并执行。
  3. 在 Telegram 中点击回调按钮,然后在测试工具中执行 getUpdates 查看 callback_query 更新,再用 answerCallbackQuery 应答。

Telegram 机器人按钮常见问题排查

现象原因与解决方法
点击后一直显示加载没有调用 answerCallbackQuery。每个回调查询都要应答。
收不到 callback_query 更新allowed_updates 中没有 callback_query,或者更新被其他进程取走了(Webhook 或第二个轮询实例)。
BUTTON_DATA_INVALIDcallback_data 为空或超过 64 字节。
message is not modified编辑没有改变文本或键盘。
query is too old…应答太晚,例如重启后处理了旧的更新。
联系人或位置按钮在群组中无反应这些按钮只能在私聊中使用。

完整的错误信息列表见 Telegram Bot API 错误码大全。格式设置和 sendMessage 的其他选项见 Telegram Bot API 发送消息教程,切换到内联模式的按钮可以配合 内联模式 使用。

常见问题

Telegram 的内联键盘和回复键盘有什么区别?

内联键盘(InlineKeyboardMarkup)附在某条消息下方,点击按钮不会往聊天里发送任何内容。回复键盘(ReplyKeyboardMarkup)会替换用户的输入法键盘,点击普通文本按钮会把按钮文字作为一条普通消息发出。

callback_data 最长可以多长?

1–64 字节。注意是字节而不是字符:非拉丁字符在 UTF-8 中占 2 个或更多字节,一个汉字一般占 3 字节。按钮里只放 item:42 这样的短键,真实数据保存在服务器上。

为什么点击按钮后一直显示加载状态?

机器人没有调用 answerCallbackQuery。在应答之前,Telegram 客户端会一直显示进度条,所以每个回调查询都要应答,即使不带 text。

用户点击按钮后如何更换按钮?

用 callback_query.message 中的 chat_id 和 message_id 调用 editMessageReplyMarkup 只替换键盘,或者调用 editMessageText 同时修改文本和键盘。

如何移除回复键盘?

发送一条 reply_markup 为 {"remove_keyboard": true}(ReplyKeyboardRemove)的消息。如果只想在点击一次后收起键盘、但仍可再次打开,请改用 one_time_keyboard。

频道里的消息可以加按钮吗?

内联键盘可以。回复键盘、ReplyKeyboardRemove 和 ForceReply 在频道中都不支持。

Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息

Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。

Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案

Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。

Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等

Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。

Telegram Bot API 错误码大全:每种报错的含义与解决方法

Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。

Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度

Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。

Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接

Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。

n8n Telegram 集成教程:连接机器人、触发工作流并发送消息

n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。

Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理

Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。

Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token

Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。

Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token

Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。

Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID

Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。

Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询

Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。

Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅

Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。

Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人

Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。

Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮

在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。

TelegramWidget JavaScript API:属性、事件、错误码与限制参考

TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。

Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码

可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。

Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML

Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。

Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端

Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。