Telegram Bot API

Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ

· 9 phút đọc

Telegram có bốn widget cho website: Telegram Login (cho phép người dùng đăng nhập bằng tài khoản Telegram), widget bài đăng (nhúng một tin nhắn từ kênh hoặc nhóm công khai), widget thảo luận (hiện bình luận của một bài trong kênh) và nút chia sẻ. Mỗi widget chỉ là một đoạn mã nhỏ bạn dán vào HTML của mình. Đây không phải là widget tương tác mà bot gửi trong tin nhắn từ Bot API 10.4; loại đó xem ở bài widget Telegram trong tin nhắn bot.

Tổng quan các widget Telegram cho website

WidgetChức năngCần bot?Lấy mã ở đâu
Telegram LoginĐăng ký và đăng nhập bằng tài khoản Telegram (OpenID Connect)Có, kèm Allowed URLs và Client ID từ @BotFatherTrình tạo mã tại core.telegram.org/bots/telegram-login
Login Widget (cũ)Nút đăng nhập dạng iframe đời trước, nay đã lưu trữCó, domain phải được gắn bằng /setdomaincore.telegram.org/widgets/login-legacy
Widget bài đăngNhúng một tin nhắn từ kênh hoặc nhóm công khaiKhôngLink t.me → EMBED, hoặc trình tạo mã bài đăng
Widget thảo luậnHiện bài đăng của kênh kèm bình luậnKhôngTrình tạo mã thảo luận
Nút chia sẻCho khách gửi link của bạn vào chat, nhóm, kênh hoặc Saved MessagesKhôngTrình tạo nút chia sẻ hoặc một link thường

Telegram Login: đăng nhập bằng Telegram kiểu mới (OpenID Connect)

Telegram Login hiện tại gồm một thư viện JavaScript và một provider OpenID Connect chuẩn, dùng Authorization Code Flow với PKCE. Bạn có thể dùng nút của thư viện, bất kỳ thư viện hay nền tảng định danh nào tương thích OIDC (Telegram nêu ví dụ Keycloak, Authentik và Auth0), hoặc SDK native cho iOS và Android.

  1. Chuẩn bị một bot đại diện cho website (cách tạo bot Telegram). Người dùng sẽ thấy tên và ảnh đại diện của bot trong hộp xác nhận, nên hãy đặt trùng tên và logo của site.
  2. Đăng ký Allowed URLs. Mở mini app của @BotFather, chọn bot, rồi vào Login Widget. Thêm các origin có đặt nút (ví dụ https://example.com) và redirect URI của OIDC (ví dụ https://example.com/auth/callback). Telegram chỉ xử lý đăng nhập và chuyển hướng cho những URL đã đăng ký trước.
  3. Lưu Client ID và Client Secret hiển thị ngay trong mục đó. Secret chỉ được nằm trên server.
  4. Chèn nút vào trang.
  5. Xác minh ID token trên server trước khi tin bất kỳ dữ liệu người dùng nào.

Mã nhúng do trình tạo mã chính thức sinh ra trông như sau (data-request-access là tùy chọn: write cho phép bot nhắn tin cho người dùng, phone xin số điện thoại đã xác minh):

<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">Đăng nhập bằng Telegram</button>

<script>
  function onTelegramAuth(data) {
    if (data.error) return console.warn(data.error);
    // Gửi data.id_token lên server và xác minh ở đó
    fetch('/auth/telegram', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({id_token: data.id_token})
    });
  }
</script>

Callback nhận id_token (JWT của OIDC), user (các claim đã giải mã) hoặc error. Thư viện còn có JS API: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]) và Telegram.Login.auth(InitOptions, callback), với các tùy chọn client_id, scope, lang và nonce (chuỗi ngẫu nhiên do server tạo, được đưa vào id_token để chống tấn công replay).

Popup và COOP: telegram-login.js giao tiếp với một cửa sổ popup. Nếu site gửi header Cross-Origin-Opener-Policy: same-origin, đăng nhập sẽ thất bại; hãy bỏ header này hoặc đổi sang same-origin-allow-popups.

Scope và endpoint OIDC

ScopeBạn nhận đượcClaim
openidBắt buộc. Định danh duy nhất và thời điểm xác thựcsub, iss, iat, exp
profileUser ID, tên, username, URL ảnh đại diệnid, name, preferred_username, picture
phoneSố điện thoại đã xác minh, khi người dùng đồng ýphone_number
telegram:bot_accessBot được phép nhắn tin cho người dùng sau khi đăng nhập—

Với client OIDC, dùng discovery document https://oauth.telegram.org/.well-known/openid-configuration, response type code và PKCE S256. Nếu tự cài đặt luồng, các endpoint là https://oauth.telegram.org/auth, https://oauth.telegram.org/token (POST từ server với Basic auth base64(client_id:client_secret)) và https://oauth.telegram.org/.well-known/jwks.json. Telegram không có endpoint UserInfo riêng: mọi dữ liệu nằm trong ID token, nên nếu thư viện mặc định gọi userinfo thì hãy tắt bước đó.

Xác minh ID token

Kiểm tra chữ ký JWT bằng khóa từ endpoint JWKS, sau đó kiểm tra iss là https://oauth.telegram.org, aud trùng với ID của bot (giá trị bạn truyền vào client_id) và exp chưa hết hạn. Token mặc định được ký bằng RS256; có thể chọn ES256, EdDSA hoặc ES256K trong Login Widget > Advanced của @BotFather (EdDSA và ES256K chỉ cho phép scope openid). Ví dụ Node.js với thư viện 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 của bạn (ID của bot)
  });
  return payload; // sub, id, name, preferred_username, picture, phone_number...
}

Telegram Login Widget kiểu cũ (legacy)

Nhiều website vẫn đang chạy Login Widget dạng iframe đời đầu. Tài liệu của nó đã được lưu trữ, nên dự án mới hãy dùng luồng ở trên; còn nếu bạn đang bảo trì bản cũ thì nó hoạt động như sau.

  1. Gửi /setdomain cho @BotFather để gắn domain của website với bot.
  2. Nhúng script. Ví dụ với callback:
<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('Đã đăng nhập: ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
  }
</script>

Thay cho data-onauth, bạn có thể đặt data-auth-url="https://example.com/auth/telegram": người dùng sẽ được chuyển tới đó kèm id, first_name, last_name, username, photo_url, auth_date và hash dưới dạng query parameter. Các tùy chọn khác trong trình tạo mã: data-size (large, medium, small), data-userpic="false", data-radius và data-request-access="write".

Kiểm tra hash trên server

Đừng tin dữ liệu khi chưa xác minh. Thuật toán: lấy mọi trường nhận được trừ hash, sắp xếp theo bảng chữ cái, nối thành các dòng key=value bằng ký tự xuống dòng (\n) để được data-check-string; khóa bí mật là SHA256 của token bot (dạng byte thô); tính HMAC-SHA-256 của data-check-string với khóa đó rồi so dạng hex với hash. Sau đó kiểm tra auth_date (Unix timestamp) còn mới. Chỉ đưa vào các trường Telegram gửi, không trộn query parameter của riêng bạn.

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)

Nguyên nhân sai hash phổ biến nhất là dùng nhầm token. Hãy kiểm tra token trên server có đúng là của bot đăng nhập hay không bằng getMe trong Bot API Tester: username trả về phải trùng với data-telegram-login. Cần tìm lại hoặc đổi token thì xem bài cách lấy token bot Telegram. Lưu ý cách này khác với kiểm tra initData của Mini App, nơi khóa được tạo bằng HMAC với chuỗi WebAppData.

Nhúng bài đăng Telegram vào website

Bạn có thể nhúng bất kỳ tin nhắn nào từ kênh hoặc nhóm công khai. Mở link t.me của bài (ví dụ t.me/durov/43) trên trình duyệt và bấm < > EMBED, hoặc dán link vào trình tạo mã widget bài đăng. Kết quả là một thẻ script duy nhất:

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

Các tùy chọn trong trình tạo mã: chiều rộng (data-width, mặc định 100%), ảnh tác giả (data-userpic="true" để luôn hiện, "false" để ẩn, bỏ trống để tự động), màu nhấn (data-color với mã hex như 13B4C6) và giao diện tối (data-dark="1"; khi có màu, trình tạo mã có thể thêm data-dark-color).

Widget thảo luận: bình luận Telegram trên website

Widget thảo luận hiển thị một bài đăng của kênh công khai cùng các bình luận. Truyền cho nó link tới một bài có bật bình luận:

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

Bạn cũng có thể chỉ truyền tên kênh (data-telegram-discussion="your_channel"). Khi đó mỗi trang bài viết sẽ hiện phần thảo luận của bài đăng trong kênh có chứa link tới trang đó, ngay khi bạn đăng link ấy lên kênh. Ở chế độ này, phần head của trang phải có <link rel="canonical" href="%page_url%"> với URL canonical của trang. Tùy chọn: số bình luận (data-comments-limit, 3–50 trong trình tạo mã), data-height, data-colorful="1" để tên có màu khác nhau, data-color và data-dark="1".

Nút chia sẻ Telegram

Khi khách bấm nút chia sẻ, Telegram yêu cầu chọn chat, nhóm hoặc kênh và cho phép sửa phần text tùy chọn trước khi gửi. Trình tạo nút trên core.telegram.org/widgets/share cho ra:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="Xem bài này nhé!" data-size="large"></script>

Bỏ data-size để có nút cỡ vừa; data-text="notext" chỉ hiện biểu tượng. Muốn tự thiết kế, hãy link tới https://t.me/share/url?url={url}&text={text} với cả hai giá trị đã URL-encode:

<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=Xem%20b%C3%A0i%20n%C3%A0y%20nh%C3%A9%21">Chia sẻ lên Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
  + '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;

Xử lý lỗi thường gặp

Bước tiếp theo

Câu hỏi thường gặp

Làm sao thêm nút đăng nhập bằng Telegram vào website?

Chọn một bot, mở mini app của @BotFather, chọn bot rồi vào Login Widget, thêm origin của site và redirect URI vào Allowed URLs, sau đó sao chép Client ID. Tiếp theo, chèn đoạn script telegram-login.js có data-client-id vào trang và xác minh id_token trả về trên server.

Telegram Login Widget kiểu cũ còn dùng được không?

Tài liệu của nó đã được lưu trữ tại core.telegram.org/widgets/login-legacy. Hiện Telegram coi thư viện Telegram Login và luồng OpenID Connect là cách chính để đăng nhập bằng Telegram, nên dự án mới nên dùng cách này.

Kiểm tra dữ liệu từ Telegram Login Widget trên server thế nào?

Với widget cũ: lấy mọi trường nhận được trừ hash, sắp xếp theo bảng chữ cái thành các dòng key=value nối bằng \n. Tính HMAC-SHA-256 của chuỗi này với khóa SHA256(bot_token), so dạng hex với hash và kiểm tra auth_date. Với cách đăng nhập mới, xác minh JWT id_token bằng JWKS của Telegram.

Nhúng bài đăng Telegram vào website bằng cách nào?

Mở link t.me của bài (ví dụ t.me/durov/43) trên trình duyệt và bấm EMBED, hoặc dùng trình tạo mã trên core.telegram.org/widgets/post. Chỉ nhúng được bài từ kênh và nhóm công khai.

Tự làm nút chia sẻ lên Telegram như thế nào?

Dùng link https://t.me/share/url?url={url}&text={text}, trong đó cả hai giá trị đều được URL-encode, ví dụ bằng encodeURIComponent trong JavaScript. Phần text là tùy chọn và người dùng có thể sửa trước khi gửi.

Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên

Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.

API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript

Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.

Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ

Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.

Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n

Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.

Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic

Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.

TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn

Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.

Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python

Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.

Widget Telegram: HTML tương tác ngay trong tin nhắn của bot

Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.