Cómo conecté un bot de Telegram a mi backend para análisis de prosodia en tiempo real

He estado construyendo Acento, una herramienta de entrenamiento de pronunciación que analiza cómo hablas inglés. Comenzó como una aplicación web, pero la forma más natural de practicar la conversación es simplemente enviar un mensaje de voz. Así que conecté el backend a un bot de Telegram. Grabas, analiza, recibes comentarios. Sin aplicación que instalar, sin interfaz de usuario que navegar.

Así es como encajan las piezas, desde el webhook y la API hasta la canalización de audio y la capa de autorización que vincula a los usuarios de Telegram con cuentas reales.

La API, FastAPI en Cloud Run

El backend es una aplicación FastAPI desplegada en Google Cloud Run. Expone algunos endpoints clave, pero dos son los más importantes.

• POST /api/analyze, el endpoint principal de análisis utilizado por la aplicación web
• POST /api/telegram/webhook, donde Telegram envía cada mensaje que recibe el bot

Cloud Run gestiona el escalado automáticamente. Cuando nadie envía mensajes de voz a las 3 AM, escala a cero. Cuando una docena de personas están practicando durante el almuerzo, inicia más instancias. El backend no tiene estado, así que eso funciona bien.

El bot de Telegram en sí está registrado a través de BotFather, y configuré la URL del webhook para que apunte a mi servicio de Cloud Run. A partir de ese momento, cada mensaje, nota de voz o pulsación de botón que ocurre en el chat del bot se reenvía a mi endpoint como una carga útil JSON.

Recepción y enrutamiento de actualizaciones de Telegram

Cuando Telegram alcanza el endpoint del webhook, lo primero que hace el backend es verificar la solicitud. Telegram envía un token secreto en la cabecera X-Telegram-Bot-Api-Secret-Token, y lo comparo usando una comprobación de tiempo constante para prevenir ataques de temporización. Si el secreto no coincide, la solicitud se rechaza inmediatamente.

Después de la verificación, el manejador inspecciona qué tipo de actualización es.

• Comandos de texto como /start, /help, /practice o /setkey se enrutan a sus respectivos manejadores
• Los mensajes de voz activan la canalización de análisis completa
• Las consultas de devolución de llamada (callback queries) manejan las pulsaciones de botones en línea, como cuando un usuario toca "Detalles" para expandir sus resultados

El webhook siempre devuelve 200 OK rápidamente. El procesamiento real ocurre en segundo plano para que Telegram no agote el tiempo de espera esperando una respuesta.

De mensaje de voz a puntuaciones de prosodia

Cuando un usuario envía un mensaje de voz, el backend pasa por varios pasos.

1. Descarga el audio de los servidores de Telegram usando el ID de archivo de la carga útil del webhook
2. Lo convierte de OGG/Opus (el predeterminado de Telegram) a WAV a 16kHz mono usando pydub y ffmpeg
3. Ejecuta el análisis de prosodia con Parselmouth (un wrapper de Python para Praat) en cinco dimensiones, incluyendo el rango de tono en semitonos, la dinámica de volumen, el tempo de habla, los patrones de ritmo (nPVI) y la distribución de pausas
4. Genera entrenamiento con IA enviando el audio a Google Gemini para transcripción y consejos de pronunciación
5. Formatea y envía una respuesta compacta a través de la API del Bot de Telegram

Cada dimensión recibe una puntuación del 1 al 10, y se combinan en una puntuación general ponderada con el tono en un 25%, el volumen y el tempo en un 20% cada uno, el ritmo en un 20% y las pausas en un 15%. El usuario recibe un resumen rápido con su principal problema y un consejo práctico, además de un botón de "Detalles" que puede pulsar para ver el desglose completo.

Dos caminos, un sistema de autenticación

El backend admite dos métodos de autenticación.

Los tokens de ID de Firebase son lo que utiliza la aplicación web. El frontend envía un token Bearer en la cabecera Authorization, el backend lo verifica con Firebase Admin SDK, y el usuario obtiene acceso completo a su historial, progreso y entrenamiento con IA.

Las claves API son lo que utiliza el bot de Telegram. Cuando un usuario crea una clave API a través de la aplicación web, el backend genera una clave aleatoria, la muestra una vez y almacena solo su hash SHA-256 en Firestore. La clave se envía en una cabecera X-Acento-Key. Cada clave tiene un límite diario configurable para prevenir el abuso.

Pero los usuarios de Telegram no envían cabeceras HTTP. Simplemente envían mensajes de voz. Así que necesitaba una forma de vincular un chat de Telegram con una cuenta de Acento.

Vinculación de Telegram con tu cuenta

El comando /setkey cierra la brecha. Un usuario escribe /setkey acento_xxxxx en el chat del bot. El backend elimina inmediatamente ese mensaje (para que la clave no quede en el historial del chat), hashea la clave, la busca en la colección api_keys y, si coincide, crea un documento telegram_links que mapea su ID de chat de Telegram con su ID de usuario de Acento y clave API.

A partir de entonces, cada mensaje de voz de ese chat se asocia automáticamente a su cuenta. El backend comprueba la cuota de su clave API, guarda las sesiones de análisis en Firestore y realiza un seguimiento de su racha de práctica.

Los usuarios que no han vinculado una cuenta aún pueden usar el bot. Obtienen análisis de prosodia (sin entrenamiento con IA) con un límite de 10 análisis por día, rastreados por ID de chat en una colección separada telegram_anon_usage.

Recordatorios diarios y rachas

Una vez que un usuario está vinculado, puede optar por recibir recordatorios diarios de práctica. Un trabajo de Cloud Scheduler golpea POST /api/telegram/send-reminders cada hora con una cabecera secreta. El backend comprueba qué usuarios tienen activados los recordatorios para esa hora y les envía un mensaje con una frase de práctica.

El mensaje de recordatorio se adapta al contexto. Si tienes una racha activa y te perdiste el día anterior, recibirás un toque de atención de "no rompas tu racha". Si has estado inactivo durante tres o más días, es una indicación de reactivación más suave. La racha en sí se incrementa cuando practicas en días consecutivos y se reinicia si te saltas uno.

Juntándolo todo

El flujo completo se ve así.

Sin tienda de aplicaciones, sin formulario de registro, sin pantallas de carga. Simplemente abre Telegram, graba tu voz y obtén comentarios en segundos. La arquitectura mantiene las cosas simples. Un endpoint de webhook, una canalización de análisis y un mecanismo de vinculación ligero que une el mundo de Telegram con el resto del sistema.

Si quieres probarlo tú mismo, visita accent.learnenglishsounds.com y graba algo. O simplemente abre el bot en Telegram y envía un mensaje de voz. Es gratis para empezar, no se requiere cuenta.