Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
Telegram 为网站提供了四种小部件:Telegram 登录(让用户用 Telegram 账号登录你的网站)、帖子小部件(嵌入公开频道或群组中的消息)、评论区小部件(显示频道帖子的评论)以及分享按钮。每一种都只是一小段代码,粘贴到你自己的 HTML 中即可。注意,它们并不是 Bot API 10.4 起机器人在聊天消息里发送的交互式小组件;那部分内容请看 Telegram 机器人消息中的小组件。
Telegram 网站小部件一览
| 小部件 | 作用 | 需要机器人吗? | 如何获取代码 |
|---|---|---|---|
| Telegram 登录 | 用 Telegram 账号注册和登录(OpenID Connect) | 需要,另外要在 @BotFather 中配置 Allowed URLs 并获取 Client ID | core.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。
- 准备一个代表网站的机器人(参见创建 Telegram 机器人教程)。用户在确认登录的弹窗中会看到它的名称和头像,所以最好与网站名称和 Logo 保持一致。
- 登记 Allowed URLs。打开 @BotFather 的 Mini App,选择机器人,进入 Login Widget。添加嵌入按钮的页面 origin(如
https://example.com)以及 OIDC 重定向 URI(如https://example.com/auth/callback)。Telegram 只会为这些预先登记的地址处理登录和跳转。 - 保存 Client ID 和 Client Secret,它们显示在同一页面。Secret 只能放在服务器上。
- 在页面上添加按钮。
- 在服务器端验证 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、姓名、用户名、头像 URL | id、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。它的文档已经归档,新项目请使用上面的新流程;如果你在维护老项目,下面是旧版的工作方式。
- 向 @BotFather 发送
/setdomain,把网站域名绑定到机器人。 - 嵌入脚本。使用回调函数的写法:
<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;
常见问题排查
- 旧版小部件显示 “Bot domain invalid”。域名没有绑定到机器人。在 @BotFather 中对该机器人发送
/setdomain,填写页面所在的确切域名。 - 新版登录没有反应或被拒绝。页面 origin 或重定向 URI 没有加入 @BotFather 的 Allowed URLs,或者
Cross-Origin-Opener-Policy: same-origin响应头拦截了弹窗。 - 小部件不显示。
telegram-widget.js从telegram.org加载,并插入一个 iframe:帖子、评论区和分享按钮来自t.me,旧版登录来自oauth.telegram.org。严格的 Content-Security-Policy(script-src、frame-src)或广告拦截插件都可能把它们挡掉。 - hash 不匹配。Token 用错;直接用 Token 而不是它的 SHA256 作为密钥;data-check-string 中混入了多余字段(你自己的查询参数);字段值被改动;或者分隔符用错了。应使用
\n,而不是&。 - 帖子无法嵌入。只有公开频道和公开群组的消息才能嵌入;私密聊天没有公开的 t.me 链接。
- 文章页面的评论区是空的。检查页面是否有 canonical 链接标签,以及你在频道中发布的链接是否正好指向这个规范 URL。
下一步
- 创建 Telegram 机器人,在登录窗口中代表你的网站。
- 查找、检查和撤销机器人 Token,旧版 hash 校验需要用到它。
- Telegram 机器人消息中的小组件:Bot API 10.4 的 HTML 小组件,是完全不同的功能。
- 官方文档:core.telegram.org/widgets。
常见问题
怎么在网站上添加“用 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 的区别。