hliubsuslov/telegram-bot-ui

Interface Utilisateur Bot Telegram

Compétence portable et indépendante du SDK pour l'ensemble du cycle de vie de l'interface utilisateur d'un bot Telegram : audit → carte écran/état → conception du texte, des boutons et de la navigation → implémentation → migration → tests → documentation.

Un bot Telegram n'a pas de CSS ni de moteur de mise en page. Son interface entière est composée de cinq éléments : le texte du message, le formatage, les claviers, le chrome de la conversation (commandes, bouton de menu, liens profonds), et les transitions entre les états. Cette compétence traite les cinq comme une seule surface de conception.

Objectif

Aider un agent à rendre l'interface d'un bot claire, cohérente et sûre à modifier : choisir ce qu'un écran dit et comment il le dit ; étiqueter, grouper, ordonner, colorer et disposer les boutons ; concevoir la navigation entre les écrans et les états ; garantir la cohérence de chaque écran avec le reste du bot ; maintenir la localisation intacte ; et restituer le corps des messages avec le format le plus riche qui convienne — dans n'importe quelle langue et n'importe quel SDK Telegram, sans casser les gestionnaires existants ni la logique métier.

Quand l'utiliser

• Travail sur l'interface : « améliorer l'UX/UI du bot », « repenser ce menu », « le clavier est surchargé », « les utilisateurs ne comprennent pas cet écran », « ajouter un bouton retour », « grouper ces actions », « faire ressortir l'action principale ».
• Boutons et claviers : claviers inline, claviers de réponse, étiquettes de boutons, ordre et disposition des boutons, couleurs style, icon_custom_emoji_id emoji personnalisé, boutons Web App / URL / copie de texte / switch-inline, ForceReply, suppression du clavier, pagination et navigation retour.
• Texte et microcopie : réécriture des messages du bot, titres, légendes, invites, confirmations, états d'erreur et vides, ton et longueur, utilisation d'emojis.
• Chrome de la conversation : liste des /commandes et portées, bouton de menu, /start et liens profonds, expérience de première utilisation.
• Retour dynamique : réponses IA en streaming (sendMessageDraft, sendRichMessageDraft, <tg-thinking>), barres de progression, statuts « en train d'écrire », chargeurs de boutons, « le bot semble figé pendant qu'il travaille ».
• Personnalisation et liens : saluer les utilisateurs par leur nom en toute sécurité, indices de locale, boutons URL vs liens inline, aperçus de liens, liens profonds, mentions.
• Cohérence : la même action nommée de trois manières différentes, boutons retour qui n'existent que sur certains écrans, états incohérents après une modification.
• Rendu des messages : HTML / MarkdownV2 / MessageEntity, emoji personnalisé dans le texte, légendes, tableaux et messages enrichis, options d'aperçu de lien / silencieux / protégé, découpage des messages longs, brouillons en streaming, modification, publications de canal, localisation et RTL, impossible d'analyser les entités, messages cassés ou surdimensionnés.

Quand NE PAS l'utiliser

Logique de bot qui n'apparaît pas dans l'interface : infrastructure de webhook, traitement des paiements, autorisation, bases de données et migrations, logique d'administration et de modération de groupe, scraping, pipelines d'analyse, parties internes de la Mini App (sa propre interface HTML/CSS est un travail de développement web ordinaire — cette compétence ne couvre que la surface côté Telegram : le bouton ou le menu qui l'ouvre). Non plus pour les fichiers .rtf Microsoft.

Terminologie — ne pas confondre

• Clavier inline ≠ clavier de réponse. InlineKeyboardMarkup est attaché à un message spécifique et envoie callback_query / ouvre des URLs. ReplyKeyboardMarkup remplace le clavier de lettres de l'utilisateur et envoie du texte comme un message normal. Différentes classes de boutons, différentes expériences utilisateur.
• style n'est pas une valeur de couleur. C'est exactement l'un des primary, success, danger. Telegram n'a pas de couleurs de boutons HEX/RGB/CSS.
• icon_custom_emoji_id n'est pas un file_id, ni un nom de pack d'emojis, ni un lien, ni un emoji Unicode. C'est l'ID d'un emoji personnalisé spécifique.
• Le texte enrichi Telegram N'EST PAS le RTF Microsoft. Ne jamais appeler les messages enrichis « RTF ».
• Markdown enrichi ≠ MarkdownV2. MarkdownV2 est un parse_mode pour les messages normaux avec un échappement strict. Le Markdown enrichi est la syntaxe de document pour les messages enrichis.
• HTML enrichi ≠ HTML de navigateur arbitraire. Seul l'ensemble de balises pris en charge par Telegram.
• Modifier un clavier ≠ renvoyer un écran. editMessageReplyMarkup et editMessageText mettent à jour sur place ; envoyer un nouveau message empile les écrans.

Politique de source de vérité

Faire confiance dans cet ordre :

1. Documentation officielle actuelle de Telegram (API Bot, fonctionnalités du bot, pages de formatage, blog officiel).
2. Journal des modifications officiel de l'API Bot.
3. Documentation du SDK réellement installé dans le projet.
4. Code source du SDK.
5. Suivi des problèmes du SDK.
6. Articles tiers — contexte supplémentaire uniquement.

Revérifier la documentation officielle avant d'agir lorsque : la tâche touche de nouvelles API ; aujourd'hui est postérieur à la date de « dernière vérification » dans references/official-sources.md ; la version de l'API Bot du projet est inconnue ; la documentation du SDK contredit l'API Bot ; vous rencontrez un type/champ inconnu ; ou l'utilisateur demande « les dernières fonctionnalités ». Cette compétence n'est pas figée à l'API Bot 10.2 — si Telegram a publié une version plus récente, utilisez-la. Points de contrôle de version pertinents pour l'UI : references/ui-changelog.md.

Flux de travail principal (auditer avant de reconcevoir)

1. Lisez les instructions du projet (AGENTS.md / CLAUDE.md / README / docs).
2. Détectez le langage, le framework, le SDK Telegram et les versions exactes.
3. Déterminez la version de l'API Bot que le SDK prend réellement en charge — cela décide si style et icon_custom_emoji_id sont accessibles.
4. Construisez une carte écran/état : chaque message que l'utilisateur peut voir, chaque clavier, chaque callback_data, chaque commande, chaque transition (references/navigation-and-flows.md).
5. Classez chaque écran : entrée / menu / étape de formulaire / confirmation / résultat / erreur / vide / notification.
6. Identifiez les véritables défauts UX (n'inventez pas de travail) : étiquettes ambiguës, claviers surchargés, impasses sans retour possible, nommage incohérent, actions destructrices à un tap, chaînes non localisées, corps illisibles.
7. Concevez la correction : texte d'abord, puis structure, puis disposition, puis couleur/emoji — dans cet ordre. La couleur est la dernière couche, jamais le correctif d'une mauvaise étiquette.
8. Vérifiez la prise en charge du SDK pour chaque champ que vous prévoyez d'utiliser (references/sdk-compatibility.md).
9. Implémentez dans le style et les utilitaires existants du projet (ne dupliquez pas ses constructeurs de claviers).
10. Préservez callback_data, les URLs, les liens profonds, le routage des gestionnaires et les clés de localisation, sauf si l'utilisateur a explicitement demandé de les modifier.
11. Ajoutez un chemin de secours et maintenez les anciens clients utilisables (references/errors-and-fallbacks.md).
12. Ajoutez des tests avec l'infrastructure de test existante du projet (references/testing-playbook.md).
13. Exécutez le lint / la vérification de type / les tests / les vérifications de fumée applicables du projet.
14. Rapportez : carte d'écran, ce qui a changé et pourquoi, ce qui a été délibérément laissé intact, les limites et les preuves de vérification.

Ne pas écrire de code d'implémentation avant les étapes 1 à 6 terminées.

Les cinq couches de l'UI (concevoir dans cet ordre)

#	Couche	Question à laquelle elle répond	Référence
1	Mots	L'utilisateur comprend-il ce que c'est et ce qui se passe ensuite ?	references/microcopy-and-labels.md
2	Structure	Quelles actions existent, comment sont-elles groupées et ordonnées ?	references/inline-keyboards.md, references/reply-keyboards.md
3	Navigation	Comment j'arrive ici, je reviens en arrière et je sors ? Dans quel état suis-je ?	references/navigation-and-flows.md
4	Rendu du corps	Le contenu est-il lisible — tableau, liste, titres, texte brut ?	references/format-selection.md, references/tables.md
5	Accentuation	Quelle est *l'*action ici ? Qu'est-ce qui est dangereux ?	references/buttons-and-styles.md, references/custom-emoji.md

Un écran qui échoue à la couche 1 ne peut pas être sauvé par les couches 4–5. Ne jamais commencer par la couleur.

Essentiels des boutons (règles complètes dans references/buttons-and-styles.md)

Exactement une action par bouton inline. Selon l'API Bot, InlineKeyboardButton nécessite exactement un des champs autres que text, icon_custom_emoji_id et style (url, callback_data, web_app, login_url, switch_inline_query*, copy_text, callback_game, pay). KeyboardButton autorise au plus un de ses champs non text/icon/style.

style (API Bot 9.4) — facultatif, exactement l'un des suivants :

style	Couleur	Signification	Étiquettes typiques
primary	bleu	*L'*action principale avant de l'écran	Continuer, Démarrer, Ouvrir, Suivant, Choisir
success	vert	Valider / confirmer / terminer positivement	Enregistrer, Confirmer, Publier, Soumettre, Terminer
danger	rouge	Destructeur ou irréversible	Supprimer, Réinitialiser, Se désabonner, Quitter, Annuler le plan
omis	défaut de l'app	Tout le reste	Retour, Paramètres, Aide, options secondaires

Si style est omis, un style spécifique à l'application est utilisé. Au plus un primary par écran. danger uniquement pour les actions véritablement destructrices, accompagné d'une étape de confirmation. Les actions secondaires comme « Retour » restent normalement sans style.

icon_custom_emoji_id (API Bot 9.4) — affiche un emoji personnalisé avant le texte du bouton. Utilisable uniquement par les bots qui ont acheté des noms d'utilisateur supplémentaires sur Fragment, ou dans les messages envoyés directement par le bot aux chats privés, aux groupes et aux supergroupes lorsque le propriétaire du bot a Telegram Premium. Ne jamais inventer un ID — l'obtenir (references/custom-emoji.md) ou demander à l'utilisateur.

Les deux champs sont une décoration au-dessus d'un bouton fonctionnel : l'étiquette doit toujours avoir un sens sans couleur et sans icône.

Corps du message : le plus riche qui aide

Besoin	Utilisation
Lignes/colonnes ou données étiquette→valeur	Tableau — references/tables.md
Document structuré : rapport, réponse IA, comparaison, liste de contrôle	Markdown enrichi
Contenu généré par modèle, contrôle précis des balises	HTML enrichi
Génération typée à partir de données / CMS / AST	Blocs InputRichBlock
Écran avec un clavier : invite courte + options	HTML régulier, court
Contrôle exact du décalage, pas de parse_mode	MessageEntity
Aucun style nécessaire	Texte brut

Règle : les données structurées deviennent un vrai tableau, jamais une grille monospace — mais un écran de menu est une invite courte plus des boutons, pas un essai. Matrice complète : references/format-selection.md.

Retour d'information pendant que le bot travaille

Attendre sans signal est le défaut UX le plus courant dans les bots. Choisissez en fonction de la forme de l'opération (règles complètes : references/dynamic-feedback-and-streaming.md) :

Situation	Mécanisme
Bouton inline tapé	answerCallbackQuery d'abord, puis faire le travail
Opération de 2 à 5 s	sendChatAction (typing, upload_photo, …) — max 5 s
Texte IA en cours de génération (chat privé)	sendMessageDraft — même draft_id, finaliser avec sendMessage
Réponse IA avec structure	sendRichMessageDraft + <tg-thinking> → sendRichMessage
Étapes réelles et nommables	editMessageText, limité
Progrès non mesurable	Étapes nommées — jamais un pourcentage factice
Processus interactif	Mini App (BottomButton.showProgress(), WebApp.ready())

Ne jamais modifier par token : mettre à jour toutes les ~800–1500 ms, ~30–80 nouveaux caractères, une phrase terminée ou un changement d'étape réel — et respecter retry_after. Un draft_id / message_id / operation_id par opération, finalisé exactement une fois.

Quelle référence lire (orientée par la tâche — ne pas toutes les lire)

UI / UX

• Étiquettes de boutons, formulation des messages, ton, emoji dans le texte → references/microcopy-and-labels.md
• Couleurs style, accentuation, disposition et groupement des boutons → references/buttons-and-styles.md
• Claviers inline, callback_data, pagination, modification sur place → references/inline-keyboards.md
• Claviers de réponse, ForceReply, suppression du clavier, espaces réservés → references/reply-keyboards.md
• Écrans, états, retour/accueil, commandes, bouton de menu, liens profonds → references/navigation-and-flows.md
• Emoji personnalisé sur les boutons et dans le texte, obtention des IDs, éligibilité → references/custom-emoji.md
• Réponses en streaming, blocs de réflexion, barres de progression, chargeurs, actions de chat → references/dynamic-feedback-and-streaming.md
• Personnalisation avec les données utilisateur, liens, aperçus, liens profonds → references/personalization-and-links.md
• Cohérence inter-écrans + la liste de contrôle avant finalisation → references/consistency-and-review.md
• Historique de l'API Bot pertinent pour l'UI et points de contrôle de version → references/ui-changelog.md
• Scénarios avant/après travaillés → references/examples-before-after.md

Rendu du contenu

• Tableaux → references/tables.md
• Messages enrichis / blocs / matrice de capacités → references/telegram-capabilities.md
• HTML / MarkdownV2 / entités / légendes / aperçus → references/regular-formatting.md
• Choix d'un format → references/format-selection.md
• Médias → references/rich-media.md
• Limites et découpage → references/limits-and-splitting.md
• Brouillons en streaming et modification → references/streaming-and-editing.md
• Canaux, notifications, diffusions → references/channels-and-broadcasting.md

Ingénierie

• Enquête sur un projet inconnu → references/project-adaptation.md
• Échappement / injection / contenu utilisateur ou IA → references/security-and-escaping.md
• Localisation, RTL, longueur des étiquettes de bouton → references/localization-and-rtl.md
• Erreurs, solutions de secours, anciens clients → references/errors-and-fallbacks.md
• Lacunes du SDK / charges utiles brutes de l'API Bot → references/sdk-compatibility.md
• Tests → references/testing-playbook.md
• Sources et dates de dernière vérification → references/official-sources.md

Validateurs locaux : scripts/validate_skill.py, scripts/validate_references.py, scripts/validate_keyboard.py (règles JSON du clavier — hors ligne, pas de jeton). Scénarios de déclenchement : evals/activation-evals.md.

Règles non négociables

• Préserver le comportement. Conserver callback_data, URLs, liens profonds, charges utiles et routage des gestionnaires existants. Une refonte visuelle ne doit pas réécrire les gestionnaires. Si un changement de callback_data est inévitable, le dire et mettre à jour chaque gestionnaire/route dans le même changement.
• Les mots avant les pixels. Corriger l'étiquette avant d'ajouter une couleur ou un emoji.
• Pas de couleur décorative. Attribuer style par la signification de l'action. Ne pas colorer chaque bouton ; un clavier entièrement coloré n'a pas de hiérarchie.