Telegram Bot API

Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật

· 7 phút đọc

Để 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:

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:

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:

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ảngCách inspect
iOSChạ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.
AndroidBậ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 macOSCà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:

  1. Parse query string và bỏ trường hash.
  2. 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=value ngăn cách bởi \n: đây là data_check_string.
  3. Tính 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.
  5. 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

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.

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.