Как я подключил Telegram-бота к своему бэкенду для анализа просодии в реальном времени

Я разрабатываю Acento — инструмент для тренировки произношения, который анализирует вашу речь на английском языке. Изначально это было веб-приложение, но самый естественный способ практиковать разговорную речь — просто отправлять голосовые сообщения. Поэтому я подключил бэкенд к боту в Telegram. Вы записываете, он анализирует, вы получаете обратную связь. Не нужно устанавливать приложение, не нужно разбираться в интерфейсе.

Вот как все части складываются вместе: от вебхука и API до конвейера обработки аудио и уровня авторизации, который связывает пользователей Telegram с реальными аккаунтами.

API на FastAPI в Cloud Run

Бэкенд представляет собой приложение на FastAPI, развернутое в Google Cloud Run. Оно предоставляет несколько ключевых конечных точек, но две из них наиболее важны.

• POST /api/analyze — основная конечная точка анализа, используемая веб-приложением
• POST /api/telegram/webhook — сюда Telegram отправляет каждое сообщение, полученное ботом

Cloud Run автоматически управляет масштабированием. Когда никто не отправляет голосовые сообщения в 3 часа ночи, он масштабируется до нуля. Когда дюжина человек практикуется во время обеда, он запускает больше экземпляров. Бэкенд не имеет состояния, поэтому это отлично работает.

Сам бот Telegram зарегистрирован через BotFather, и я настроил URL вебхука так, чтобы он указывал на мой сервис Cloud Run. С этого момента каждое сообщение, голосовая заметка или нажатие кнопки в боте перенаправляется на мою конечную точку в виде JSON-полезной нагрузки.

Прием и маршрутизация обновлений Telegram

Когда Telegram обращается к конечной точке вебхука, первое, что делает бэкенд, — это проверяет запрос. Telegram отправляет секретный токен в заголовке X-Telegram-Bot-Api-Secret-Token, и я сравниваю его с помощью константной проверки, чтобы предотвратить атаки по времени. Если секрет не совпадает, запрос немедленно отклоняется.

После проверки обработчик анализирует тип обновления.

• Текстовые команды, такие как /start, /help, /practice или /setkey, маршрутизируются к соответствующим обработчикам
• Голосовые сообщения запускают полный конвейер анализа
• Callback-запросы обрабатывают нажатия встроенных кнопок, например, когда пользователь нажимает «Подробности», чтобы просмотреть полные результаты

Вебхук всегда быстро возвращает 200 OK. Фактическая обработка происходит в фоновом режиме, чтобы Telegram не ждал ответа слишком долго.

От голосового сообщения до оценок просодии

Когда пользователь отправляет голосовое сообщение, бэкенд выполняет несколько шагов.

1. Загружает аудио с серверов Telegram, используя file ID из полезной нагрузки вебхука
2. Конвертирует его из OGG/Opus (формат по умолчанию в Telegram) в WAV с частотой 16 кГц в моно с помощью pydub и ffmpeg
3. Выполняет анализ просодии с помощью Parselmouth (обертка Python для Praat) по пяти параметрам, включая диапазон высоты тона в полутонах, динамику громкости, темп речи, паттерны ритма (nPVI) и распределение пауз
4. Генерирует советы от AI, отправляя аудио в Google Gemini для транскрипции и советов по произношению
5. Форматирует и отправляет компактный ответ обратно через Telegram Bot API

Каждый параметр получает оценку от 1 до 10, и они объединяются во взвешенную общую оценку: высота тона — 25%, громкость и темп — по 20% каждый, ритм — 20%, паузы — 15%. Пользователь получает краткую сводку с основной проблемой и одним практическим советом, а также кнопку «Подробности», которую можно нажать, чтобы увидеть полный разбор.

Два пути, одна система аутентификации

Бэкенд поддерживает два метода аутентификации.

Firebase ID tokens используются веб-приложением. Фронтенд отправляет токен Bearer в заголовке Authorization, бэкенд проверяет его с помощью Firebase Admin SDK, и пользователь получает полный доступ к своей истории, прогрессу и советам от AI.

API-ключи используются ботом Telegram. Когда пользователь создает API-ключ через веб-приложение, бэкенд генерирует случайный ключ, показывает его один раз и сохраняет только его SHA-256 хеш в Firestore. Ключ отправляется в заголовке X-Acento-Key. У каждого ключа есть настраиваемый дневной лимит для предотвращения злоупотреблений.

Но пользователи Telegram не отправляют HTTP-заголовки. Они просто отправляют голосовые сообщения. Поэтому мне нужен был способ связать чат Telegram с аккаунтом Acento.

Связывание Telegram с вашим аккаунтом

Команда /setkey устраняет этот разрыв. Пользователь вводит /setkey acento_xxxxx в чате бота. Бэкенд немедленно удаляет это сообщение (чтобы ключ не оставался в истории чата), хеширует ключ, ищет его в коллекции api_keys, и если он совпадает, создает документ telegram_links, который сопоставляет ID чата Telegram с ID пользователя Acento и API-ключом.

С этого момента каждое голосовое сообщение из этого чата автоматически привязывается к его аккаунту. Бэкенд проверяет квоту его API-ключа, сохраняет сеансы анализа в Firestore и отслеживает его серию практик.

Пользователи, не привязавшие аккаунт, все равно могут пользоваться ботом. Они получают анализ просодии (без советов от AI) с ограничением в 10 анализов в день, отслеживаемых по ID чата в отдельной коллекции telegram_anon_usage.

Ежедневные напоминания и серии

После привязки аккаунта пользователь может подписаться на ежедневные напоминания о практике. Задача Cloud Scheduler каждый час обращается к POST /api/telegram/send-reminders с секретным заголовком. Бэкенд проверяет, какие пользователи включили напоминания на этот час, и отправляет им сообщение с предложением для практики.

Напоминание адаптируется к контексту. Если у вас активна серия и вы пропустили вчерашний день, вы получите напоминание «не прерывайте серию». Если вы неактивны три дня или больше, это будет более мягкий призыв к возобновлению занятий. Сама серия увеличивается, когда вы практикуетесь в последовательные дни, и сбрасывается, если вы пропускаете день.

Сборка всего вместе

Полный процесс выглядит так.

Никаких магазинов приложений, никаких форм регистрации, никаких экранов загрузки. Просто откройте Telegram, запишите свой голос и получите обратную связь за считанные секунды. Архитектура поддерживает простоту. Один конечный вебхук, один конвейер анализа и легкий механизм привязки, который соединяет мир Telegram с остальной системой.

Если хотите попробовать сами, перейдите на accent.learnenglishsounds.com и что-нибудь запишите. Или просто откройте бота в Telegram и отправьте голосовое сообщение. Начало бесплатное, регистрация не требуется.