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

Si vous avez déjà essayé de créer une Telegram Web App (TWA) sans couche d'abstraction, vous connaissez la galère. Parler directement à window.Telegram.WebApp fonctionne — mais c'est verbeux, incohérent selon les plateformes, et sans aucune sécurité de types. C'est exactement ce que @twa-dev/sdk règle.

Cet article couvre ce que le SDK fait vraiment, comment l'installer, ses fonctionnalités clés, et les problèmes que les gens rencontrent. Rien de superflu — juste ce dont vous avez besoin pour livrer quelque chose.

Qu'est-ce que @twa-dev/sdk ?

@twa-dev/sdk est un package TypeScript/JavaScript open source qui enveloppe l'API JavaScript de Telegram Web App. Il est maintenu par la communauté et disponible sur GitHub.

L'API brute de Telegram Web App est exposée sous forme d'objet global injecté dans votre webview par Telegram. Ça fonctionne, mais elle a été conçue pour les environnements navigateur — pas pour les frontends TypeScript modernes. @twa-dev/sdk vous offre :

• Des typages TypeScript complets (fini de deviner quels champs existent)

• Des wrappers réactifs autour des événements Telegram

• Un comportement cohérent sur iOS, Android et Telegram Desktop

• Une expérience développeur plus propre avec des imports de modules appropriés

En résumé : vous écrivez moins de boilerplate et détectez plus de bugs à la compilation plutôt qu'à 2h du matin quand un utilisateur signale un crash.

Installer et configurer @twa-dev/sdk

Démarrer est simple. Installez le package via npm ou yarn :

npm install @twa-dev/sdk
# ou
yarn add @twa-dev/sdk

npm install @twa-dev/sdk
# ou
yarn add @twa-dev/sdk

npm install @twa-dev/sdk
# ou
yarn add @twa-dev/sdk

Ensuite, importez-le dans votre application. Le SDK exporte un objet WebApp par défaut qui reproduit l'API Telegram Web App — mais avec des types et quelques améliorations de confort :

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Indique à Telegram que l'app est chargée
console.log(WebApp.initDataUnsafe.user); // Objet utilisateur typé

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Indique à Telegram que l'app est chargée
console.log(WebApp.initDataUnsafe.user); // Objet utilisateur typé

import WebApp from '@twa-dev/sdk';

WebApp.ready(); // Indique à Telegram que l'app est chargée
console.log(WebApp.initDataUnsafe.user); // Objet utilisateur typé

C'est tout pour les bases. Pas de fichiers de configuration, pas de cérémonie d'installation. Si vous utilisez React, Vue ou Svelte — ça s'intègre directement.

Un point important à surveiller

Le SDK est conçu pour fonctionner dans l'environnement WebView de Telegram. Si vous essayez d'exécuter votre application dans un navigateur classique (par exemple, lors du développement local), window.Telegram.WebApp n'existera pas et vous obtiendrez des erreurs. La solution habituelle est de mocker l'objet en local ou d'utiliser un environnement de test pour Telegram Mini App.

Utilisez WebApp.isExpanded, WebApp.platform et des vérifications d'environnement pour protéger la logique spécifique à chaque plateforme pendant le développement.

Les fonctionnalités clés que vous utiliserez vraiment

Bouton principal et bouton retour

Les Telegram Web Apps disposent d'éléments d'interface natifs — le Main Button (le grand bouton en bas) et le Back Button (dans l'en-tête). Les gérer avec les appels API bruts est maladroit. Avec @twa-dev/sdk :

WebApp.MainButton.setText('Confirmer la commande');
WebApp.MainButton.show();
WebApp.MainButton.onClick(() => handleConfirm());

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

WebApp.MainButton.setText('Confirmer la commande');
WebApp.MainButton.show();
WebApp.MainButton.onClick(() => handleConfirm());

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

WebApp.MainButton.setText('Confirmer la commande');
WebApp.MainButton.show();
WebApp.MainButton.onClick(() => handleConfirm());

WebApp.BackButton.show();
WebApp.BackButton.onClick(() => router.back());

Propre, typé et prévisible. Vous les utiliserez constamment dans toute Mini App un tant soit peu sérieuse.

Init Data et authentification des utilisateurs

Quand un utilisateur ouvre votre TWA, Telegram injecte initData — une chaîne contenant les infos utilisateur, le contexte du chat, et un hash que vous pouvez vérifier côté serveur. Le SDK le parse pour vous :

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Alex', username: 'alex_dev', ... }

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Alex', username: 'alex_dev', ... }

const user = WebApp.initDataUnsafe.user;
// { id: 123456789, first_name: 'Alex', username: 'alex_dev', ... }

Validez toujours initData sur votre serveur — ne faites jamais confiance au client seul. Le hash est signé avec le token de votre Bot, vous pouvez donc le vérifier avec HMAC-SHA256. C'est ainsi que vous authentifiez les utilisateurs sans mots de passe ni flux OAuth.

Retour haptique

Un petit détail, une grande différence en termes d'UX. Le SDK expose WebApp.HapticFeedback avec trois méthodes :

• impactOccurred('light' | 'medium' | 'heavy' | 'rigid' | 'soft')

• notificationOccurred('error' | 'success' | 'warning')

• selectionChanged()

Utilisez les haptiques quand les utilisateurs confirment des actions, rencontrent des erreurs ou font défiler des listes. Ça donne à votre application un aspect natif — pas celui d'un site web encapsulé.

Variables de thème et de couleur

Telegram injecte des variables CSS pour le thème actuel de l'utilisateur (clair/sombre, couleurs personnalisées). Le SDK vous donne un accès facile via WebApp.themeParams, afin que vous puissiez créer une interface qui s'intègre naturellement, quel que soit le thème Telegram de l'utilisateur.

@twa-dev/sdk vs API Telegram Web App brute : quelle est la vraie différence ?

Honnêtement ? Pour les petits projets, vous pouvez vous en sortir avec l'API brute. L'objet global Telegram.WebApp est bien documenté et ne nécessite aucune dépendance.

Mais dès que votre projet dépasse un seul fichier, l'API brute devient un risque :

• Sans types TypeScript, ce sont des casts any constants et des surprises à l'exécution

• La gestion des événements est manuelle et facile à faire fuir (oublier de supprimer des listeners)

• Les particularités multi-plateformes (iOS vs Android vs Desktop) se manifestent comme des bugs en production, pas comme des erreurs de compilation

@twa-dev/sdk est le bon choix par défaut pour tout projet sérieux. Le coût en dépendances est minimal. L'amélioration de l'expérience développeur est bien réelle.

Les pièges courants lors de la création de Telegram Web Apps

Même avec un bon SDK, les gens tombent dans les mêmes problèmes. Voici ce qu'il faut surveiller :

• Appeler WebApp.ready() trop tard. Appelez-le le plus tôt possible — ça indique à Telegram que votre application est chargée et arrête le spinner de chargement. Retardez-le et les utilisateurs voient un écran blanc plus longtemps que nécessaire.

• Ne pas gérer les changements de viewport. Le clavier apparaît, le viewport rétrécit. Si vous n'écoutez pas WebApp.onEvent('viewportChanged', ...), votre mise en page se cassera sur mobile.

• Supposer que initDataUnsafe est sûr. Le nom parle de lui-même. Vérifiez toujours la chaîne initData côté serveur avant de faire confiance aux informations utilisateur.

• Coder les couleurs en dur au lieu d'utiliser les variables de thème. Votre application aura l'air cassée en mode sombre ou pour les utilisateurs avec des thèmes Telegram personnalisés.

• Ignorer WebApp.expand(). Par défaut, la Mini App s'ouvre en vue partielle. Appelez WebApp.expand() si vous voulez le plein écran — la plupart des applications en bénéficient.

À lire également : les bonnes pratiques de sécurité pour les Telegram Mini Apps — surtout si votre application gère des données utilisateur ou des paiements.

Quand les Telegram Web Apps ont du sens pour les workflows de vente et de CRM

C'est là que ça devient intéressant d'un point de vue business. Les Telegram Web Apps ne sont pas réservées aux jeux et aux utilitaires. Elles sont de plus en plus utilisées pour intégrer des interfaces CRM, des formulaires de capture de leads, des flux d'Onboarding et des Tableaux de bord directement dans les chats Telegram.

Pensez à la friction que représente le fait de demander à un prospect commercial d'ouvrir un onglet de navigateur séparé, de s'inscrire et de remplir un formulaire. Comparez maintenant avec un bouton dans un message Telegram qui ouvre une Mini App directement — pré-remplie avec son identité Telegram, sans connexion requise.

C'est un Tunnel de conversion fondamentalement différent. Si vous créez des workflows personnalisés basés sur Telegram par-dessus un CRM existant, l'API CRMChat vaut le coup d'œil — elle est conçue spécifiquement pour créer des intégrations entre Telegram et les Pipelines de vente, ce qui se marie naturellement avec les frontends de Mini App.

Pour en savoir plus sur l'ensemble de l'API Telegram Mini App, cet aperçu de l'API Telegram Mini App couvre ce qui est disponible au-delà du seul SDK.

En résumé

Utilisez @twa-dev/sdk si vous construisez quelque chose qui dépasse le prototype du week-end. Il vous offre des types, une gestion d'événements plus propre et une cohérence multi-plateforme — le tout pour un coût réel nul.

Votre checklist de départ :

1. Installez @twa-dev/sdk et remplacez les appels bruts à window.Telegram.WebApp

2. Appelez WebApp.ready() le plus tôt possible

3. Appelez WebApp.expand() si vous voulez le plein écran

4. Validez initData côté serveur — toujours

5. Utilisez les variables de thème pour que votre interface ne soit pas cassée en mode sombre

6. Testez sur de vrais appareils (iOS et Android), pas seulement dans le navigateur

C'est la base. Construisez à partir de là.