我如何将 Telegram 机器人连接到我的后端以进行实时韵律分析
我一直在构建 Acento，一个分析你说英语方式的发音辅导工具。它最初是一个 Web 应用，但练习口语最自然的方式就是直接发送语音消息。所以我将后端连接到了一个 Telegram 机器人。你录音，它分析，你得到反馈。无需安装应用，无需浏览用户界面。
以下是各个组件如何协同工作的方式，从 webhook 和 API 到音频管道和将 Telegram 用户与真实账户关联起来的授权层。
API，Cloud Run 上的 FastAPI
后端是一个部署在 Google Cloud Run 上的 FastAPI 应用。它暴露了几个关键的端点，但其中两个最重要。
POST /api/analyze，Web 应用使用的主要分析端点POST /api/telegram/webhook，Telegram 将机器人收到的每条消息发送到此端点
Cloud Run 自动处理扩展。当凌晨 3 点没有人发送语音消息时，它会缩减到零。当午休时间有十几个人在练习时，它会启动更多实例。后端是无状态的，所以这很有效。
Telegram 机器人本身是通过 BotFather 注册的，我将 webhook URL 设置为指向我的 Cloud Run 服务。从那时起，机器人的聊天中发生的每条消息、语音或按钮点击都会作为 JSON 有效载荷转发到我的端点。
接收和路由 Telegram 更新
当 Telegram 命中 webhook 端点时，后端首先要做的是验证请求。Telegram 在 X-Telegram-Bot-Api-Secret-Token 标头中发送一个密钥令牌，我使用恒定时间检查来比较它，以防止时序攻击。如果密钥不匹配，请求会立即被拒绝。
验证后，处理程序会检查它是哪种类型的更新。
- 文本命令，如
/start、/help、/practice或/setkey，会被路由到各自的处理程序 - 语音消息会触发完整的分析管道
- 回调查询处理内联按钮点击，例如当用户点击“详情”以展开其结果时
Webhook 总是会快速返回 200 OK。实际处理在后台进行，这样 Telegram 不会因为等待响应而超时。
从语音消息到韵律得分
当用户发送语音消息时，后端会经过几个步骤。
- 使用 webhook 有效载荷中的文件 ID 从 Telegram 服务器下载音频
- 使用 pydub 和 ffmpeg 将其从 OGG/Opus（Telegram 的默认格式）转换为 16kHz 单声道的 WAV 格式
- 使用 Parselmouth（Praat 的 Python 包装器）对五个维度进行韵律分析，包括半音调的音高范围、音量动态、语速、节奏模式 (nPVI) 和停顿分布
- 通过将音频发送到 Google Gemini 来生成 AI 辅导，以获取转录和发音技巧
- 格式化并通过 Telegram Bot API 发送紧凑的响应
每个维度都会获得 1 到 10 的分数，并将它们组合成一个加权总分，其中音高占 25%，音量和语速各占 20%，节奏占 20%，停顿占 15%。用户会收到一个快速摘要，其中包含他们最主要的问题和一个可操作的提示，以及一个可以点击查看完整细分的“详情”按钮。
两条路径，一个授权系统
后端支持两种授权方法。
Firebase ID 令牌是 Web 应用使用的。前端在 Authorization 标头中发送一个 Bearer 令牌，后端使用 Firebase Admin SDK 验证它，用户即可完全访问其历史记录、进度和 AI 辅导。
API 密钥是 Telegram 机器人使用的。当用户通过 Web 应用创建 API 密钥时，后端会生成一个随机密钥，仅显示一次，并将该密钥的 SHA-256 哈希值存储在 Firestore 中。该密钥通过 X-Acento-Key 标头发送。每个密钥都有一个可配置的每日限制，以防止滥用。
但是 Telegram 用户不发送 HTTP 标头。他们只是发送语音消息。因此，我需要一种方法将 Telegram 聊天与 Acento 账户关联起来。
将 Telegram 与您的账户关联
/setkey 命令弥合了差距。用户在机器人聊天中输入 /setkey acento_xxxxx。后端会立即删除该消息（这样密钥就不会留在聊天记录中），对密钥进行哈希处理，在 api_keys 集合中查找它，如果匹配，则创建一个 telegram_links 文档，将他们的 Telegram 聊天 ID 映射到他们的 Acento 用户 ID 和 API 密钥。
从那时起，来自该聊天的每条语音消息都会自动与他们的账户相关联。后端会检查他们的 API 密钥配额，将分析会话保存到 Firestore，并跟踪他们的练习连胜。
尚未关联账户的用户仍然可以使用该机器人。他们可以获得韵律分析（没有 AI 辅导），每天最多 10 次分析，使用单独的 telegram_anon_usage 集合按聊天 ID 跟踪。
每日提醒和连胜
一旦用户关联成功，他们可以选择接收每日练习提醒。一个 Cloud Scheduler 作业每小时向 POST /api/telegram/send-reminders 发送一个带有密钥标头的请求。后端会检查哪些用户在该小时启用了提醒，并向他们发送包含练习句子的消息。
提醒消息会根据上下文进行调整。如果你有一个活跃的连胜记录但错过了昨天，你会收到一个“不要打破你的连胜”的提醒。如果你已经有三天或更长时间没有活动，则会收到一个更温和的重新参与提示。如果你连续几天练习，连胜记录就会增加；如果你跳过一天，连胜记录就会重置。
整合
完整的流程如下所示。
没有应用商店，没有注册表单，没有加载屏幕。只需打开 Telegram，录制你的声音，几秒钟内就能得到反馈。架构保持简单。一个 webhook 端点，一个分析管道，以及一个轻量级的关联机制，它将 Telegram 的世界与系统的其余部分连接起来。
如果你想亲自尝试一下，请访问 accent.learnenglishsounds.com 并录制一些内容。或者直接在 Telegram 上打开 机器人并发送一条语音消息。入门是免费的，无需注册账户。