Telegram Web API Cheatsheet

Hoja de referencia de la API web de Telegram

Para comenzar a usar la API, coloque esto en su HTML:

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

Cuando lo agregas a tu HTML, obtienes el objeto window.Telegram y también algunas variables de estilo CSS.

La mayor parte de su trabajo con la API de Telegram se realizará con window.Telegram.WebApp , que contiene muchos métodos y propiedades útiles.

CSS

Puede utilizar las variables CSS de la API para que su aplicación web coincida con el tema de Telegram que el usuario eligió; No necesitas hacer nada, ¡las variables CSS están listas para usar!

 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 )

También puedes acceder a ellos usando JavaScript:

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

Autenticación de usuario

Para asegurarse de que los usuarios que usan su aplicación sean los reales y también para asegurarse de que estén usando su aplicación desde la aplicación Telegram, debe autenticar a sus usuarios; Este es un paso importante, ¡así que no lo saltes!

Primero, necesita obtener Telegram.WebApp.initData del usuario, que es una cadena que contiene una consulta con estos parámetros:

• auth_date : Hora Unix en la que se abrió el formulario.
• hash : un hash de todos los parámetros pasados, que el servidor del bot puede usar para verificar su validez.
• query_id : Opcional. Un identificador único para la sesión de la aplicación web, necesario para enviar mensajes mediante el método answerWebAppQuery .
• user :
  • id
  • first_name
  • last_name
  • username
  • language_code , por ejemplo en

Ejemplo:

 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 >

En segundo lugar, debe pasar esa consulta al backend para validar los datos.

Así es como lo haces:

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

Usando JavaScript, puedes validar los datos de esta manera:

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

Ahora te aseguraste de que el usuario que usa tu aplicación sea el real y también use la aplicación Telegram; ¡ahora tu aplicación es segura!

Obtener datos de usuario

Después de autenticar al usuario desde el backend, podemos volver al frontend y obtener los datos del usuario:

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

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

// Now userData is ready to use! 

Botón Atrás

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

Botón 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 ( ) ; 

Confirmación de cierre

Cuando llame a este método, esperará hasta que el usuario intente cerrar la aplicación; luego pedirá confirmación

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

Abrir un enlace

en un navegador

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

Mostrar ventana emergente

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

Más sobre los tipos de botones aquí

Mostrar alerta

Si se pasó un parámetro de devolución de llamada opcional, se llamará a la función de devolución de llamada y la identificación del campo del botón presionado se pasará como primer argumento.

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

Mostrar Confirmar

Si se pasó un parámetro de devolución de llamada opcional, la función de devolución de llamada se llamará cuando se cierre la ventana emergente y el primer argumento será un booleano que indicará si el usuario presionó el botón "Aceptar".

Escaneando código QR

Si se pasó un parámetro de devolución de llamada opcional, se llamará a la función de devolución de llamada y el texto del código QR se pasará como primer argumento. Devolver verdadero dentro de esta función de devolución de llamada hace que se cierre la ventana emergente.

 const tg = window . Telegram . WebApp ;

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

tg . closeScanQrPopup ( ) ; 

¿Aplicación lista?

Un método que informa a la aplicación Telegram que la aplicación web está lista para mostrarse.

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

Expandir aplicación (pantalla completa)

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

Contribuyendo

¡Siéntete libre de contribuir a esta hoja de trucos!