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
- Lấy chuỗi initData gốc trong Mini App, ví dụ bằng cách log
Telegram.WebApp.initData(không phảiinitDataUnsafe). Một URL fragment bắt đầu bằngtgWebAppData=cũng dùng được: tiền tố sẽ được loại bỏ. - Dán token của bot mở Mini App.
- Bấm Xác thực. Bạn nhận được kết luận hợp lệ/không hợp lệ,
auth_datecù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ớiuservà 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:
- Phân tích initData như một query string và tách riêng
hash. - Tạo
data_check_string: mọi trường còn lại dạngkey=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. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).- Dữ liệu hợp lệ nếu
hex(HMAC_SHA256(key=secret_key, message=data_check_string))bằnghash.
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
- Token thuộc một bot khác với bot đã mở Mini App.
- initData đã bị decode hoặc sửa đổi trước khi xác thực — luôn truyền chuỗi gốc.
- Chuỗi được dựng lại từ
initDataUnsafe: thứ tự trường và cách encode khác nhau, nên hash sẽ 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