Telegram Bot 接入指南

两类凭据

botToken 用于访问 Telegram Bot API；secretToken 用于校验来信请求头 X-Telegram-Bot-Api-Secret-Token。两者用途不同。Console 接收 botToken 并由后端构造固定 Telegram API 地址，不支持自定义发送 URL。

配置与验收

1. 准备 Telegram Bot 及其 token，部署具有公开 HTTPS 回调地址的 Server。
2. 在 Console 创建 Telegram 账号、绑定用户组，填写 secretToken；需要发送回复时填写 botToken。
3. 在 Telegram Bot API 的 setWebhook 中，将 url 设为 Console 提供的回调地址，将 secret_token 设为同一个 secretToken。完整调用参数与限制以官方 API 文档为准。
4. 通过 getWebhookInfo 检查注册结果，再向 Bot 发送消息。确认有权坐席可以收到消息并发送文本回复。Telegram 回调不使用 GET challenge 握手。

轮换与故障定位

Webhook 配置错误时检查 HTTPS、回调路径和 secretToken 请求头是否被网关保留。发送失败时检查 botToken、Bot 是否有权向该 chat 发送消息，以及平台频控结果。相同 Bot ID 可以轮换 token；切换到其他 Bot 必须新建渠道账号，不能通过清空 token 绕过身份绑定。

参考

Telegram setWebhook ↗ · getWebhookInfo ↗ · DuDu 字段与身份约束 ↗。不要将真实 Bot token 写入仓库、截图或可公开访问的日志。