ganiry/Telegram-Web-API-Cheatsheet

📋 Telegram Web API Cheatsheet — tài liệu gọn cho Mini Apps

Một trang cheatsheet đơn giản, tập trung vào những API thực sự dùng hàng ngày khi xây dựng Telegram Mini Apps — không rườm rà, có code mẫu copy-paste chạy ngay.

Dự án của ganiry gom lại các đoạn code khởi tạo, theme CSS, xác thực người dùng (initData), thao tác Back Button/Main Button, xác nhận đóng, mở link và hiển thị popup — tất cả đều lấy từ tài liệu chính thức Telegram Bot API nhưng trình bày dạng "tra cứu nhanh". Phù hợp cho dev đang nhúng web app vào Telegram và cần nhớ cú pháp mà không muốn lướt qua trang docs dài dòng.

✨ Điểm nổi bật

• CSS Theme Variables: Danh sách biến --tg-theme-* (bg-color, text-color, hint-color, link-color, button-color, button-text-color, secondary-bg-color) và cách truy xuất qua Telegram.WebApp.themeParams để UI tự đồng bộ theme Telegram của người dùng.
• Xác thực initData (HMAC-SHA256): Hướng dẫn đầy đủ quy trình: lấy Telegram.WebApp.initData → tách hash → sort params → tạo data-check-string → ký HMAC với secret key HMAC_SHA256(bot_token, "WebAppData") → so khớp hash. Kèm hàm verifyTelegramWebAppData viết sẵn bằng Node.js crypto.
• Lấy dữ liệu user frontend: Parse initData qua URLSearchParams, JSON.parse(user) để có object userData sẵn dùng.
• Back Button: show(), hide(), onClick(), offClick(), isVisible — điều khiển nút quay lại góc trái.
• Main Button: Toàn bộ property (text, color, textColor, isVisible, isActive, isProgressVisible) và method (setText, show, hide, enable, disable, showProgress, hideProgress).
• Closing Confirmation: enableClosingConfirmation() / disableClosingConfirmation() — hỏi xác nhận trước khi user đóng Mini App.
• Open Link & Popup: openLink(url) mở trong browser, showPopup({title, message, buttons}) hiển thị dialog native.

💡 Vì sao đáng chú ý

Cheatsheet này cắt bỏ phần lý thuyết, chỉ giữ lại cú pháp và luồng thực tế — chính thứ dev cần khi ngồi code. Phần xác thực initData là điểm giá trị nhất: nhiều tutorial chỉ nói "validate hash" mà không cho code hoàn chỉnh, ở đây có hàm verifyTelegramWebAppData sẵn, giải thích rõ data-check-string, secret key, thứ tự sort params — copy vào backend là chạy. Các ví dụ Back/Main Button cũng viết theo pattern event listener (onClick/offClick) thay vì pseudo-code, dễ tích hợp vào React/Vue/Svelte.

---

#Telegram #MiniApps #WebApp #Cheatsheet #TiniX