hlibsuslov/telegram-bot-ui

Telegram Bot UI

Portable, SDK-unabhängige Fertigkeit für den gesamten Lebenszyklus der Benutzeroberfläche eines Telegram-Bots: Überprüfung → Bildschirm-/Zustandsübersicht → Text-, Tasten- und Navigationsdesign → Implementierung → Migration → Test → Dokumentation.

Ein Telegram-Bot hat weder CSS noch ein Layout-Engine. Seine gesamte Oberfläche besteht aus fünf Dingen: Nachrichtentext, Formatierung, Tastaturen, das Chat-Chrome (Befehle, Menü-Button, Deep Links) und die Übergänge zwischen Zuständen. Diese Fertigkeit behandelt alle fünf als eine zusammenhängende Designfläche.

Zweck

Einem Agenten helfen, die Oberfläche eines Bots klar, konsistent und sicher änderbar zu machen: auswählen, was ein Bildschirm sagt und wie er es sagt; Tasten beschriften, gruppieren, anordnen, einfärben und layouten; die Navigation zwischen Bildschirmen und Zuständen entwerfen; jeden Bildschirm konsistent mit dem Rest des Bots halten; die Lokalisierung intakt lassen; und Nachrichtentexte mit dem reichhaltigsten Format darstellen, das passt – über jede Sprache und jedes Telegram-SDK hinweg, ohne bestehende Handler oder Geschäftslogik zu beschädigen.

Wann verwenden

• Oberflächenarbeit: "Verbessere die UX/UI des Bots", "Gestalte dieses Menü neu", "Die Tastatur ist überladen", "Benutzer verstehen diesen Bildschirm nicht", "Füge einen Zurück-Button hinzu", "Gruppiere diese Aktionen", "Lasse die Hauptaktion hervorstechen".
• Tasten und Tastaturen: Inline-Tastaturen, Antworttastaturen, Tastenbeschriftungen, Tastenanordnung und -layout, style-Farben, icon_custom_emoji_id-Custom-Emoji, Web-App-/URL-/Kopiertext-/Switch-Inline-Tasten, ForceReply, Tastaturentfernung, Paginierung und Zurück-Navigation.
• Text und Mikrokopien: Bot-Nachrichten, Titel, Bildunterschriften, Aufforderungen, Bestätigungen, Fehler- und Leerzustände, Ton und Länge, Emoji-Nutzung.
• Chat-Chrome: /commands-Liste und -Geltungsbereiche, Menü-Button, /start und Deep Links, erste Nutzungserfahrung.
• Dynamisches Feedback: Streaming von KI-Antworten (sendMessageDraft, sendRichMessageDraft, <tg-thinking>), Fortschrittsbalken, "tippt..."-Status, Tasten-Loader, "der Bot fühlt sich eingefroren an, während er arbeitet".
• Personalisierung und Links: Benutzer sicher mit Namen begrüßen, Locale-Hinweise, URL-Buttons vs. Inline-Links, Linkvorschauen, Deep Links, Erwähnungen.
• Konsistenz: Dieselbe Aktion auf drei verschiedene Weisen benannt, Zurück-Buttons, die nur auf manchen Bildschirmen existieren, inkonsistente Zustände nach einer Bearbeitung.
• Nachrichtendarstellung: HTML / MarkdownV2 / MessageEntity, Custom-Emoji in Text, Bildunterschriften, Tabellen und Rich Messages, Linkvorschau-/stille/geschützte Optionen, Aufteilung langer Nachrichten, Streaming-Entwürfe, Bearbeitung, Kanalbeiträge, Lokalisierung und RTL, can't parse entities, beschädigte oder überdimensionierte Nachrichten.

Wann NICHT verwenden

Bot-Logik, die nicht in der Oberfläche sichtbar ist: Webhook-Infrastruktur, Zahlungsabwicklung, Autorisierung, Datenbanken und Migrationen, Gruppenverwaltung und -moderationslogik, Scraping, Analyse-Pipelines, Mini-App-Interna (deren eigenes HTML/CSS-UI ist normale Web-Frontend-Arbeit – diese Fertigkeit deckt nur die Telegram-seitige Oberfläche ab: den Button oder das Menü, das sie öffnet). Auch nicht für Microsoft .rtf-Dateien.

Terminologie – nicht verwechseln

• Inline-Tastatur ≠ Antworttastatur. InlineKeyboardMarkup ist an eine bestimmte Nachricht angehängt und sendet callback_query / öffnet URLs. ReplyKeyboardMarkup ersetzt die Buchstabentastatur des Benutzers und sendet Text als normale Nachricht. Unterschiedliche Tastenklassen, unterschiedliche UX.
• style ist kein Farbwert. Es ist genau einer von primary, success, danger. Telegram hat keine HEX/RGB/CSS-Tastenfarben.
• icon_custom_emoji_id ist keine file_id, kein Emoji-Pack-Name, kein Link und kein Unicode-Emoji. Es ist die ID eines bestimmten Custom-Emojis.
• Telegram Rich Text ist NICHT Microsoft RTF. Rich Messages niemals als "RTF" bezeichnen.
• Rich Markdown ≠ MarkdownV2. MarkdownV2 ist ein parse_mode für normale Nachrichten mit strengem Escaping. Rich Markdown ist die Dokumentsyntax für Rich Messages.
• Rich HTML ≠ beliebiges Browser-HTML. Nur der von Telegram unterstützte Tag-Satz.
• Bearbeiten einer Tastatur ≠ erneutes Senden eines Bildschirms. editMessageReplyMarkup und editMessageText aktualisieren an Ort und Stelle; das Senden einer neuen Nachricht stapelt Bildschirme.

Quellen-Wahrheitsrichtlinie

Vertraue in dieser Reihenfolge:

1. Aktuelle offizielle Telegram-Dokumentation (Bot-API, Bot-Features, Formatierungsseiten, offizieller Blog).
2. Offizielles Bot-API-Änderungsprotokoll.
3. Dokumentation des tatsächlich im Projekt installierten SDKs.
4. SDK-Quellcode.
5. SDK-Issue-Tracker.
6. Drittanbieter-Artikel – nur ergänzender Kontext.

Überprüfe die offiziellen Dokumente vor dem Handeln erneut, wenn: die Aufgabe neue APIs betrifft; heute nach dem Datum der "letzten Überprüfung" in references/official-sources.md liegt; die Bot-API-Version des Projekts unbekannt ist; die SDK-Dokumentation der Bot-API widerspricht; du auf einen unbekannten Typ/ein unbekanntes Feld triffst; oder der Benutzer nach "den neuesten Fähigkeiten" fragt. Diese Fertigkeit ist nicht eingefroren bei Bot-API 10.2 – wenn Telegram eine neuere Version veröffentlicht hat, verwende sie. UI-relevante Versionsschwellen: references/ui-changelog.md.

Kernarbeitsablauf (Überprüfung vor Neugestaltung)

1. Lies die Anweisungen des Projekts (AGENTS.md / CLAUDE.md / README / Dokumentation).
2. Erkenne Sprache, Framework, Telegram-SDK und exakte Versionen.
3. Bestimme die Bot-API-Version, die das SDK tatsächlich unterstützt – dies entscheidet, ob style und icon_custom_emoji_id überhaupt erreichbar sind.
4. Erstelle eine Bildschirm-/Zustandsübersicht: jede Nachricht, die der Benutzer sehen kann, jede Tastatur, jedes callback_data, jeder Befehl, jeder Übergang (references/navigation-and-flows.md).
5. Klassifiziere jeden Bildschirm: Einstieg / Menü / Formularschritt / Bestätigung / Ergebnis / Fehler / Leer / Benachrichtigung.
6. Identifiziere die echten UX-Mängel (erfinde keine Arbeit): mehrdeutige Beschriftungen, überladene Tastaturen, Sackgassen ohne Rückweg, inkonsistente Benennung, destruktive Aktionen nur einen Tipp entfernt, nicht lokalisierte Zeichenfolgen, unlesbare Nachrichtentexte.
7. Entwerfe die Lösung: zuerst Text, dann Struktur, dann Layout, dann Farbe/Emoji – in dieser Reihenfolge. Farbe ist die letzte Schicht, niemals die Lösung für eine schlechte Beschriftung.
8. Überprüfe die SDK-Unterstützung für jedes Feld, das du verwenden möchtest (references/sdk-compatibility.md).
9. Implementiere im vorhandenen Stil und mit den vorhandenen Hilfsmitteln des Projekts (dupliziere nicht seine Tastatur-Ersteller).
10. Erhalte callback_data, URLs, Deep Links, Handler-Routing und Lokalisierungsschlüssel, es sei denn, der Benutzer hat explizit um eine Änderung gebeten.
11. Füge einen Fallback-Pfad hinzu und halte alte Clients nutzbar (references/errors-and-fallbacks.md).
12. Füge Tests mit der vorhandenen Testinfrastruktur des Projekts hinzu (references/testing-playbook.md).
13. Führe den Linter / Typchecker / die Tests / die relevanten Smoke-Checks des Projekts aus.
14. Berichte: Bildschirmübersicht, was geändert wurde und warum, was absichtlich unberührt blieb, Grenzen und Überprüfungsnachweise.

Schreibe keinen Implementierungscode, bevor die Schritte 1–6 abgeschlossen sind.

Die fünf UI-Ebenen (Entwurf in dieser Reihenfolge)

#	Ebene	Frage, die sie beantwortet	Referenz
1	Wörter	Versteht der Benutzer, was dies ist und was als Nächstes passiert?	references/microcopy-and-labels.md
2	Struktur	Welche Aktionen gibt es, wie sind sie gruppiert und angeordnet?	references/inline-keyboards.md, references/reply-keyboards.md
3	Navigation	Wie komme ich hierher, zurück und raus? In welchem Zustand bin ich?	references/navigation-and-flows.md
4	Inhaltsdarstellung	Ist der Inhalt lesbar – Tabelle, Liste, Überschriften, Klartext?	references/format-selection.md, references/tables.md
5	Hervorhebung	Was ist die Aktion hier? Was ist gefährlich?	references/buttons-and-styles.md, references/custom-emoji.md

Ein Bildschirm, der auf Ebene 1 versagt, kann nicht durch die Ebenen 4–5 gerettet werden. Niemals mit Farbe beginnen.

Tasten-Grundlagen (vollständige Regeln in references/buttons-and-styles.md)

Genau eine Aktion pro Inline-Taste. Gemäß der Bot-API erfordert InlineKeyboardButton genau eines der Felder außer text, icon_custom_emoji_id und style (url, callback_data, web_app, login_url, switch_inline_query*, copy_text, callback_game, pay). KeyboardButton erlaubt höchstens eines seiner Nicht-text/icon/style-Felder.

style (Bot-API 9.4) – optional, genau einer von:

style	Farbe	Bedeutung	Typische Beschriftungen
primary	blau	Die Hauptvorwärtsaktion des Bildschirms	Weiter, Starten, Öffnen, Nächster, Auswählen
success	grün	Commit / Bestätigen / Positiv abschließen	Speichern, Bestätigen, Veröffentlichen, Absenden, Fertig
danger	rot	Destruktiv oder unwiderruflich	Löschen, Zurücksetzen, Abbestellen, Verlassen, Plan kündigen
weggelassen	App-Standard	Alles andere	Zurück, Einstellungen, Hilfe, sekundäre Optionen

Wenn style weggelassen wird, wird ein App-spezifischer Stil verwendet. Maximal ein primary pro Bildschirm. danger nur für wirklich destruktive Aktionen, gepaart mit einem Bestätigungsschritt. Sekundäre Aktionen wie "Zurück" bleiben normalerweise ohne Stil.

icon_custom_emoji_id (Bot-API 9.4) – zeigt ein Custom-Emoji vor dem Tastentext an. Nur nutzbar von Bots, die weitere Benutzernamen auf Fragment erworben haben, oder in Nachrichten, die direkt vom Bot an private, Gruppen- und Supergruppen-Chats gesendet werden, wenn der Bot-Besitzer Telegram Premium hat. Erfinde niemals eine ID – besorge sie (references/custom-emoji.md) oder frage den Benutzer danach.

Beide Felder sind Verzierung auf einer funktionierenden Taste: Die Beschriftung muss auch ohne Farbe und ohne Icon Sinn ergeben.

Nachrichtentext: reichhaltigste passende Darstellung

Bedarf	Verwende
Zeilen/Spalten oder Label→Wert-Daten	Tabelle – references/tables.md
Strukturiertes Dokument: Bericht, KI-Antwort, Vergleich, Checkliste	Rich Markdown
Server-templatierter Inhalt, präzise Tag-Kontrolle	Rich HTML
Typisierte Generierung aus Daten / CMS / AST	InputRichBlock-Blöcke
Ein Bildschirm mit einer Tastatur: kurze Aufforderung + Optionen	Normales HTML, kurz
Exakte Offset-Kontrolle, kein parse_mode	MessageEntity
Wirklich keine Formatierung nötig	Klartext

Regel: Strukturierte Daten werden zu einer echten Tabelle, niemals zu einem Monospace-Raster – aber ein Menübildschirm ist eine kurze Aufforderung plus Tasten, kein Aufsatz. Vollständige Matrix: references/format-selection.md.

Feedback, während der Bot arbeitet

Warten ohne Signal ist der häufigste UX-Fehler bei Bots. Wähle je nach Art der Operation (vollständige Regeln: references/dynamic-feedback-and-streaming.md):

Situation	Mechanismus
Inline-Taste getippt	answerCallbackQuery zuerst, dann die Arbeit erledigen
2–5 s Operation	sendChatAction (typing, upload_photo, …) – max. 5 s
KI-Text wird generiert (privater Chat)	sendMessageDraft – gleiche draft_id, abschließen mit sendMessage
KI-Antwort mit Struktur	sendRichMessageDraft + <tg-thinking> → sendRichMessage
Reale, benennbare Phasen	editMessageText, gedrosselt
Fortschritt nicht messbar	Benannte Phasen – niemals einen gefälschten Prozentwert
Interaktiver Prozess	Mini-App (BottomButton.showProgress(), WebApp.ready())

Nie pro Token bearbeiten: Aktualisiere alle ~800–1500 ms, ~30–80 neue Zeichen, einen abgeschlossenen Satz oder einen echten Phasenwechsel – und beachte retry_after. Eine draft_id / message_id / operation_id pro Operation, genau einmal abgeschlossen.

Welche Referenz zu lesen ist (aufgabenbezogen – nicht alle lesen)

UI / UX

• Tastenbeschriftungen, Nachrichtenwortlaut, Ton, Emoji im Text → references/microcopy-and-labels.md
• style-Farben, Hervorhebung, Tastenlayout und -gruppierung → references/buttons-and-styles.md
• Inline-Tastaturen, callback_data, Paginierung, Bearbeitung an Ort und Stelle → references/inline-keyboards.md
• Antworttastaturen, ForceReply, Tastaturentfernung, Platzhalter → references/reply-keyboards.md
• Bildschirme, Zustände, Zurück/Startseite, Befehle, Menü-Button, Deep Links → references/navigation-and-flows.md
• Custom-Emoji auf Tasten und im Text, IDs besorgen, Berechtigung → references/custom-emoji.md
• Streaming-Antworten, Denkblöcke, Fortschrittsbalken, Loader, Chat-Aktionen → references/dynamic-feedback-and-streaming.md
• Personalisierung mit Benutzerdaten, Links, Vorschauen, Deep Links → references/personalization-and-links.md
• Bildschirmübergreifende Konsistenz + die Checkliste vor dem Abschluss → references/consistency-and-review.md
• UI-relevante Bot-API-Historie und Versionsschwellen → references/ui-changelog.md
• Vorher/Nachher-Szenarien → references/examples-before-after.md

Inhaltsdarstellung

• Tabellen → references/tables.md
• Rich Messages / Blöcke / Fähigkeitsmatrix → references/telegram-capabilities.md
• HTML / MarkdownV2 / Entitäten / Bildunterschriften / Vorschauen → references/regular-formatting.md
• Formatauswahl → references/format-selection.md
• Medien → references/rich-media.md
• Grenzen und Aufteilung → references/limits-and-splitting.md
• Streaming-Entwürfe und Bearbeitung → references/streaming-and-editing.md
• Kanäle, Benachrichtigungen, Broadcasts → references/channels-and-broadcasting.md

Technik

• Untersuchung eines unbekannten Projekts → references/project-adaptation.md
• Escaping / Injection / Benutzer- oder KI-Inhalte → references/security-and-escaping.md
• Lokalisierung, RTL, Tastenbeschriftungslänge → references/localization-and-rtl.md
• Fehler, Fallbacks, alte Clients → references/errors-and-fallbacks.md
• SDK-Lücken / rohe Bot-API-Payloads → references/sdk-compatibility.md
• Testen → references/testing-playbook.md
• Quellen und Daten der letzten Überprüfung → references/official-sources.md

Lokale Validierer: scripts/validate_skill.py, scripts/validate_references.py, scripts/validate_keyboard.py (Tastatur-JSON-Regeln – offline, kein Token). Auslöseszenarien: evals/activation-evals.md.

Unverhandelbare Regeln

• Verhalten erhalten. Vorhandenes callback_data, URLs, Deep Links, Payloads und Handler-Routing beibehalten. Ein visuelles Redesign darf Handler nicht umschreiben. Wenn eine Änderung von callback_data unvermeidbar ist, benenne es und aktualisiere jeden Handler/Route in derselben Änderung.
• Wörter vor Pixeln. Beschriftung korrigieren, bevor eine Farbe oder ein Emoji hinzugefügt wird.
• Keine dekorative Farbe. Weise style nach der Bedeutung der Aktion zu. Färbe nicht jeden Button; eine komplett eingefärbte Tastatur hat keine Hierarchie.
• style nicht für Inaktivität oder Lesbarkeit missbrauchen. Telegram hat keine deaktivierte style-Variante. Verwende stattdessen callback_answer mit einem Hinweis.