Telegram Web API Cheatsheet
1.0.0
API 사용을 시작하려면 다음을 HTML에 입력하세요.
< script src =" https://telegram.org/js/telegram-web-app.js " > </ script > 이를 HTML에 추가하면 window.Telegram 객체와 일부 CSS 스타일 변수를 얻게 됩니다.
Telegram API를 사용하는 대부분의 작업은 유용한 메소드와 속성이 많이 포함된 window.Telegram.WebApp 을 사용하여 수행됩니다.
API의 CSS 변수를 사용하여 웹 앱이 사용자가 선택한 Telegram 테마와 일치하도록 할 수 있습니다. 아무것도 할 필요가 없습니다. CSS 변수를 사용할 준비가 되었습니다!
var ( --tg-theme-bg-color )
var ( --tg-theme-text-color )
var ( --tg-theme-hint-color )
var ( --tg-theme-link-color )
var ( --tg-theme-button-color )
var ( --tg-theme-button-text-color )
var ( --tg-theme-secondary-bg-color )JavaScript를 사용하여 액세스할 수도 있습니다.
const {
bg_color ,
text_color ,
hint_color ,
button_color ,
button_text_color ,
secondary_bg_color ,
} = Telegram . WebApp . themeParams ; 귀하의 앱을 사용하는 사용자가 실제 사용자인지 확인하고 그들이 Telegram 앱에서 귀하의 앱을 사용하고 있는지 확인하려면 사용자를 인증해야 합니다. 이것은 중요한 단계이므로 건너뛰지 마십시오!
먼저, 다음 매개변수가 포함된 쿼리가 포함된 문자열인 사용자의 Telegram.WebApp.initData 가져와야 합니다.
auth_date : 양식이 열린 Unix 시간입니다.hash : 봇 서버가 유효성을 확인하는 데 사용할 수 있는 모든 전달된 매개변수의 해시입니다.query_id : 선택사항입니다. answerWebAppQuery 메서드를 통해 메시지를 보내는 데 필요한 웹앱 세션의 고유 식별자입니다.user :idfirst_namelast_nameusernamelanguage_code 예: en예:
query_id = < query_id > &user=%7B%22id%22%3A < user_id > %2C%22first_name%22%3A%22 < first_name > %22%2C%22last_name%22%3A%22 < last_name > %22%2C%22username%22%3A%22 < username > %22%2C%22language_code%22%3A%22 < language_code > %22%7D&auth_date= < auth_date > &hash= < hash >둘째, 데이터의 유효성을 검사하려면 해당 쿼리를 백엔드에 전달해야 합니다.
수행 방법은 다음과 같습니다.
data_check_string = ...
secret_key = HMAC_SHA256 ( < bot_token > , "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// Data is from Telegram
}JavaScript를 사용하면 다음과 같이 데이터의 유효성을 검사할 수 있습니다.
const verifyTelegramWebAppData = ( telegramInitData : string ) => {
// The data is a query string, which is composed of a series of field-value pairs.
const encoded = decodeURIComponent ( telegramInitData ) ;
// HMAC-SHA-256 signature of the bot's token with the constant string WebAppData used as a key.
const secret = crypto . createHmac ( "sha256" , "WebAppData" ) . update ( botToken ) ;
// Data-check-string is a chain of all received fields'.
const arr = encoded . split ( "&" ) ;
const hashIndex = arr . findIndex ( ( str ) => str . startsWith ( "hash=" ) ) ;
const hash = arr . splice ( hashIndex ) [ 0 ] . split ( "=" ) [ 1 ] ;
// Sorted alphabetically
arr . sort ( ( a , b ) => a . localeCompare ( b ) ) ;
// In the format key=<value> with a line feed character ('n', 0x0A) used as separator
// e.g., 'auth_date=<auth_date>nquery_id=<query_id>nuser=<user>
const dataCheckString = arr . join ( "n" ) ;
// The hexadecimal representation of the HMAC-SHA-256 signature of the data-check-string with the secret key
const _hash = crypto
. createHmac ( "sha256" , secret . digest ( ) )
. update ( dataCheckString )
. digest ( "hex" ) ;
// If hash is equal, the data may be used on your server.
// Complex data types are represented as JSON-serialized objects.
return _hash === hash ;
} ;이제 귀하의 앱을 사용하는 사용자가 실제 사용자이고 Telegram 앱도 사용하는지 확인했습니다. 이제 귀하의 앱은 안전합니다!
백엔드에서 사용자를 인증한 후 프런트엔드로 돌아가 사용자 데이터를 가져올 수 있습니다.
const params = new URLSearchParams ( Telegram . WebApp . initData ) ;
const userData = Object . fromEntries ( params ) ;
userData . user = JSON . parse ( userData . user ) ;
// Now userData is ready to use! 
const tg = Telegram . WebApp ;
// Show the back button
tg . BackButton . show ( ) ;
// Check if the button is visible
tg . BackButton . isVisible ;
// Click Event
const goBack = ( ) => {
// Callback code
} ;
tg . BackButton . onClick ( goBack ) ;
// Remove Click Event
tg . BackButton . offClick ( goBack ) ;
// Hide the back button
tg . BackButton . hide ( ) ; 
const tg = Telegram . WebApp . MainButton ;
// Properties
tg . text ; // You can change the value
tg . color ; // You can change the value
tg . textColor ; // You can change the value
tg . isVisible ;
tg . isActive ;
tg . isProgressVisible ;
// Events
tg . onClick ( callback ) ;
tg . offClick ( callback ) ;
// Methods
tg . setText ( "buy" ) ;
tg . show ( ) ;
tg . hide ( ) ;
tg . enable ( ) ; // Default
tg . disable ( ) ; // If the button is disabled, then it will not work when clicked
tg . showProgress ( true ) ; // Shows a spinning icon; if you passed into it `false`, then it will disable the button when loading
tg . hideProgress ( ) ; 
이 메서드를 호출하면 사용자가 앱을 닫으려고 할 때까지 기다립니다. 그러면 확인을 요청할 것입니다
const tg = Telegram . WebApp ;
tg . enableClosingConfirmation ( ) ;
tg . disableClosingConfirmation ( ) ; 브라우저에서
const tg = window . Telegram . WebApp ;
tg . openLink ( "https://youtube.com" ) ; 
const tg = Telegram . WebApp ;
tg . showPopup (
{
title : "Sample Title" , // Optional
message : "Sample message" ,
buttons : [ { type : "destructive" , text : "oh hell nah" } ] , // Optional
} ,
callback
) ;버튼 유형에 대한 자세한 내용은 여기를 참조하세요.
선택적 콜백 매개변수가 전달된 경우 콜백 함수가 호출되고 누른 버튼의 필드 ID가 첫 번째 인수로 전달됩니다.
const tg = window . Telegram . WebApp ;
tg . showAlert ( "sample alert" , callback ) ;
선택적 콜백 매개변수가 전달된 경우 팝업이 닫힐 때 콜백 함수가 호출되며 첫 번째 인수는 사용자가 '확인' 버튼을 눌렀는지 여부를 나타내는 부울입니다.
선택적 콜백 매개변수가 전달된 경우 콜백 함수가 호출되고 QR 코드의 텍스트가 첫 번째 인수로 전달됩니다. 이 콜백 함수 내에서 true를 반환하면 팝업이 닫힙니다.
const tg = window . Telegram . WebApp ;
tg . showScanQrPopup ( { text : "capture" } , callback ) ;
tg . closeScanQrPopup ( ) ; 웹 앱을 표시할 준비가 되었음을 텔레그램 앱에 알리는 메서드입니다.
const tg = window . Telegram . WebApp ;
tg . ready ( ) ; const tg = window . Telegram . WebApp ;
tg . isExpanded ;
tg . expand ( ) ; 이 치트시트에 자유롭게 기여해 주세요!
