Telegram Bot API

Công cụ xác thực initData của Telegram Mini App

Dán Telegram.WebApp.initData và token của bot để kiểm tra hash của Mini App có hợp lệ hay không — đúng phép kiểm tra HMAC-SHA256 mà server của bạn phải chạy, nhưng thực hiện cục bộ trong trình duyệt.

Token chỉ lưu trong trình duyệt của bạn (localStorage) và chỉ được gửi tới api.telegram.org.

Thuật toán: secret_key = HMAC_SHA256("WebAppData", bot_token); hash = hex(HMAC_SHA256(secret_key, data_check_string)), trong đó data_check_string là mọi trường trừ hash, sắp xếp theo key và nối dạng key=value bằng \n.

Cách kiểm tra hash của Telegram Mini App

  1. Lấy chuỗi initData gốc trong Mini App, ví dụ bằng cách log Telegram.WebApp.initData (không phải initDataUnsafe). Một URL fragment bắt đầu bằng tgWebAppData= cũng dùng được: tiền tố sẽ được loại bỏ.
  2. Dán token của bot mở Mini App.
  3. Bấm Xác thực. Bạn nhận được kết luận hợp lệ/không hợp lệ, auth_date cùng tuổi của nó (cảnh báo nếu cũ hơn 24 giờ) và mọi trường đã phân tích, với user và các giá trị JSON khác được giải mã.

Cách xác thực hoạt động

Công cụ làm theo thuật toán chính thức trong Validating data received via the Mini App:

  1. Phân tích initData như một query string và tách riêng hash.
  2. Tạo data_check_string: mọi trường còn lại dạng key=value (giá trị đã URL-decode), sắp xếp theo thứ tự bảng chữ cái, nối bằng ký tự xuống dòng \n.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. Dữ liệu hợp lệ nếu hex(HMAC_SHA256(key=secret_key, message=data_check_string)) bằng hash.

Phép kiểm tra tương tự trên server Node.js:

const crypto = require('crypto');

function checkInitData(initData, botToken) {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');
  const dataCheckString = [...params]
    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');
  const secret = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
  const calc = crypto.createHmac('sha256', secret).update(dataCheckString).digest('hex');
  return calc === hash;
}

Hãy kiểm tra cả auth_date trên server để initData cũ bị đánh cắp không thể bị dùng lại.

Vì sao hash không khớp

Quyền riêng tư

Không có request nào rời khỏi trình duyệt: HMAC được tính bằng Web Crypto API, và token chỉ được giữ trong localStorage — không có gì đến server của chúng tôi. Để xem initData thật từ một lần mở thực tế, hãy mở /vi/telegram-mini-app-tester.html bên trong Telegram. Quy trình test đầy đủ có trong /vi/guides/test-telegram-mini-app.html; nếu cần token mới, xem /vi/guides/telegram-bot-token.html.

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

Làm sao xác thực init data của Telegram Web App?

Tính secret_key = HMAC_SHA256("WebAppData", bot_token), tạo data-check-string từ mọi trường trừ hash, sắp xếp theo key và nối bằng \n, rồi so sánh hex(HMAC_SHA256(secret_key, data_check_string)) với hash. Công cụ ở trên làm đúng như vậy.

Vì sao hash initData của tôi không hợp lệ?

Thường là token thuộc bot khác, hoặc initData đã bị thay đổi: bị decode, encode lại, cắt bớt hoặc dựng lại từ initDataUnsafe. Hãy dán nguyên chuỗi Telegram.WebApp.initData gốc.

Có thể tin initDataUnsafe không?

Không, ở phía server. initDataUnsafe chỉ là dữ liệu đã phân tích ở client; hãy gửi initData gốc lên backend và xác thực hash ở đó trước khi tin user ID.

initData được phép cũ đến mức nào?

Telegram khuyên kiểm tra auth_date để từ chối dữ liệu lỗi thời, nhưng giới hạn do bạn quyết định. Công cụ hiển thị tuổi của dữ liệu và cảnh báo khi nó cũ hơn 24 giờ.

Token của bot có bị gửi đi đâu không?

Không. Công cụ xác thực không gửi request mạng nào: hash được tính bằng Web Crypto API trong trình duyệt. Token chỉ được ghi nhớ trong localStorage.

Tiện ích khác

Công cụ tìm chat IDCông cụ escape MarkdownV2 & HTMLCông cụ kiểm tra webhookBot API Tester