Hoe ik een Telegram-bot koppelde aan mijn backend voor real-time prosodie-analyse

Ik bouw Acento, een hulpmiddel voor uitspraakcoaching dat analyseert hoe je Engels spreekt. Het begon als een web-app, maar de meest natuurlijke manier om te oefenen met spreken is gewoon een spraakbericht sturen. Dus heb ik de backend gekoppeld aan een Telegram-bot. Je neemt op, het analyseert, je krijgt feedback. Geen app om te installeren, geen UI om doorheen te navigeren.

Dit is hoe de stukjes in elkaar passen, van de webhook en API tot de audio-pipeline en de autorisatielaag die Telegram-gebruikers koppelt aan echte accounts.

De API, FastAPI op Cloud Run

De backend is een FastAPI-applicatie die is geïmplementeerd op Google Cloud Run. Het stelt een paar belangrijke endpoints bloot, maar twee zijn het belangrijkst.

• POST /api/analyze, het belangrijkste analyse-endpoint dat door de web-app wordt gebruikt
• POST /api/telegram/webhook, waar Telegram elk bericht naartoe stuurt dat de bot ontvangt

Cloud Run zorgt automatisch voor schaalvergroting. Wanneer niemand om 3 uur 's nachts spraakberichten stuurt, schaalt het naar nul. Wanneer een dozijn mensen oefent tijdens de lunch, start het meer instanties op. De backend is stateless, dus dat werkt prima.

De Telegram-bot zelf is geregistreerd via BotFather, en ik heb de webhook-URL ingesteld om naar mijn Cloud Run-service te wijzen. Vanaf dat moment wordt elk bericht, spraakopname of knopdruk in de botchat doorgestuurd naar mijn endpoint als een JSON-payload.

Telegram-updates ontvangen en routeren

Wanneer Telegram het webhook-endpoint bereikt, is het eerste wat de backend doet het verzoek verifiëren. Telegram stuurt een geheim token in de header X-Telegram-Bot-Api-Secret-Token, en ik vergelijk dit met een constantetijdscontrole om timing-aanvallen te voorkomen. Als het geheim niet overeenkomt, wordt het verzoek onmiddellijk afgewezen.

Na verificatie inspecteert de handler welk type update het is.

• Tekstcommando's zoals /start, /help, /practice of /setkey worden gerouteerd naar hun respectievelijke handlers
• Spraakberichten activeren de volledige analyse-pipeline
• Callback-queries verwerken inline knopdrukken, zoals wanneer een gebruiker op "Details" tikt om hun resultaten uit te vouwen

De webhook retourneert altijd snel 200 OK. De daadwerkelijke verwerking gebeurt op de achtergrond, zodat Telegram niet time-out wacht op een antwoord.

Van spraakbericht naar prosodie-scores

Wanneer een gebruiker een spraakbericht stuurt, doorloopt de backend verschillende stappen.

1. Downloadt de audio van de servers van Telegram met behulp van de bestands-ID uit de webhook-payload
2. Converteert deze van OGG/Opus (standaard van Telegram) naar WAV op 16kHz mono met behulp van pydub en ffmpeg
3. Voert prosodie-analyse uit met Parselmouth (een Python-wrapper rond Praat) over vijf dimensies, waaronder toonhoogtebereik in halve tonen, volumebewegingen, spreektempo, ritmepatronen (nPVI) en pauze-verdeling
4. Genereert AI-coaching door de audio naar Google Gemini te sturen voor transcriptie en uitspraaktips
5. Formatteert en verzendt een compact antwoord terug via de Telegram Bot API

Elke dimensie krijgt een score van 1 tot 10 en deze worden gecombineerd tot een gewogen totale score met toonhoogte op 25%, volume en tempo elk op 20%, ritme op 20% en pauzes op 15%. De gebruiker krijgt een korte samenvatting met hun belangrijkste probleem en één bruikbare tip, plus een "Details"-knop die ze kunnen aanraken om de volledige uitsplitsing te zien.

Twee paden, één authenticatiesysteem

De backend ondersteunt twee authenticatiemethoden.

Firebase ID-tokens zijn wat de web-app gebruikt. De frontend stuurt een Bearer-token in de Authorization-header, de backend verifieert dit met de Firebase Admin SDK en de gebruiker krijgt volledige toegang tot zijn geschiedenis, voortgang en AI-coaching.

API-sleutels zijn wat de Telegram-bot gebruikt. Wanneer een gebruiker een API-sleutel aanmaakt via de web-app, genereert de backend een willekeurige sleutel, toont deze één keer en slaat alleen de SHA-256-hash ervan op in Firestore. De sleutel wordt verzonden in een X-Acento-Key header. Elke sleutel heeft een configureerbare dagelijkse limiet om misbruik te voorkomen.

Maar Telegram-gebruikers sturen geen HTTP-headers. Ze sturen gewoon spraakberichten. Dus ik had een manier nodig om een Telegram-chat te koppelen aan een Acento-account.

Telegram koppelen aan je account

Het commando /setkey overbrugt de kloof. Een gebruiker typt /setkey acento_xxxxx in de botchat. De backend verwijdert dat bericht onmiddellijk (zodat de sleutel niet in de chatgeschiedenis blijft staan), hasht de sleutel, zoekt deze op in de api_keys-collectie, en als deze overeenkomt, maakt het een telegram_links-document aan dat hun Telegram-chat-ID koppelt aan hun Acento-gebruikers-ID en API-sleutel.

Vanaf dat moment wordt elk spraakbericht uit die chat automatisch aan hun account gekoppeld. De backend controleert hun API-sleutellimiet, slaat analysesessies op in Firestore en houdt hun oefenreeks bij.

Gebruikers die nog geen account hebben gekoppeld, kunnen de bot nog steeds gebruiken. Ze krijgen prosodie-analyse (geen AI-coaching) met een limiet van 10 analyses per dag, bijgehouden op chat-ID in een aparte telegram_anon_usage-collectie.

Dagelijkse herinneringen en reeksen

Zodra een gebruiker is gekoppeld, kunnen ze zich aanmelden voor dagelijkse oefenherinneringen. Een Cloud Scheduler-taak raakt elk uur POST /api/telegram/send-reminders aan met een geheime header. De backend controleert welke gebruikers herinneringen hebben ingeschakeld voor dat uur en stuurt hen een bericht met een oefenzin.

Het herinneringsbericht past zich aan de context aan. Als je een actieve reeks hebt en gisteren hebt gemist, krijg je een "breek je reeks niet"-duwtje. Als je drie dagen of langer inactief bent geweest, is het een mildere heractiveringsprompt. De reeks zelf telt op wanneer je op opeenvolgende dagen oefent en wordt gereset als je er een overslaat.

Alles samenvoegen

De volledige stroom ziet er als volgt uit.

Geen app store, geen aanmeldformulier, geen laadschermen. Open gewoon Telegram, neem je stem op en krijg binnen enkele seconden feedback. De architectuur houdt de dingen eenvoudig. Eén webhook-endpoint, één analyse-pipeline en een lichtgewicht koppelingsmechanisme dat de wereld van Telegram verbindt met de rest van het systeem.

Als je het zelf wilt proberen, ga dan naar accent.learnenglishsounds.com en neem iets op. Of open gewoon de bot op Telegram en stuur een spraakbericht. Het is gratis om te beginnen, geen account vereist.