Telegram Bot API

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

· 9 分钟阅读

Telegram 为网站提供了四种小部件:Telegram 登录(让用户用 Telegram 账号登录你的网站)、帖子小部件(嵌入公开频道或群组中的消息)、评论区小部件(显示频道帖子的评论)以及分享按钮。每一种都只是一小段代码,粘贴到你自己的 HTML 中即可。注意,它们并不是 Bot API 10.4 起机器人在聊天消息里发送的交互式小组件;那部分内容请看 Telegram 机器人消息中的小组件。

Telegram 网站小部件一览

小部件作用需要机器人吗?如何获取代码
Telegram 登录用 Telegram 账号注册和登录(OpenID Connect)需要,另外要在 @BotFather 中配置 Allowed URLs 并获取 Client IDcore.telegram.org/bots/telegram-login 上的生成器
Login Widget(旧版)早期基于 iframe 的登录按钮,文档已归档需要,并用 /setdomain 绑定域名core.telegram.org/widgets/login-legacy
帖子小部件嵌入公开频道或群组中的一条消息不需要t.me 链接 → EMBED,或帖子生成器
评论区小部件显示频道帖子及其评论不需要评论区生成器
分享按钮让访客把你的链接发到私聊、群组、频道或“收藏夹”(Saved Messages)不需要分享按钮生成器或一个普通链接

新版 Telegram 登录:用 OpenID Connect 登录网站

当前的 Telegram 登录由一个 JavaScript 库和一个标准的 OpenID Connect 提供方组成,采用带 PKCE 的授权码模式(Authorization Code Flow)。你可以直接用库自带的按钮,也可以用任何兼容 OIDC 的库或身份平台(官方举例了 Keycloak、Authentik 和 Auth0),移动端还有 iOS 和 Android 原生 SDK。

  1. 准备一个代表网站的机器人(参见创建 Telegram 机器人教程)。用户在确认登录的弹窗中会看到它的名称和头像,所以最好与网站名称和 Logo 保持一致。
  2. 登记 Allowed URLs。打开 @BotFather 的 Mini App,选择机器人,进入 Login Widget。添加嵌入按钮的页面 origin(如 https://example.com)以及 OIDC 重定向 URI(如 https://example.com/auth/callback)。Telegram 只会为这些预先登记的地址处理登录和跳转。
  3. 保存 Client ID 和 Client Secret,它们显示在同一页面。Secret 只能放在服务器上。
  4. 在页面上添加按钮。
  5. 在服务器端验证 ID token,验证通过之前不要信任任何用户数据。

官方生成器给出的嵌入代码如下(data-request-access 可选:write 允许机器人给用户发消息,phone 请求经过验证的手机号):

<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>

<button class="tg-auth-button">使用 Telegram 登录</button>

<script>
  function onTelegramAuth(data) {
    if (data.error) return console.warn(data.error);
    // 把 data.id_token 发到服务器,并在服务器上验证
    fetch('/auth/telegram', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({id_token: data.id_token})
    });
  }
</script>

回调函数会收到 id_token(OIDC 的 JWT)、user(解码后的 claims)或 error。该库还提供 JS API:Telegram.Login.init(InitOptions, callback)、Telegram.Login.open([callback]) 和 Telegram.Login.auth(InitOptions, callback),可用选项有 client_id、scope、lang 和 nonce(由服务器生成的随机字符串,会写入 id_token,用于防止重放攻击)。

弹窗与 COOP:telegram-login.js 依赖与弹出窗口通信。如果网站返回了 Cross-Origin-Opener-Policy: same-origin 响应头,登录会失败;请去掉该响应头,或改为 same-origin-allow-popups。

Scope 与 OIDC 端点

Scope能拿到什么Claims
openid必填。唯一标识和认证时间sub、iss、iat、exp
profile用户 ID、姓名、用户名、头像 URLid、name、preferred_username、picture
phone经过验证的手机号(需用户同意)phone_number
telegram:bot_access登录后机器人可以给用户发消息—

如果使用 OIDC 客户端库,配置发现文档 https://oauth.telegram.org/.well-known/openid-configuration,response type 设为 code,PKCE 使用 S256。如果自己实现整个流程,端点分别是 https://oauth.telegram.org/auth、https://oauth.telegram.org/token(服务器端 POST,Basic 认证 base64(client_id:client_secret))和 https://oauth.telegram.org/.well-known/jwks.json。Telegram 没有单独的 UserInfo 端点,所有数据都在 ID token 中;如果你的库默认会请求 userinfo,需要把这一步关掉。

验证 ID token

先用 JWKS 端点提供的公钥验证 JWT 签名,再检查 iss 是否为 https://oauth.telegram.org、aud 是否等于你的机器人 ID(即作为 client_id 传入的值),以及 exp 是否已过期。默认签名算法是 RS256;也可以在 @BotFather 的 Login Widget > Advanced 中改为 ES256、EdDSA 或 ES256K(EdDSA 和 ES256K 只支持 openid scope)。下面是用 Node.js 的 jose 库验证的示例:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));

export async function verifyTelegramIdToken(idToken) {
  const { payload } = await jwtVerify(idToken, JWKS, {
    issuer: 'https://oauth.telegram.org',
    audience: '123456789' // 你的 Client ID(机器人 ID)
  });
  return payload; // sub, id, name, preferred_username, picture, phone_number...
}

旧版 Telegram Login Widget

不少网站仍在使用最初基于 iframe 的 Login Widget。它的文档已经归档,新项目请使用上面的新流程;如果你在维护老项目,下面是旧版的工作方式。

  1. 向 @BotFather 发送 /setdomain,把网站域名绑定到机器人。
  2. 嵌入脚本。使用回调函数的写法:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
  function onTelegramAuth(user) {
    alert('已登录:' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
  }
</script>

也可以不用 data-onauth,改为设置 data-auth-url="https://example.com/auth/telegram":用户会被重定向到该地址,查询参数中带有 id、first_name、last_name、username、photo_url、auth_date 和 hash。生成器中的其他选项:data-size(large、medium、small)、data-userpic="false"、data-radius 以及 data-request-access="write"。

在服务器端校验 hash

数据在校验通过之前一律不可信。算法如下:取除 hash 以外的所有字段,按字母顺序排序,拼成 key=value 并用换行符(\n)连接,得到 data-check-string;密钥是机器人 Token 的 SHA256 值(原始字节);用该密钥对 data-check-string 计算 HMAC-SHA-256,把十六进制结果与 hash 比较。之后再确认 auth_date(Unix 时间戳)足够新。只传入 Telegram 发来的字段,不要混入你自己的查询参数。

import hashlib
import hmac
import time

def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
    fields = {k: v for k, v in data.items() if k != "hash"}
    data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
    secret_key = hashlib.sha256(bot_token.encode()).digest()
    calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
        return False
    return time.time() - int(fields["auth_date"]) <= max_age

# Flask:check_telegram_auth(request.args.to_dict(), BOT_TOKEN)
const crypto = require('crypto');

function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
  const { hash, ...fields } = data;
  const dataCheckString = Object.keys(fields).sort()
    .map((k) => `${k}=${fields[k]}`)
    .join('\n');
  const secretKey = crypto.createHash('sha256').update(botToken).digest();
  const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
  if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
  return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}

// Express:checkTelegramAuth(req.query, process.env.BOT_TOKEN)

校验失败最常见的原因是 Token 用错了。可以用 Bot API Tester 中的 getMe 确认服务器上的 Token 确实属于登录用的机器人:返回的 username 必须与 data-telegram-login 一致。如果要查找或更换 Token,请参阅 Telegram Bot Token 获取与管理教程。注意,这与 Mini App 的 initData 校验不同,后者是用 HMAC 和字符串 WebAppData 派生密钥的。

嵌入 Telegram 帖子

公开频道或群组中的任何消息都可以嵌入网页。在浏览器中打开它的 t.me 链接(例如 t.me/durov/43),点击 < > EMBED;或者把链接粘贴到帖子小部件生成器中。得到的是一个 script 标签:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>

生成器提供的选项:宽度(data-width,默认 100%)、作者头像(data-userpic="true" 始终显示,"false" 隐藏,不写则自动)、强调色(data-color,十六进制值,如 13B4C6)以及深色主题(data-dark="1";设置了颜色时,生成器还可能加上 data-dark-color)。

评论区小部件:在网站上显示 Telegram 评论

评论区小部件会显示一条公开频道帖子及其评论。传入一条带评论的帖子链接即可:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>

也可以只传频道名(data-telegram-discussion="your_channel")。这样一来,只要你在频道里发布了某篇文章的链接,该文章页面就会显示这条频道帖子下的讨论。使用这种模式时,页面的 head 中必须包含 <link rel="canonical" href="%page_url%">,指向页面的规范 URL。其他选项:评论数量(data-comments-limit,生成器中可选 3–50)、data-height、data-colorful="1"(不同用户名显示不同颜色)、data-color 和 data-dark="1"。

Telegram 分享按钮

访客点击分享按钮后,Telegram 会让他选择一个聊天、群组或频道,并且可以在发送前修改附带的文字(可选)。core.telegram.org/widgets/share 上的生成器会给出这样的代码:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="推荐看看这篇!" data-size="large"></script>

不写 data-size 时是中号按钮;data-text="notext" 只显示图标。如果想用自己的样式,直接链接到 https://t.me/share/url?url={url}&text={text},两个参数都要做 URL 编码:

<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=%E6%8E%A8%E8%8D%90%E7%9C%8B%E7%9C%8B%E8%BF%99%E7%AF%87%EF%BC%81">分享到 Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
  + '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;

常见问题排查

下一步

常见问题

怎么在网站上添加“用 Telegram 登录”按钮?

准备一个机器人,打开 @BotFather 的 Mini App,选择该机器人后进入 Login Widget,把网站的 origin 和重定向 URI 加入 Allowed URLs,并复制 Client ID。然后在页面中加入带 data-client-id 的 telegram-login.js 代码,并在服务器上验证返回的 id_token。

旧版 Telegram Login Widget 还能用吗?

它的文档已归档到 core.telegram.org/widgets/login-legacy。Telegram 现在把 Telegram Login 库和 OpenID Connect 流程作为“用 Telegram 登录”的主要方式,新项目建议优先使用新方案。

如何在服务器端校验 Telegram Login Widget 返回的数据?

对于旧版小部件:取除 hash 以外的所有字段,按字母顺序排序,拼成 key=value 并用 \n 连接得到 data-check-string;以 SHA256(bot_token) 为密钥计算 HMAC-SHA-256,将十六进制结果与 hash 比较,并检查 auth_date。对于新版登录,用 Telegram 的 JWKS 验证 id_token(JWT)。

怎么把 Telegram 帖子嵌入到网站?

在浏览器中打开帖子的 t.me 链接(例如 t.me/durov/43)并点击 EMBED,或者使用 core.telegram.org/widgets/post 上的生成器。只有公开频道和公开群组的消息才能嵌入。

如何自定义 Telegram 分享按钮?

链接到 https://t.me/share/url?url={url}&text={text},两个参数都要做 URL 编码,在 JavaScript 中可以用 encodeURIComponent。text 是可选的,用户发送前还可以修改。

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

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

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 测试服务器:如何在 Telegram 测试环境中测试机器人

Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 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 的区别。