@twa-dev/sdk : Comment créer des Telegram Web Apps qui fonctionnent vraiment

Si vous créez une Telegram Mini App et que vous lisez la documentation officielle, vous remarquerez qu'elle fait référence à un objet brut window.Telegram.WebApp. Ça fonctionne — mais c'est verbeux, non typé, et pénible à utiliser avec les frameworks modernes. C'est là qu'intervient @twa-dev/sdk.

Le package @twa-dev/sdk est un wrapper TypeScript non officiel mais largement adopté autour de l'API Telegram Web App. Il vous offre une sécurité de type complète, une syntaxe plus claire et une expérience développeur bien meilleure — sans aucune surcharge réelle. Si vous construisez quelque chose de sérieux sur les Telegram Mini Apps, c'est le SDK qu'il vous faut.

Ce que fait vraiment @twa-dev/sdk

L'API officielle Telegram Web App est exposée via un objet JavaScript global injecté par le client Telegram. Elle fonctionne bien pour des scripts simples, mais dès que vous travaillez dans un projet React, Vue ou Svelte, manipuler des globales brutes devient vite compliqué.

@twa-dev/sdk encapsule cette globale dans un module typé et importable. Voici ce que vous obtenez d'emblée :

• Types TypeScript complets — autocomplétion pour chaque méthode, événement et propriété

• Imports plus propres — utilisez import WebApp from '@twa-dev/sdk' plutôt que d'aller chercher window.Telegram.WebApp

• Compatible avec les frameworks réactifs — fonctionne très bien avec React, Vue et autres frameworks basés sur des composants

• Toujours à jour — le package suit l'API Telegram officielle, vous n'avez donc pas à maintenir vos propres déclarations de types

C'est une couche légère. Elle n'ajoute pas de magie ni n'abstrait l'API principale. Pensez-y comme à une interface fortement typée, pas comme à un framework.

Comment l'installer et le configurer

L'installation prend environ 30 secondes :

npm install @twa-dev/sdk

npm install @twa-dev/sdk

npm install @twa-dev/sdk

Ensuite, importez-le là où vous en avez besoin :

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

import WebApp from '@twa-dev/sdk'

C'est tout. À partir de là, vous avez accès à toute la surface de l'API Telegram Web App — données utilisateur, thématisation, boutons, popups, retour haptique, et bien plus encore.

Un exemple minimal fonctionnel

Voici un composant React de base qui récupère les informations de l'utilisateur actuel et signale que l'application est prête :

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Bonjour, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Bonjour, {WebApp.initDataUnsafe.user?.first_name}</div>
}

import WebApp from '@twa-dev/sdk'
import { useEffect } from 'react'

export default function App() {
  useEffect(() => {
    WebApp.ready()
    console.log(WebApp.initDataUnsafe.user)
  }, [])

  return <div>Bonjour, {WebApp.initDataUnsafe.user?.first_name}</div>
}

WebApp.ready() indique à Telegram que l'application a chargé et que l'indicateur de chargement peut être masqué. Appelez-le toujours en début d'exécution. L'oublier laisse les utilisateurs face à un spinner indéfini.

Les fonctionnalités que vous utiliserez le plus

L'API Telegram Web App est vaste. Voici les parties que vous utiliserez dans presque tous vos projets :

MainButton

Le MainButton est le bouton CTA bien visible qui apparaît en bas de la Mini App. Vous le contrôlez entièrement :

WebApp.MainButton.setText('Valider la commande')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Valider la commande')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

WebApp.MainButton.setText('Valider la commande')
WebApp.MainButton.show()
WebApp.MainButton.onClick(() => handleSubmit())

C'est l'un des éléments d'interface les plus visibles d'une Mini App. Utilisez-le pour les actions principales — paiement, confirmation, envoi — et masquez-le quand il n'est pas pertinent pour l'écran en cours.

initDataUnsafe

Ceci vous donne les données de l'utilisateur Telegram actuel : ID, nom, nom d'utilisateur, code de langue, et s'il est abonné Premium. C'est « unsafe » (non sécurisé) car il s'agit de données côté client — validez-les toujours sur votre serveur en utilisant initData et le token du bot avant de leur faire confiance pour quoi que ce soit de sensible.

HapticFeedback

Un petit détail, un grand impact. Le retour haptique donne à votre application un aspect natif sur mobile :

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

WebApp.HapticFeedback.impactOccurred('medium')
WebApp.HapticFeedback.notificationOccurred('success')

Thème et palette de couleurs

Telegram transmet le thème actuel de l'utilisateur (clair/sombre) ainsi que des variables de couleur. Utilisez WebApp.colorScheme et les variables CSS injectées par Telegram (--tg-theme-bg-color, etc.) pour correspondre à l'apparence native sans aucune configuration supplémentaire.

sendData et close

WebApp.sendData() envoie une charge utile sous forme de chaîne de caractères à votre bot. Utilisez-le pour des soumissions de formulaires simples où le bot doit réagir aux entrées de l'utilisateur. WebApp.close() ferme la Mini App — appelez-le quand un flux est terminé.

@twa-dev/sdk vs window.Telegram.WebApp brut — lequel choisir ?

Honnêtement ? Utilisez @twa-dev/sdk pour tout projet impliquant plus d'un développeur ou une complexité supérieure à un week-end de travail.

• Si vous prototypez un petit script — l'API brute convient

• Si vous développez en React, Vue ou dans n'importe quel projet TypeScript — utilisez le SDK

• Si vous voulez détecter les bugs à la compilation plutôt qu'à l'exécution — utilisez le SDK

L'API brute ne disparaîtra pas. Mais le SDK vous évite d'écrire vos propres déclarations de types, les fautes de frappe dans les noms de méthodes, et ce genre de bugs qui n'apparaissent que sur l'appareil d'un utilisateur à 2h du matin.

Pour un regard plus approfondi sur le fonctionnement de l'API sous-jacente et ce que vous pouvez construire avec elle, consultez notre article sur l'API Telegram Mini App.

Sécurité : ne faites pas confiance à initDataUnsafe côté serveur

C'est l'erreur que font la plupart des gens au début. initDataUnsafe est une donnée fournie par le client. N'importe qui peut la falsifier. Si vous l'utilisez pour identifier des utilisateurs sur votre backend, vous construisez sur des fondations fragiles.

La bonne approche :

1. Envoyez la chaîne brute WebApp.initData à votre serveur (pas initDataUnsafe)

2. Sur le serveur, vérifiez la signature HMAC en utilisant votre token de bot

3. Ne faites confiance aux données utilisateur qu'après que cette vérification soit passée

Telegram documente l'algorithme de vérification dans sa documentation officielle. Ce n'est pas complexe — quelques lignes dans n'importe quel langage backend. Ne sautez pas cette étape. Pour un aperçu plus large des considérations de sécurité pour les Mini Apps, consultez notre article sur la sécurité des Telegram Mini Apps.

Créer des applications Telegram en production

Une fois votre Mini App solide, le prochain défi est de la connecter à de vrais workflows de vente et métier. C'est là que se creuse l'écart entre la « démo sympa » et l'« outil vraiment utile ».

Si vous construisez un workflow de vente ou un CRM basé sur Telegram — pas seulement une Mini App ponctuelle — l'API CRMChat mérite le détour. Elle vous permet de connecter des flux d'intégration Telegram personnalisés : pousser des leads depuis votre Mini App vers un Pipeline CRM, déclencher des Séquences de prospection, ou synchroniser des données de conversation sans avoir à construire toute l'infrastructure from scratch.

Pour un contexte plus large sur la façon dont Telegram s'intègre dans un workflow de vente moderne, cet article sur l'intégration CRM Telegram couvre bien le côté pratique.

En résumé

@twa-dev/sdk est le choix par défaut pour quiconque construit des Telegram Mini Apps dans une stack JS/TS moderne. Installez-le, importez-le, appelez WebApp.ready() en début d'exécution, validez initData sur votre serveur, et utilisez MainButton pour vos principaux CTA.

La surface de l'API est large mais bien documentée. Vous n'avez pas besoin de tout apprendre d'emblée. Commencez par initDataUnsafe, MainButton et sendData — cela couvre 80 % de ce que font réellement la plupart des Mini Apps.