Telegram Web API Cheatsheet

Aide-mémoire de l'API Web Telegram

Pour commencer à utiliser l'API, insérez ceci dans votre HTML :

 < script src =" https://telegram.org/js/telegram-web-app.js " > </ script >

Lorsque vous l'ajoutez à votre HTML, vous obtenez l'objet window.Telegram ainsi que quelques variables de style CSS.

La plupart de votre travail avec l'API Telegram se fera avec window.Telegram.WebApp , qui contient de nombreuses méthodes et propriétés utiles.

CSS

Vous pouvez utiliser les variables CSS de l'API pour que votre application Web corresponde au thème Telegram de l'utilisateur qu'il a choisi ; vous n'avez rien à faire, les variables CSS sont prêtes à l'emploi !

 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 )

Vous pouvez également y accéder en utilisant JavaScript :

 const {
  bg_color ,
  text_color ,
  hint_color ,
  button_color ,
  button_text_color ,
  secondary_bg_color ,
} = Telegram . WebApp . themeParams ; 

Authentification utilisateur

Pour vous assurer que les utilisateurs qui utilisent votre application sont les vrais et également pour vous assurer qu'ils utilisent votre application depuis l'application Telegram, vous devez authentifier vos utilisateurs ; c'est une étape importante, alors ne la sautez pas !

Tout d’abord, vous devez obtenir le Telegram.WebApp.initData de l’utilisateur, qui est une chaîne contenant une requête avec ces paramètres :

• auth_date : heure Unix à laquelle le formulaire a été ouvert.
• hash : Un hachage de tous les paramètres transmis, que le serveur du bot peut utiliser pour vérifier leur validité.
• query_id : facultatif. Un identifiant unique pour la session Web App, requis pour l'envoi de messages via la méthode answerWebAppQuery .
• user :
  • id
  • first_name
  • last_name
  • username
  • language_code , par exemple en

Exemple:

 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 >

Deuxièmement, vous devez transmettre cette requête au backend pour valider les données.

Voici comment procéder :

 data_check_string = ...
secret_key = HMAC_SHA256 ( < bot_token > , "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
  // Data is from Telegram
}

En utilisant JavaScript, vous pouvez valider les données comme ceci :

 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 ;
} ;

Vous vous êtes maintenant assuré que l'utilisateur qui utilise votre application est le vrai et qu'il utilise également l'application Telegram ; maintenant votre application est sécurisée !

Obtenir des données utilisateur

Après avoir authentifié l'utilisateur depuis le backend, nous pouvons revenir au frontend et récupérer les données de l'utilisateur :

 const params = new URLSearchParams ( Telegram . WebApp . initData ) ;

const userData = Object . fromEntries ( params ) ;
userData . user = JSON . parse ( userData . user ) ;

// Now userData is ready to use! 

Bouton Retour

 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 ( ) ; 

Bouton principal

 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 ( ) ; 

Confirmation de clôture

Lorsque vous appelez cette méthode, elle attendra que l'utilisateur tente de fermer l'application ; alors il demandera une confirmation

 const tg = Telegram . WebApp ;
tg . enableClosingConfirmation ( ) ;
tg . disableClosingConfirmation ( ) ; 

Ouvrir un lien

Dans un navigateur

 const tg = window . Telegram . WebApp ;
tg . openLink ( "https://youtube.com" ) ; 

Afficher la fenêtre contextuelle

 const tg = Telegram . WebApp ;
tg . showPopup (
  {
    title : "Sample Title" , // Optional
    message : "Sample message" ,
    buttons : [ { type : "destructive" , text : "oh hell nah" } ] , // Optional
  } ,
  callback
) ;

En savoir plus sur les types de boutons ici

Afficher l'alerte

Si un paramètre de rappel facultatif a été passé, la fonction de rappel sera appelée et l'identifiant du champ du bouton enfoncé sera transmis comme premier argument.

 const tg = window . Telegram . WebApp ;
tg . showAlert ( "sample alert" , callback ) ;

Afficher Confirmer

Si un paramètre de rappel facultatif a été passé, la fonction de rappel sera appelée à la fermeture de la fenêtre contextuelle et le premier argument sera un booléen indiquant si l'utilisateur a appuyé sur le bouton « OK ».

Scanner le code QR

Si un paramètre de rappel facultatif a été transmis, la fonction de rappel sera appelée et le texte du code QR sera transmis comme premier argument. Le retour de true dans cette fonction de rappel entraîne la fermeture de la fenêtre contextuelle.

 const tg = window . Telegram . WebApp ;

tg . showScanQrPopup ( { text : "capture" } , callback ) ;

tg . closeScanQrPopup ( ) ; 

Application prête ?

Une méthode qui informe l'application Telegram que la Web App est prête à être affichée.

 const tg = window . Telegram . WebApp ;
tg . ready ( ) ; 

Développer l'application (plein écran)

 const tg = window . Telegram . WebApp ;
tg . isExpanded ;
tg . expand ( ) ; 

Contribuer

N'hésitez pas à contribuer à cette aide-mémoire !