Come ho collegato un bot Telegram al mio backend per l'analisi della prosodia in tempo reale

Sto costruendo Acento, uno strumento di coaching della pronuncia che analizza il modo in cui parli inglese. È iniziato come un'app web, ma il modo più naturale per esercitarsi a parlare è semplicemente inviare un messaggio vocale. Quindi ho collegato il backend a un bot di Telegram. Registri, analizza, ricevi feedback. Nessuna app da installare, nessuna interfaccia utente da navigare.

Ecco come i pezzi si incastrano, dal webhook e dall'API alla pipeline audio e allo strato di autorizzazione che collega gli utenti di Telegram agli account reali.

L'API, FastAPI su Cloud Run

Il backend è un'applicazione FastAPI distribuita su Google Cloud Run. Espone alcuni endpoint chiave, ma due sono i più importanti.

• POST /api/analyze, l'endpoint di analisi principale utilizzato dall'app web
• POST /api/telegram/webhook, dove Telegram invia ogni messaggio ricevuto dal bot

Cloud Run gestisce il ridimensionamento automaticamente. Quando nessuno invia messaggi vocali alle 3 del mattino, si riduce a zero. Quando una dozzina di persone si esercita durante la pausa pranzo, avvia più istanze. Il backend è stateless, quindi funziona bene.

Il bot di Telegram stesso è registrato tramite BotFather, e ho impostato l'URL del webhook in modo che punti al mio servizio Cloud Run. Da quel momento in poi, ogni messaggio, nota vocale o pressione di un pulsante che avviene nella chat del bot viene inoltrato al mio endpoint come payload JSON.

Ricezione e instradamento degli aggiornamenti di Telegram

Quando Telegram raggiunge l'endpoint del webhook, la prima cosa che fa il backend è verificare la richiesta. Telegram invia un token segreto nell'header X-Telegram-Bot-Api-Secret-Token, che confronto utilizzando un controllo a tempo costante per prevenire attacchi di temporizzazione. Se il segreto non corrisponde, la richiesta viene rifiutata immediatamente.

Dopo la verifica, l'handler ispeziona che tipo di aggiornamento è.

• I comandi di testo come /start, /help, /practice o /setkey vengono instradati ai rispettivi handler
• I messaggi vocali attivano l'intera pipeline di analisi
• Le query di callback gestiscono le pressioni dei pulsanti inline, come quando un utente tocca "Dettagli" per espandere i propri risultati

Il webhook restituisce sempre 200 OK rapidamente. L'elaborazione effettiva avviene in background in modo che Telegram non vada in timeout in attesa di una risposta.

Da messaggio vocale a punteggi di prosodia

Quando un utente invia un messaggio vocale, il backend esegue diversi passaggi.

1. Scarica l'audio dai server di Telegram utilizzando l'ID del file nel payload del webhook
2. Lo converte da OGG/Opus (il predefinito di Telegram) a WAV a 16kHz mono utilizzando pydub e ffmpeg
3. Esegue l'analisi della prosodia con Parselmouth (un wrapper Python attorno a Praat) su cinque dimensioni, inclusa l'estensione del tono in semitoni, la dinamica del volume, il ritmo di eloquio, i modelli ritmici (nPVI) e la distribuzione delle pause
4. Genera il coaching AI inviando l'audio a Google Gemini per la trascrizione e i suggerimenti sulla pronuncia
5. Formatta e invia una risposta compatta tramite l'API del bot di Telegram

Ogni dimensione riceve un punteggio da 1 a 10 e sono combinati in un punteggio complessivo ponderato con il tono al 25%, il volume e il ritmo al 20% ciascuno, il ritmo al 20% e le pause al 15%. L'utente riceve un rapido riepilogo con il suo problema principale e un suggerimento pratico, oltre a un pulsante "Dettagli" che può toccare per vedere la ripartizione completa.

Due percorsi, un sistema di autenticazione

Il backend supporta due metodi di autenticazione.

I token ID di Firebase sono ciò che utilizza l'app web. Il frontend invia un token Bearer nell'header Authorization, il backend lo verifica con Firebase Admin SDK e l'utente ottiene pieno accesso alla propria cronologia, ai progressi e al coaching AI.

Le chiavi API sono ciò che utilizza il bot di Telegram. Quando un utente crea una chiave API tramite l'app web, il backend genera una chiave casuale, la mostra una volta e memorizza solo il suo hash SHA-256 in Firestore. La chiave viene inviata in un header X-Acento-Key. Ogni chiave ha un limite giornaliero configurabile per prevenire abusi.

Ma gli utenti di Telegram non inviano header HTTP. Inviando semplicemente messaggi vocali. Quindi avevo bisogno di un modo per collegare una chat di Telegram a un account Acento.

Collegare Telegram al tuo account

Il comando /setkey colma il divario. Un utente digita /setkey acento_xxxxx nella chat del bot. Il backend elimina immediatamente quel messaggio (in modo che la chiave non rimanga nella cronologia della chat), esegue l'hash della chiave, la cerca nella raccolta api_keys e, se corrisponde, crea un documento telegram_links che mappa il proprio ID chat di Telegram al proprio ID utente Acento e alla chiave API.

Dopodiché, ogni messaggio vocale proveniente da quella chat viene automaticamente associato al proprio account. Il backend controlla la quota della chiave API, salva le sessioni di analisi in Firestore e tiene traccia della propria serie di esercizi.

Gli utenti che non hanno collegato un account possono comunque utilizzare il bot. Ottengono l'analisi della prosodia (nessun coaching AI) con un limite di 10 analisi al giorno, tracciate tramite l'ID della chat in una raccolta separata telegram_anon_usage.

Promemoria giornalieri e serie di esercizi

Una volta che un utente è collegato, può scegliere di ricevere promemoria di pratica giornalieri. Un job di Cloud Scheduler esegue POST /api/telegram/send-reminders ogni ora con un header segreto. Il backend controlla quali utenti hanno i promemoria attivi per quell'ora e invia loro un messaggio con una frase di pratica.

Il messaggio di promemoria si adatta al contesto. Se hai una serie attiva e hai saltato ieri, ricevi un sollecito per "non interrompere la tua serie". Se sei stato inattivo per tre o più giorni, è un invito al rientro più gentile. La serie stessa si incrementa quando ti eserciti in giorni consecutivi e si resetta se ne salti uno.

Mettendo tutto insieme

Il flusso completo è il seguente.

Nessun app store, nessun modulo di registrazione, nessun schermo di caricamento. Basta aprire Telegram, registrare la voce e ricevere un feedback in pochi secondi. L'architettura mantiene le cose semplici. Un endpoint webhook, una pipeline di analisi e un meccanismo di collegamento leggero che collega il mondo di Telegram al resto del sistema.

Se vuoi provarlo tu stesso, vai su accent.learnenglishsounds.com e registra qualcosa. Oppure apri semplicemente il bot su Telegram e invia un messaggio vocale. È gratuito per iniziare, nessun account richiesto.