Comment j'ai connecté un bot Telegram à mon backend pour une analyse de prosodie en temps réel

Je construis Acento, un outil de coaching de prononciation qui analyse la façon dont vous parlez anglais. Cela a commencé comme une application web, mais la manière la plus naturelle de s'entraîner à parler est simplement d'envoyer un message vocal. J'ai donc connecté le backend à un bot Telegram. Vous enregistrez, il analyse, vous recevez un retour. Pas d'application à installer, pas d'interface utilisateur à naviguer.

Voici comment les pièces s'assemblent, du webhook et de l'API au pipeline audio et à la couche d'autorisation qui lie les utilisateurs Telegram aux comptes réels.

L'API, FastAPI sur Cloud Run

Le backend est une application FastAPI déployée sur Google Cloud Run. Elle expose quelques points de terminaison clés, mais deux sont les plus importants.

• POST /api/analyze, le point de terminaison d'analyse principal utilisé par l'application web
• POST /api/telegram/webhook, où Telegram envoie chaque message que le bot reçoit

Cloud Run gère la mise à l'échelle automatiquement. Lorsque personne n'envoie de messages vocaux à 3 heures du matin, il se met à l'échelle à zéro. Lorsque des dizaines de personnes s'entraînent pendant la pause déjeuner, il lance plus d'instances. Le backend est sans état, donc cela fonctionne bien.

Le bot Telegram lui-même est enregistré via BotFather, et j'ai configuré l'URL du webhook pour pointer vers mon service Cloud Run. À partir de ce moment, chaque message, note vocale ou pression de bouton qui se produit dans le chat du bot est transféré à mon point de terminaison sous forme de charge utile JSON.

Réception et routage des mises à jour Telegram

Lorsque Telegram atteint le point de terminaison du webhook, la première chose que fait le backend est de vérifier la requête. Telegram envoie un jeton secret dans l'en-tête X-Telegram-Bot-Api-Secret-Token, et je le compare à l'aide d'une vérification en temps constant pour prévenir les attaques par temporisation. Si le secret ne correspond pas, la requête est rejetée immédiatement.

Après vérification, le gestionnaire inspecte le type de mise à jour.

• Les commandes texte comme /start, /help, /practice ou /setkey sont acheminées vers leurs gestionnaires respectifs
• Les messages vocaux déclenchent le pipeline d'analyse complet
• Les requêtes de rappel (callback queries) gèrent les pressions sur les boutons en ligne, comme lorsqu'un utilisateur appuie sur « Détails » pour développer ses résultats

Le webhook retourne toujours 200 OK rapidement. Le traitement réel se fait en arrière-plan afin que Telegram ne subisse pas de délai d'attente en attendant une réponse.

Du message vocal aux scores de prosodie

Lorsqu'un utilisateur envoie un message vocal, le backend passe par plusieurs étapes.

1. Télécharge l'audio depuis les serveurs de Telegram en utilisant l'ID de fichier de la charge utile du webhook
2. Le convertit d'OGG/Opus (le format par défaut de Telegram) en WAV à 16 kHz mono à l'aide de pydub et ffmpeg
3. Exécute l'analyse de prosodie avec Parselmouth (un wrapper Python pour Praat) sur cinq dimensions, y compris la plage de hauteur en demi-tons, la dynamique du volume, le tempo de parole, les schémas rythmiques (nPVI) et la distribution des pauses
4. Génère le coaching IA en envoyant l'audio à Google Gemini pour la transcription et les conseils de prononciation
5. Formate et envoie une réponse compacte via l'API du bot Telegram

Chaque dimension reçoit un score de 1 à 10, et elles sont combinées en un score global pondéré avec la hauteur à 25 %, le volume et le tempo à 20 % chacun, le rythme à 20 % et les pauses à 15 %. L'utilisateur reçoit un résumé rapide avec son problème principal et un conseil pratique, ainsi qu'un bouton « Détails » qu'il peut appuyer pour voir la ventilation complète.

Deux chemins, un système d'authentification

Le backend prend en charge deux méthodes d'authentification.

Les jetons d'identification Firebase sont ce que l'application web utilise. Le frontend envoie un jeton Bearer dans l'en-tête Authorization, le backend le vérifie avec le SDK d'administration Firebase, et l'utilisateur obtient un accès complet à son historique, à ses progrès et à son coaching IA.

Les clés API sont ce que le bot Telegram utilise. Lorsqu'un utilisateur crée une clé API via l'application web, le backend génère une clé aléatoire, l'affiche une seule fois et ne stocke que son hachage SHA-256 dans Firestore. La clé est envoyée dans un en-tête X-Acento-Key. Chaque clé a une limite quotidienne configurable pour prévenir les abus.

Mais les utilisateurs Telegram n'envoient pas d'en-têtes HTTP. Ils envoient simplement des messages vocaux. J'avais donc besoin d'un moyen de lier un chat Telegram à un compte Acento.

Lier Telegram à votre compte

La commande /setkey comble le fossé. Un utilisateur tape /setkey acento_xxxxx dans le chat du bot. Le backend supprime immédiatement ce message (afin que la clé ne reste pas dans l'historique du chat), hache la clé, la recherche dans la collection api_keys, et si elle correspond, crée un document telegram_links qui mappe son ID de chat Telegram à son ID utilisateur Acento et à sa clé API.

À partir de là, chaque message vocal provenant de ce chat est automatiquement associé à son compte. Le backend vérifie le quota de sa clé API, enregistre les sessions d'analyse dans Firestore et suit sa série de pratiques (streak).

Les utilisateurs qui n'ont pas lié de compte peuvent toujours utiliser le bot. Ils bénéficient de l'analyse de prosodie (sans coaching IA) avec un plafond de 10 analyses par jour, suivi par l'ID de chat dans une collection séparée telegram_anon_usage.

Rappels quotidiens et séries

Une fois qu'un utilisateur est lié, il peut choisir de recevoir des rappels de pratique quotidiens. Un travail Cloud Scheduler appelle POST /api/telegram/send-reminders chaque heure avec un en-tête secret. Le backend vérifie quels utilisateurs ont activé les rappels pour cette heure et leur envoie un message avec une phrase d'entraînement.

Le message de rappel s'adapte au contexte. Si vous avez une série active et que vous avez manqué hier, vous recevez une piqûre de rappel de « ne pas casser votre série ». Si vous êtes inactif depuis trois jours ou plus, c'est une invite de réengagement plus douce. La série elle-même s'incrémente lorsque vous vous entraînez des jours consécutifs et se réinitialise si vous en sautez un.

Mise en place de l'ensemble

Le flux complet se présente comme suit.

Pas d'App Store, pas de formulaire d'inscription, pas d'écrans de chargement. Ouvrez simplement Telegram, enregistrez votre voix et obtenez un retour en quelques secondes. L'architecture maintient les choses simples. Un seul point de terminaison de webhook, un seul pipeline d'analyse et un mécanisme de liaison léger qui fait le pont entre le monde de Telegram et le reste du système.

Si vous souhaitez l'essayer vous-même, rendez-vous sur accent.learnenglishsounds.com et enregistrez quelque chose. Ou ouvrez simplement le bot sur Telegram et envoyez un message vocal. C'est gratuit pour commencer, aucun compte requis.