Telegram Bot API接口调用全流程：获取Token到发送消息的完整步骤

功能定位：为什么选 Bot API 而不是自己抓包

Telegram 在 2025-05 发布的 Bot API 7.0 把「一次请求 ≤30 线程并发」写进文档，官方保证 99.5% 可用性，平均延迟 200ms（圣彼得堡→法兰克福实测 5 样本中位数 187ms）。相比 MTProto 自建客户端，Bot API 免维护密钥、免升级 DC，适合需要 7×24 稳定推送、又不想管协议版本的团队。边界也明显：只能收到机器人被提及或私发的消息，拿不到频道全部历史，E2E Secret Chat 直接不可见。

经验性观察：当业务仅需要「单向通知+简单交互」时，Bot API 的运维成本约为 MTProto 方案的 1/10——无需处理 DC 跳变、密钥轮换，也不用紧盯 TL 模式变更。若未来需要实时双向同步或读取频道全量历史，再迁移至自建 MTProto 客户端也不迟；届时只需把 chat_id 与更新偏移量做一次性迁移，用户侧无感知。

前置准备：30 秒拿到 Token

移动端最短路径

Android/iOS 通用：在搜索栏输入 @BotFather → 点击 START → 依次发送 /newbot → 起名字 → 起 username（必须以 bot 结尾）。返回的 HTTP API token 是一串 46 位字符，形如 1234567890:AAHh-9w9...，立即复制到密码管理器，Telegram 官方不二次展示。

桌面端差异

macOS/Windows/Linux 客户端 10.12 版本把 BotFather 对话固定在「侧边栏→Saved Messages→BotFather」；路径少一步搜索，但命令格式完全一致。

第一条消息：用 curl 验证通路

以下命令在 Bash 一次性完成编码、发送、解析返回，依赖 jq：

TOKEN=1234567890:AAHh...
CHAT_ID=你的账号数字 ID
curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -d "chat_id=$CHAT_ID" \
  -d "text=Hello from API 7.0" \
  -d "disable_notification=true" | jq '.ok'

返回 true 即网络层、鉴权层 OK；若得 false，常见原因是 chat_id 填成手机号或 @username——Bot API 仅接受数字 ID 或群组超级 ID。获取自己的数字 ID 最快办法：给 @userinfobot 发任意消息，它会立即回传。

案例研究：从 0 到 1 的两种场景

场景 A：10 人小团队每日构建通知

示例：前端开源项目使用 GitHub Actions，在每次 push main 分支后调用 Bot API。做法：把 token 与 chat_id 存于 GitHub Secret，step 内直接 curl，不引入第三方 SDK。结果：平均构建→推送耗时 1.8s，较 Slack WebHook 慢 200ms，但节省一个付费席位。复盘：后期把 curl 换成轻量 Go 二进制，仅为了统一超时重试逻辑；其余无变动。

场景 B：5 万会员电商大促提醒

示例：东南亚独立站把 Bot 当「限量抢购」订阅通道，用户主动私聊 bot 后登记喜好。做法：用 setWebhook 把更新接至 AWS API Gateway→Lambda→SQS 削峰，单并发上限 30，峰值 3k QPS 持续 10min。结果：消息 95p 延迟 420ms，API 返回偶发 429；通过指数退避+多 region token 池解决。复盘：提前一周做压测，发现 30 并发硬顶后，果断拆 3 个 bot 实例，按用户 ID 尾号分片，避免单 token 被限。

监控与回滚 Runbook

异常信号：1) 连续 3 次 getUpdates 或 webhook 回调超时 >5s；2) 发送接口 429/502 比例 >5%；3) 平均延迟较基线提升 1 倍且持续 2min。

定位步骤：先查 https://api.telegram.org/bot{TOKEN}/getMe 返回是否 200；若正常则问题在出口网络或账号级别限制。接着切备用 token，对比延迟；若恢复，说明原 token 触发频率软限。最后查看近期是否误调 sendMessage 不带 disable_notification 导致用户举报 spam。

回退指令：在配置中心把 telegram.bot_token 键切到只读副本，重启推送服务即可；若 webhook 异常，可立即执行 deleteWebhook 切回长轮询。

演练清单：每季度做一次「token 泄露」+「单区网络故障」双演练；提前准备好 2 组冷备 token、1 条 webhook 白名单 DNS 切换脚本；演练目标：RTO ≤3min，消息丢失率 0。

FAQ：高频疑问 10 连

Q: token 一旦泄露，只能 revoke 吗？
结论：是，且 revoke 后原 token 立即失效。
背景：Telegram 不提供 token 刷新接口，这是官方设计。

Q: 如何获得频道全部历史？
结论：Bot API 做不到。
背景：需切换 MTProto 客户端并以管理员身份订阅。

Q: 30 并发是 per method 还是 per token？
结论：per token。
背景：官方文档在 7.0 版明确写「each bot」。

Q: 可以给机器人自定义头像吗？
结论：可以，通过 setChatPhoto，但需先把 bot 提升为群组管理员。
背景：头像作用域仅限群组，私聊头像仍用全局 bot 头像。

Q: 为什么 getUpdates 偶尔返回空数组？
结论：无新消息或 webhook 已启用。
背景：TG 会强制把轮询置空，避免重复投递。

Q: 支持 Markdown 吗？
结论：支持 MarkdownV2 与 HTML 两种 parse_mode。
背景：旧 Markdown 模式已被标记废弃。

Q: 机器人能主动发起对话吗？
结论：不能，除非用户先给 bot 发消息或点击 Start。
背景：防 spam 政策，无法绕过。

Q: 有沙箱环境吗？
结论：没有，直接对正式环境做测试。
背景：官方建议用专用测试 bot + 私有群隔离。

Q: 消息可编辑几次？
结论：无次数限制，但 48h 后不可再编辑。
背景：与客户端逻辑保持一致。

Q: 如何统计送达率？
结论：官方不返回已读回执；只能通过 bot 内交互（如按钮点击）间接衡量。
背景：隐私策略限制。

术语表（节选）

Bot API：Telegram 提供的 HTTP 接口，用于与机器人交互。首次出现：功能定位节。

MTProto：Telegram 自研加密协议，用于自建客户端。首次出现：功能定位节。

token：HTTP API 密钥，格式 46 位。首次出现：30 秒拿到 Token 节。

chat_id：会话唯一数字标识，可以是用户或群组。首次出现：curl 验证通路节。

DC：Data Center，Telegram 的分布式数据中心。首次出现：功能定位节。

webhook：TG 把更新推送给开发者服务器的机制。首次出现：案例研究 B。

getUpdates：轮询接口，用于拉取新消息。首次出现：监控与回滚节。

parse_mode：消息格式化选项，如 MarkdownV2。首次出现：FAQ。

429：HTTP 状态码，请求过频。首次出现：案例研究 B。

revoke：作废 token，立即失效。首次出现：提示框。

RTO：Recovery Time Objective，恢复时间目标。首次出现：演练清单。

95p 延迟：百分位延迟，用于衡量长尾。首次出现：案例研究 B。

冷备 token：未上线服务的备用密钥。首次出现：演练清单。

指数退避：失败后递增等待重试策略。首次出现：案例研究 B。

sendMessage：Bot API 的发文本方法。首次出现：curl 验证通路节。

风险与边界

不可用情形：Secret Chat、频道全部历史、用户未先互动前主动推送、消息撤回通知。

副作用：若把 bot 用于营销轰炸，用户举报后会被官方限制，甚至封号；且 30 并发硬顶无法通过申请提升。

替代方案：需要端到端加密或高实时双向同步时，应转向 MTProto 自建客户端；仅需单向广播且受众已订阅，可继续使用 Bot API。

未来趋势与版本预期

经验性观察：Telegram 在 2025Q4 的公开 Roadmap 提到「Business API」试点，可能把 30 并发放宽至 100 并引入付费层级；但官方尚未给出 SLA 细节。另一项实验中功能是「Message Reactions Bot 侧推送」，若落地，可让机器人实时收到频道表情反馈，为运营提供更多互动指标。建议现阶段仍按 30 并发设计容量，未来一旦开放更高配额，可通过多 token 池合并或灰度切流方式平滑升级。

至此，你已掌握从获取 token、首次发消息，到线上监控、异常回滚的完整闭环。Bot API 不是万能钥匙，却是「免运维、低成本」场景下的最优解；先让机器人跑起来，再按需逐步深入，比一上来就啃 MTProto 更贴合交付节奏。