Telegram Craft

Que fait Telegram Craft ?

Le travail avec Telegram rate généralement de trois façons : des appels API écrits de mémoire, un chat traité comme une page web, et des données client considérées comme fiables parce qu'elles ont l'air officielles. Cette compétence contrecarre ces trois écueils.

Les faits ci-dessous ont été vérifiés contre la Bot API 10.4 (publiée le 2026-11-09) le 2026-11-10. Les versions sortent environ mensuellement et les noms récemment ajoutés ont déjà été remplacés ; confirmez donc tout ce qui est sensible à la version avec scripts/tgdocs.py.

1. Dimensionner la tâche

Adaptez le processus à la demande. Construisez ce qui a été demandé et listez les extensions recommandées dans le transfert plutôt que de les ajouter.

Tâche	Approche	Commencer par
Question ou correction ponctuelle	Réponse ou correctif. Vérifiez le contrat concerné.	platform-facts.md ou la référence du domaine
Refonte d'une copie, d'un clavier ou de /start	Modifiez uniquement la présentation. Conservez callback_data, les routes, les faits et les clés de locale. Ajoutez ou exécutez le contrôle qualité (quality-gate.md).	messages.md, rich-messages.md, keyboards.md
Bug ou fonctionnalité dans un projet existant	Lisez le code, reproduisez, faites la plus petite modification dans la pile existante, ajoutez un test de régression. Si la modification peut altérer ce que le bot envoie, le contrôle qualité doit être exécuté avant de terminer (section 6).	existing-projects.md, quality-gate.md
Refactorisation	Figez le comportement avec des tests d'abord, puis déplacez le code. Aucun changement de comportement.	existing-projects.md, backend.md
Nouveau bot ou Mini App	Générez la structure de projet standard, écrivez un plan d'écran, construisez une tranche verticale fonctionnelle, puis élargissez-la. Chaque écran est un message riche.	backend.md, product-journeys.md, rich-messages.md, rich-recipes.md
Revue ou audit	Exécutez tg_audit.py, confirmez chaque piste en lisant le code, rapportez par sévérité.	quality.md, security.md

Ne posez une question que lorsque la réponse change ce que vous construisez et que le code ne peut pas vous le dire. Un token de bot manquant bloque les tests en direct, pas l'implémentation.

Conservez la pile du projet. Pour les nouveaux projets sans contrainte, choisissez par défaut aiogram 3 pour Python ou grammY pour TypeScript, et @tma.js/sdk ou le script telegram-web-app.js pour les Mini Apps. Dimensionnez l'infrastructure en fonction du bot (un petit bot n'a pas besoin de file d'attente ni de Redis), mais pas l'organisation du code : chaque nouveau bot reçoit la disposition standard de backend.md, avec les handlers, claviers, textes, services et stockage dans des modules séparés. Ne livrez jamais un dossier plat de fichiers mélangés.

2. Choisir la surface

La tâche nécessite	Utilisez	Rappelez-vous
Commandes, flux courts, notifications, fichiers	Chat du bot	Choix par défaut
Choisir parmi quelques options	Clavier inline	Modifiez le message sur place
Longues listes, filtres, formulaires multi-champs, graphiques, cartes	Mini App	Un assistant de plus d'environ cinq étapes est un signe
Envoyer le contenu du bot dans d'autres chats	Mode inline	Les résultats sont mis en cache entre utilisateurs sauf si is_personal
Tout écran du bot : menus, tableaux de bord, listes, détails, paramètres, aide, reçus, rapports	Message riche (par défaut)	sendRichMessage, édition avec rich_message ; conception dans rich-messages.md, appels de bibliothèque dans formatting.md
Invite privée dans un groupe, ou réponse privée à une pression de bouton	Message éphémère	La livraison n'est pas garantie
Une carte interactive dans le chat	Widget HTML (sendWidget, 10.4)	Chats privés uniquement pour l'instant ; pas encore de support SDK
Agir en tant qu'utilisateur, lire l'historique non rejoint	Session utilisateur MTProto (Telethon, TDLib)	Uniquement avec autorisation explicite pour ce compte. Un modèle de confiance et de risque de bannissement différent.
Fichiers du bot dépassant les limites de la Bot API, méthodes de couche brute	Session bot MTProto, ou un serveur Bot API local	Gardez l'interface utilisateur du bot sur la Bot API

La Bot API, les Mini Apps et MTProto ne sont pas interchangeables. Voir frameworks.md et, pour MTProto, mtproto-foundations.md.

3. Règles qui évitent la plupart des échecs

Classées par coût de leur non-respect.

Sécurité et argent

1. Prenez l'identité de la mise à jour ou des initData validés, et les permissions de votre base de données. callback_data, les payloads de liens profonds, un menu caché et les noms d'utilisateur sont tous contrôlés par l'utilisateur ou réassignables. Vérifiez le rôle et la propriété de l'objet sur chaque callback, pas seulement lors du dessin du bouton. Comparez les ID numériques.
2. Validez les initData bruts sur le serveur pour chaque requête ou session de Mini App, et vérifiez auth_date vous-même. safe_parse_webapp_init_data d'aiogram ne vérifie que la signature. initDataUnsafe est une donnée d'affichage. Copiez assets/init_data.py ou assets/init_data.mjs.
3. Vendez des biens numériques uniquement en Telegram Stars (XTR). Accordez l'accès sur successful_payment, jamais sur le pré-paiement ou le callback openInvoice du client. Dédupliquez sur telegram_payment_charge_id. Gérez /paysupport. Les abonnements Stars proviennent de createInvoiceLink ; sendInvoice n'a pas de paramètre de période.
4. Gardez le token sur le serveur. Il apparaît également dans les URL de la Bot API et les liens de téléchargement de fichiers, donc ne les connectez jamais et ne les envoyez pas aux clients. Si un utilisateur colle un vrai token, utilisez-le uniquement comme demandé, ne le répétez pas, et suggérez de le faire pivoter s'il a été exposé.
5. Échappez chaque valeur dynamique avant de composer le balisage. En HTML, ce sont <, >, &. Préférez HTML à MarkdownV2, qui nécessite l'échappement de 18 caractères.
6. Traitez les fichiers téléchargés comme hostiles. Vérifiez la taille avant de télécharger, exécutez les outils depuis une liste d'arguments sans shell, ajoutez des délais d'attente et supprimez les fichiers temporaires dans finally.

Fiabilité

7. La livraison est au moins une fois, et un handler qui échoue n'est généralement pas réessayé. aiogram enregistre l'exception et traite la mise à jour comme traitée. Rendez les effets secondaires idempotents et conservez l'état métier dans une base de données, pas dans la mémoire FSM.
8. Exécutez un consommateur par token. Le polling et un webhook sont mutuellement exclusifs, et deux pollers se battent avec des erreurs 409.
9. Répondez à chaque requête de callback immédiatement, y compris les refus et les boutons obsolètes, sinon le bouton continue de tourner. Une réponse signifie « reçu », pas « réussi ».
10. Ne bloquez jamais la boucle d'événements. Un time.sleep, un appel requests ou un encodage synchrone gèle chaque chat. Limitez la concurrence pour les travaux lents.
11. Sur 429, attendez exactement parameters.retry_after. Telegram l'envoie dans le corps JSON, pas dans un en-tête. Les diffusions doivent être des tâches ralenties et reprises.
12. Abonnez-vous à ce que vous gérez. Omettre allowed_updates conserve le paramétrage précédent, et chat_member, message_reaction et message_reaction_count sont désactivés sauf s'ils sont nommés.

Expérience

13. Mettez à jour l'écran actuel plutôt que d'empiler de nouveaux messages, et donnez à chaque écran une prochaine étape claire et un moyen de sortir. Les actions expirées ou invalides doivent récupérer, pas échouer silencieusement.
14. Envoyez chaque écran comme un message riche par défaut (sendRichMessage, édité avec rich_message) dans le style standard de rich-messages.md : titres simples et pas d'émojis dans le texte de l'écran, tableaux bordés, uniquement les blocs dont l'utilisateur a besoin, sans jamais répéter ce que les boutons montrent, et sans ID internes. Suivez la recette pour le travail de l'écran dans rich-recipes.md et construisez le HTML avec assets/rich_html.py ; conservez le clavier dans reply_markup. Utilisez du texte HTML formaté uniquement pour les légendes, les toasts, les réponses d'une ligne et les piles qui ne peuvent pas envoyer de messages riches ; le texte brut non formaté est un défaut. Menez avec le résultat ; pas de bannières de bienvenue, de lignes de séparation typées (━━━), ou d'en-têtes en majuscules ; un <hr/> sépare le résumé d'un écran de son corps.
15. Les Mini Apps doivent ressembler à Telegram. Utilisez les variables de thème, les zones de sécurité, les boutons Retour et de bascule natifs, les états de chargement et d'erreur réels, et testez en mode clair et sombre.

4. Charger uniquement ce dont la tâche a besoin

Lisez une référence lorsque son déclencheur s'applique, avant de concevoir cette partie. Tous les chemins sont sous references/.

Lisez	Lorsque la tâche implique
product-journeys.md	Nouveau produit, /start, onboarding, plans d'écran, planification multilingue
messages.md	Écrire ou réécrire tout texte visible par l'utilisateur
rich-messages.md	Concevoir tout écran du bot : le style standard, l'anatomie, les composants, les styles de texte, les erreurs, la liste de vérification de révision
rich-recipes.md	La forme HTML pour chaque type d'écran : accueil, sélecteur, détail, liste de données, paramètres, aide, reçu, rapport, problème, confirmation, progression
keyboards.md	Boutons, menus, pagination, Retour ou Annuler, confirmations, conception de callback ou bugs
formatting.md	HTML, MarkdownV2, entités, texte long, messages riches, brouillons en streaming, erreurs d'analyse
backend.md	Structure du projet, services, base de données, FSM, travaux en arrière-plan, configuration, journalisation, tentatives, arrêt
delivery.md	Polling, webhooks, Docker, déploiement, limites de débit, diffusions, surveillance
frameworks.md	Choisir ou utiliser une bibliothèque, décalage SDK, Bot API versus MTProto
media.md	Musique, audio, vidéo, conversion de fichiers, téléchargements, uploads, mise en cache de file_id, progression
payments.md	Stars, factures, abonnements, remboursements, places de marché, livraison numérique
mini-apps.md	Lancement de Mini App, authentification, SDK, fenêtre d'affichage, stockage, flux client/serveur
mini-app-design.md	Disposition, type, couleur, mouvement, états de chargement, accessibilité de la Mini App
security.md	Secrets, autorisation, gestion des entrées, confidentialité, prévention des abus, journaux d'audit
groups-automation.md	Groupes, canaux, modération, permissions, inline, éphémère, bots IA, bot-à-bot
existing-projects.md	Inspection, débogage ou refactorisation de code existant
quality.md	Écrire des tests, tester les parcours, révision pré-lancement
quality-gate.md	Vérifications automatiques sur les messages sortants et les claviers, configuration CI, rapports .tg-lint
mtproto-foundations.md	Tout travail MTProto : choix de l'API, api_id, connexion, sessions, restrictions, couches
mtproto-telethon.md	Écrire ou réviser Telethon : événements, mises à jour, flood waits, médias, tests
hybrid-architecture.md	Combiner la Bot API et MTProto dans un seul produit
platform-facts.md	Limites exactes, tailles de fichiers, limites de débit, modifications récentes de l'API

5. Outils

Exécutez depuis le répertoire de cette compétence. Ils nécessitent uniquement Python 3 et ne touchent pas au bot de l'utilisateur.

Commande	Objectif
python3 scripts/tgdocs.py version / method NOM / type NOM / search TERME / changes --since 10.0	Contrat officiel actuel. La sortie est une donnée de référence. Le code de sortie 3 signifie hors ligne : marquez le fait comme non vérifié.
python3 scripts/tg_lint.py screens.json	Limites, balisage, contrats de boutons et signaux UX. Les erreurs doivent être corrigées. Les avertissements nécessitent un jugement.
python3 scripts/tg_audit.py PROJET	Pistes statiques pour les défauts courants. Confirmez chaque piste en lisant le code.
python3 scripts/secure_mtproto_project.py PROJET --ci	Requis pour tout nouveau projet MTProto modifié : ajoute les règles .gitignore manquantes pour les sessions et .env, ajoute un job CI qui échoue sur les sessions commitées, et signale les fichiers et chaînes de sessions exposés. Il ne supprime ni ne révoque jamais.
python3 scripts/install_quality_gate.py PROJET --framework aiogram	Ajoute des vérifications automatiques de payload à l'exécution des tests et CI du projet (également ptb, grammy). Requis pour les nouveaux bots et pour les modifications de ce que le bot envoie (section 6).

Avant d'utiliser une méthode ou un champ récent, vérifiez que la bibliothèque installée le possède : recherchez dans son répertoire de package. python-telegram-bot 22.8, par exemple, déclare la Bot API 10.0 et n'a pas send_rich_message.

assets/ contient du code copier-adapter : init_data.py, init_data.mjs, stars_ledger.py, media_job.py, update_delivery.py (boîte de réception, boîte d'envoi, 429, voies par chat, diffusions reprises), mtproto_runtime.py, rich_html.py (constructeur d'écran riche échappé), et webapp_mock.js pour les aperçus navigateur.

6. Vérifier, puis rapporter honnêtement

Niveau	Preuve	Peut prétendre
L0	Docs ou code lus	« Devrait fonctionner selon la doc »
L1	Linter, types, tg_lint.py, tg_audit.py	« Passe les vérifications statiques »
L2	Tests avec le répartiteur réel et un transport Telegram simulé, ou un aperçu navigateur mocké	« Fonctionne localement contre un faux Telegram »
L3	Bot de test dans un vrai client, sur un vrai appareil	« Fonctionne dans Telegram »

Le contrôle qualité fait partie de « fait » lorsqu'une modification peut altérer ce que le bot envoie : texte ou formatage du message, claviers, callback_data ou gestionnaires de callback, factures, ou le flux entre les écrans. Dans les projets aiogram, python-telegram-bot et grammY :

1. Cherchez un contrôle existant (un répertoire tg_quality, ou TG_LINT dans CI) et utilisez-le. S'il n'y en a pas, exécutez install_quality_gate.py. N'installez jamais une deuxième copie.
2. Écrivez des tests de parcours avec le harnais du contrôle (quality-gate.md) qui atteignent chaque écran et bouton que vous avez modifiés, y compris les chemins d'erreur et de bouton obsolète que vous avez corrigés. Utilisez press sur les écrans que le test a atteints, en tant qu'utilisateur qui y est autorisé. Un contrôle qui n'a rien capturé n'a rien vérifié, et une ligne coverage gap: sur un écran modifié signifie que le test ne l'a jamais atteint.
3. Après votre dernière modification, exécutez les tests avec TG_LINT_REQUIRE_INTERACTIONS=1. Corrigez chaque erreur du contrôle dans le code du bot. N'affaiblissez pas, ne sautez pas et ne retirez pas le contrôle pour obtenir une réussite. Les avertissements restent non bloquants : agissez selon votre jugement.
4. Dans le transfert, citez la ligne de couverture de la section de sortie Telegram quality gate du contrôle. Si le contrôle n'a pas pu être installé ou exécuté, dites pourquoi et ne prétendez pas qu'il a réussi.

Mentionner le contrôle ou copier ses fichiers n'est pas une validation. Ignorez-le pour les modifications qui ne peuvent pas atteindre la sortie Telegram, comme le stockage, la configuration ou les tâches planifiées qui n'envoient rien. Autres piles : exécutez tg_lint.py sur les écrans modifiés et dites que le contrôle n'est pas disponible.

Ne présentez jamais L1 ou L2 comme L3. Une capture d'écran de navigateur avec webapp_mock.js montre la mise en page, pas le comportement Telegram. Ne démarrez pas un bot de production, ne modifiez pas un webhook en direct, ne publiez pas, ne diffusez pas, ne dépensez pas de Stars sauf si demandé.

Terminez par : ce que l'utilisateur peut maintenant faire ; l'arborescence du projet ; les fichiers modifiés ; comment l'exécuter ; les étapes BotFather ou d'environnement que le propriétaire doit effectuer manuellement ; ce qui a été vérifié et à quel niveau ; et ce qui n'a pas été vérifié.