Wie ich einen Telegram-Bot mit meinem Backend für Echtzeit-Prosodieanalyse verbunden habe

Ich baue gerade Acento, ein Aussprache-Coaching-Tool, das analysiert, wie Sie Englisch sprechen. Es begann als Web-App, aber der natürlichste Weg, das Sprechen zu üben, ist einfach das Senden einer Sprachnachricht. Also habe ich das Backend mit einem Telegram-Bot verbunden. Sie nehmen auf, es analysiert, Sie erhalten Feedback. Keine App zum Installieren, keine UI zum Navigieren.

Hier sehen Sie, wie die Teile zusammenpassen, vom Webhook und der API bis zur Audio-Pipeline und der Autorisierungsschicht, die Telegram-Benutzer mit echten Konten verknüpft.

Die API, FastAPI auf Cloud Run

Das Backend ist eine FastAPI-Anwendung, die auf Google Cloud Run bereitgestellt wird. Sie stellt einige wichtige Endpunkte bereit, aber zwei sind am wichtigsten.

• POST /api/analyze, der Hauptanalyse-Endpunkt, der von der Web-App verwendet wird
• POST /api/telegram/webhook, wohin Telegram jede Nachricht sendet, die der Bot empfängt

Cloud Run übernimmt die Skalierung automatisch. Wenn niemand um 3 Uhr morgens Sprachnachrichten sendet, skaliert es auf null. Wenn ein Dutzend Leute in der Mittagspause üben, startet es weitere Instanzen. Das Backend ist zustandslos, daher funktioniert das einwandfrei.

Der Telegram-Bot selbst wird über BotFather registriert, und ich habe die Webhook-URL so eingestellt, dass sie auf meinen Cloud Run-Dienst zeigt. Von diesem Zeitpunkt an wird jede Nachricht, Sprachnotiz oder Tastendruck, die im Bot-Chat stattfindet, als JSON-Payload an meinen Endpunkt weitergeleitet.

Empfangen und Weiterleiten von Telegram-Updates

Wenn Telegram den Webhook-Endpunkt aufruft, überprüft das Backend als Erstes die Anfrage. Telegram sendet ein geheimes Token im Header X-Telegram-Bot-Api-Secret-Token, das ich mit einem zeitkonstanten Vergleich abgleiche, um Timing-Angriffe zu verhindern. Wenn das Geheimnis nicht übereinstimmt, wird die Anfrage sofort abgelehnt.

Nach der Überprüfung untersucht der Handler, um welche Art von Update es sich handelt.

• Textbefehle wie /start, /help, /practice oder /setkey werden an ihre jeweiligen Handler weitergeleitet
• Sprachnachrichten lösen die vollständige Analyse-Pipeline aus
• Callback-Abfragen verarbeiten Inline-Tastendrücke, z. B. wenn ein Benutzer auf „Details“ tippt, um seine Ergebnisse anzuzeigen

Der Webhook gibt immer schnell 200 OK zurück. Die eigentliche Verarbeitung erfolgt im Hintergrund, damit Telegram nicht auf eine Antwort wartet.

Von der Sprachnachricht zu Prosodie-Scores

Wenn ein Benutzer eine Sprachnachricht sendet, durchläuft das Backend mehrere Schritte.

1. Lädt die Audiodatei mit der Datei-ID aus der Webhook-Payload von den Telegram-Servern herunter
2. Konvertiert sie mit pydub und ffmpeg von OGG/Opus (Standard von Telegram) in WAV bei 16 kHz Mono
3. Führt eine Prosodie-Analyse mit Parselmouth (ein Python-Wrapper für Praat) über fünf Dimensionen durch, darunter Tonhöhenbereich in Halbtönen, Lautstärkedynamik, Sprechtempo, Rhythmusmuster (nPVI) und Pausenverteilung
4. Generiert KI-Coaching, indem die Audiodatei zur Transkription und für Aussprachetipps an Google Gemini gesendet wird
5. Formatiert und sendet eine kompakte Antwort über die Telegram Bot API zurück

Jede Dimension erhält einen Score von 1 bis 10 und diese werden zu einem gewichteten Gesamtscore kombiniert, wobei die Tonhöhe 25 %, Lautstärke und Tempo jeweils 20 %, der Rhythmus 20 % und die Pausen 15 % ausmachen. Der Benutzer erhält eine kurze Zusammenfassung mit seinem Hauptproblem und einem umsetzbaren Tipp sowie einer „Details“-Schaltfläche, auf die er tippen kann, um die vollständige Aufschlüsselung anzuzeigen.

Zwei Pfade, ein Authentifizierungssystem

Das Backend unterstützt zwei Authentifizierungsmethoden.

Firebase ID-Tokens werden von der Web-App verwendet. Das Frontend sendet ein Bearer-Token im Authorization-Header, das Backend verifiziert es mit dem Firebase Admin SDK, und der Benutzer erhält vollen Zugriff auf seinen Verlauf, seinen Fortschritt und sein KI-Coaching.

API-Schlüssel werden vom Telegram-Bot verwendet. Wenn ein Benutzer über die Web-App einen API-Schlüssel erstellt, generiert das Backend einen zufälligen Schlüssel, zeigt ihn einmal an und speichert nur dessen SHA-256-Hash in Firestore. Der Schlüssel wird in einem X-Acento-Key-Header gesendet. Jeder Schlüssel hat ein konfigurierbares Tageslimit, um Missbrauch zu verhindern.

Aber Telegram-Benutzer senden keine HTTP-Header. Sie senden einfach Sprachnachrichten. Ich brauchte also eine Möglichkeit, einen Telegram-Chat mit einem Acento-Konto zu verknüpfen.

Verknüpfung von Telegram mit Ihrem Konto

Der Befehl /setkey schließt die Lücke. Ein Benutzer gibt /setkey acento_xxxxx im Bot-Chat ein. Das Backend löscht diese Nachricht sofort (damit der Schlüssel nicht im Chatverlauf verbleibt), hasht den Schlüssel, sucht ihn in der Sammlung api_keys nach und erstellt, falls er übereinstimmt, ein Dokument telegram_links, das seine Telegram-Chat-ID mit seiner Acento-Benutzer-ID und seinem API-Schlüssel verknüpft.

Von da an wird jede Sprachnachricht aus diesem Chat automatisch seinem Konto zugeordnet. Das Backend überprüft sein API-Schlüsselkontingent, speichert Analyse-Sitzungen in Firestore und verfolgt seine Übungs-Serie.

Benutzer, die kein Konto verknüpft haben, können den Bot trotzdem nutzen. Sie erhalten eine Prosodie-Analyse (kein KI-Coaching) mit einem Limit von 10 Analysen pro Tag, verfolgt nach Chat-ID in einer separaten Sammlung telegram_anon_usage.

Tägliche Erinnerungen und Serien

Sobald ein Benutzer verknüpft ist, kann er tägliche Übungserinnerungen aktivieren. Ein Cloud Scheduler-Job ruft jede Stunde POST /api/telegram/send-reminders mit einem geheimen Header auf. Das Backend prüft, welche Benutzer für diese Stunde Erinnerungen aktiviert haben, und sendet ihnen eine Nachricht mit einem Übungssatz.

Die Erinnerungsnachricht passt sich dem Kontext an. Wenn Sie eine aktive Serie haben und gestern verpasst haben, erhalten Sie einen „Nicht die Serie unterbrechen“-Anstoß. Wenn Sie drei oder mehr Tage inaktiv waren, ist es eine sanftere Wiedereinstiegsaufforderung. Die Serie selbst erhöht sich, wenn Sie an aufeinanderfolgenden Tagen üben, und wird zurückgesetzt, wenn Sie einen Tag auslassen.

Alles zusammenfügen

Der gesamte Ablauf sieht wie folgt aus.

Kein App Store, kein Anmeldeformular, keine Ladebildschirme. Öffnen Sie einfach Telegram, nehmen Sie Ihre Stimme auf und erhalten Sie in Sekundenschnelle Feedback. Die Architektur hält die Dinge einfach. Ein Webhook-Endpunkt, eine Analyse-Pipeline und ein leichtgewichtiger Verknüpfungsmechanismus, der die Welt von Telegram mit dem Rest des Systems verbindet.

Wenn Sie es selbst ausprobieren möchten, besuchen Sie accent.learnenglishsounds.com und nehmen Sie etwas auf. Oder öffnen Sie einfach den Bot auf Telegram und senden Sie eine Sprachnachricht. Der Einstieg ist kostenlos, kein Konto erforderlich.