Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật
Để test Telegram Mini App, hãy bắt đầu trên trình duyệt thường với Telegram.WebApp được mock, sau đó đưa bản build local ra HTTPS, đăng ký URL với @BotFather và mở nó trong Telegram kèm DevTools. Bước cuối diễn ra trên server: xác thực initData trước khi tin người dùng. Dưới đây là toàn bộ quy trình, từ localhost đến checklist trước khi lên production.
Bước 1: test giao diện trên trình duyệt thường
Bên ngoài Telegram, phía sau Telegram.WebApp không có client nào: không có dữ liệu khởi chạy, không có theme, không có nút native. Bạn vẫn dựng được phần lớn giao diện trên trình duyệt desktop nếu code chịu được tình huống đó:
const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);
if (insideTelegram) {
tg.ready(); // ẩn màn hình chờ càng sớm càng tốt
tg.expand();
} else {
console.info("Ngoài Telegram: dùng dữ liệu mock");
}
Dùng biến theme kèm giá trị dự phòng, ví dụ var(--tg-theme-bg-color, #fff), để trang vẫn dễ đọc ở cả hai môi trường.
Muốn xem từng lệnh API làm gì mà không phải viết code, hãy mở Mini App Tester. Trên trình duyệt thường, công cụ chạy ở chế độ mock và giả lập Telegram.WebApp: bấm MainButton và BackButton, mở popup, ghi vào CloudStorage, đổi theme và theo dõi hơn 45 sự kiện trong log. Tuy nhiên dữ liệu mock chỉ để thay thế: initData của nó không được Telegram ký nên sẽ (đúng như mong đợi) không qua được bước xác thực trên server.
Bước 2: chạy Telegram Mini App từ localhost qua HTTPS
Telegram chỉ mở Mini App từ URL HTTPS (trừ môi trường test), và điện thoại của bạn cũng không truy cập được http://localhost. Cách phổ biến để test Telegram Mini App trên localhost là dùng tunnel cấp cho dev server một địa chỉ HTTPS công khai:
# chạy dev server, ví dụ Vite ở cổng 5173
npm run dev
# ở terminal thứ hai, chọn một trong các tunnel
ngrok http 5173
cloudflared tunnel --url http://localhost:5173
Mỗi công cụ sẽ in ra một URL https:// công khai. Hai lỗi hay gặp:
- Vite từ chối host của tunnel. Các bản Vite gần đây chặn host lạ trên dev server; hãy thêm domain tunnel vào
server.allowedHoststrongvite.config.js. - Địa chỉ bị đổi. Nhiều tunnel cấp URL ngẫu nhiên mới mỗi lần khởi động lại. Khi đó hãy cập nhật trong @BotFather hoặc gọi lại
setChatMenuButtonnhư ở Bước 3.
Bước 3: đăng ký Mini App với @BotFather
Mini App luôn gắn với một bot. Nếu chưa có bot, hãy xem cách tạo bot Telegram. Sau đó chọn cách người dùng mở URL của bạn:
- Link trực tiếp: gửi
/newappcho @BotFather, chọn bot và làm theo hướng dẫn. App sẽ mở tạihttps://t.me/<bot_username>/<app_name>. - Nút menu: trong @BotFather dùng
/setmenubuttonhoặc Bot Settings → Menu Button, hoặc gọi methodsetChatMenuButton. - Nút bàn phím: nút
web_apptrong reply keyboard hoặc inline keyboard (chỉ trong chat riêng).
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button": {"type": "web_app", "text": "Mở app",
"web_app": {"url": "https://your-tunnel.example.com"}}}'
Không truyền chat_id thì lệnh này đặt nút menu mặc định cho mọi người dùng. Mỗi khi URL tunnel thay đổi, hãy gọi lại qua setChatMenuButton trong Bot API Tester thay vì gõ lại curl.
Bước 4: dùng môi trường test của Telegram
Telegram có một môi trường test riêng, nơi link Mini App được dùng HTTP thường không TLS — tiện khi test trong mạng nội bộ. Môi trường này cần tài khoản và bot riêng:
- iOS: chạm biểu tượng Settings 10 lần → Accounts → Login to another account → Test.
- Telegram Desktop: ☰ Settings → Shift+Alt+chuột phải vào "Add Account" → Test Server.
- macOS: bấm biểu tượng Settings 10 lần để mở Debug Menu, rồi ⌘+click "Add Account".
Tạo bot với @BotFather ngay trong tài khoản test và gửi request tới https://api.telegram.org/bot<token>/test/METHOD_NAME. Giới hạn flood ở đây không được nới mà còn có thể chặt hơn, nên đừng dùng để test tải. Cách thiết lập đầy đủ, kể cả nút TEST trong Bot API Tester, có trong bài cách dùng server test của Telegram.
Bước 5: debug Mini App bên trong Telegram
Nhiều lỗi không bao giờ xuất hiện trên Chrome mà chỉ lộ ra trong WebView thật. Tóm tắt hướng dẫn chính thức Debug Mode for Mini Apps:
| Nền tảng | Cách inspect |
|---|---|
| iOS | Chạm biểu tượng Settings 10 lần và bật Allow Web View Inspection; cắm USB rồi mở Develop → thiết bị của bạn trong Safari trên Mac. |
| Android | Bật USB debugging; trong Settings của Telegram cuộn xuống cuối, nhấn giữ số phiên bản hai lần, chọn Enable WebView Debug; mở chrome://inspect/#devices trong Chrome. |
| Telegram Desktop (Windows, Linux) | Cài bản beta; Settings → Advanced → Experimental settings → Enable webview inspection; chuột phải → Inspect. |
| Telegram cho macOS | Cài bản beta; bấm biểu tượng Settings 5 lần và bật Debug Mini Apps; chuột phải → Inspect Element. |
Để so sánh nhanh các client, đặt https://telegram-bot-api.info/telegram-mini-app-tester.html làm URL Mini App của một bot test. Bên trong Telegram, Mini App Tester dùng API thật và hiển thị version, platform, colorScheme, themeParams, safe area cùng mọi sự kiện mà client đó phát ra. Trong code của bạn, hãy kiểm tra tính năng mới bằng Telegram.WebApp.isVersionAtLeast("8.0") thay vì mặc định ai cũng dùng app mới nhất.
Bước 6: xác thực initData trên server
Telegram.WebApp.initDataUnsafe chỉ dùng để hiển thị. Hãy gửi chuỗi Telegram.WebApp.initData gốc lên backend và kiểm tra:
- Parse query string và bỏ trường
hash. - Sắp xếp các trường còn lại theo bảng chữ cái và nối thành các dòng
key=valuengăn cách bởi\n: đây làdata_check_string. - Tính
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. - Loại dữ liệu cũ bằng cách kiểm tra
auth_date.
import crypto from "node:crypto";
export function validateInitData(initData, botToken, maxAgeSec = 3600) {
const params = new URLSearchParams(initData);
const hash = params.get("hash") ?? "";
params.delete("hash");
const dataCheckString = [...params.keys()].sort()
.map((key) => `${key}=${params.get(key)}`)
.join("\n");
const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");
const valid = hash.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
const age = Date.now() / 1000 - Number(params.get("auth_date"));
if (!valid || !(age <= maxAgeSec)) return null;
return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}
Ở client, gửi nguyên chuỗi không chỉnh sửa, ví dụ fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), và xác thực bằng token của chính bot đã mở app. Bên thứ ba không được biết token thì có thể kiểm tra trường signature bằng public key Ed25519 của Telegram, như mô tả trong tài liệu chính thức.
Bot API 10.2: bảo vệ origin của Mini App
Bot API 10.2 cấm gọi method của Mini App từ origin khác domain gốc của Mini App, và cơ chế này được bật cho mọi Mini App từ ngày 20/7/2026. Khi test, vấn đề hay xuất hiện lúc app redirect từ URL tunnel đã đăng ký sang host khác, như domain staging hay trang đăng nhập: tại đó các lệnh Telegram.WebApp ngừng hoạt động. Hãy giữ phần code giao tiếp với Telegram trên domain đã đăng ký và đăng ký lại URL mỗi khi host tunnel đổi. Bạn có thể tắt bảo vệ trong phần Mini App của @BotFather, nhưng khi đó tự bạn phải đảm bảo Mini App không chứa link tới trang không tin cậy.
Checklist test Telegram Mini App
- Giao diện chạy được ở chế độ mock và ở cả theme sáng lẫn tối.
Telegram.WebApp.ready()được gọi ngay khi phần giao diện chính đã render.- URL trong @BotFather hoặc
setChatMenuButtonkhớp với tunnel hiện tại hoặc domain production. - Đã test trên iOS, Android và desktop với DevTools; tính năng mới được kiểm tra bằng
isVersionAtLeast(). - Layout fullscreen tôn trọng
safeAreaInsetvàcontentSafeAreaInset. - Backend xác thực
initData(hash vàauth_date) và không bao giờ tininitDataUnsafe. - Mọi lệnh
Telegram.WebAppchạy trên origin đã đăng ký. - Production chạy trên domain riêng với chứng chỉ hợp lệ, không phải tunnel tạm thời.
Code xác thực phụ thuộc vào token bot, nên hãy giữ bí mật token: xem cách lấy và bảo vệ token bot Telegram. Nếu cùng backend đó cũng nhận update của bot, hãy đọc tiếp cách cài webhook Telegram bot. Nếu bạn chỉ cần một khối tương tác nhỏ trong tin nhắn thay vì cả một web app, hãy xem widget Telegram, có từ Bot API 10.4.
Câu hỏi thường gặp
Làm sao test Telegram Mini App trên localhost?
Telegram chỉ mở Mini App từ URL HTTPS, nên hãy đưa dev server ra ngoài qua tunnel HTTPS (ví dụ ngrok hoặc Cloudflare Tunnel) rồi đăng ký URL đó trong @BotFather hoặc bằng setChatMenuButton. Trong môi trường test thì được phép dùng link HTTP thường.
Có test được Telegram Mini App mà không cần Telegram không?
Được một phần. Trình duyệt thường không có client Telegram, nên bạn cần mock Telegram.WebApp, chẳng hạn chế độ mock của Mini App Tester. initData thật, popup gốc và haptic chỉ hoạt động bên trong Telegram.
Mở DevTools cho Telegram Mini App như thế nào?
Trên iOS bật Allow Web View Inspection (chạm Settings 10 lần) và dùng menu Develop của Safari. Trên Android bật WebView Debug trong cài đặt debug của Telegram rồi mở chrome://inspect/#devices. Trên desktop và macOS dùng tùy chọn inspect webview của bản beta.
Vì sao xác thực initData bị sai?
Nguyên nhân hay gặp: kiểm tra initDataUnsafe thay vì chuỗi initData gốc, dùng token của bot khác, không URL-decode giá trị, để sót hash trong data-check string, đảo key và message của HMAC, hoặc test bằng dữ liệu mock mà Telegram chưa từng ký.
Vì sao các method Telegram.WebApp ngừng chạy trên domain khác?
Từ Bot API 10.2, method của Mini App bị chặn khi được gọi từ origin khác domain của Mini App; cơ chế bảo vệ này được bật cho mọi Mini App từ ngày 20/7/2026. Hãy giữ app trên domain đã đăng ký hoặc tắt bảo vệ trong @BotFather.
Telegram Mini App có server test riêng không?
Có. Môi trường test tách biệt hoàn toàn với production: bạn cần tài khoản mới và bot mới ở đó, request Bot API gửi tới https://api.telegram.org/bot<token>/test/METHOD_NAME, và link Mini App có thể dùng HTTP không TLS.
Bài viết liên quan
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.
Cách deploy bot Telegram: VPS, Docker và hosting serverless
Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.
Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế
Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.
Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục
Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.
Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn
Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.
Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start
Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.
Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard
Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.
Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn
Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.
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.
Bot inline Telegram: cách bật inline mode và trả lời inline query
Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.
Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao
Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.
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.
Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ
Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.
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.