首页门户/Bot API 接入
Telegram Bot API 接入说明（以官方文档为准）
本页所有接口名、参数名与数值上限均转述自 core.telegram.org/bots/api 官方文档，核对日期 2026-10-19；不提供任何官方文档之外的「增强能力」描述。
口径声明：本页是第三方整理的中文导读，不是官方文档，也不替代官方文档。文档首页提供版本更新记录（Changelog），本页不复制其中的版本号，请以你打开官方页面时看到的为准。核对日期 2026-10-19。
开始之前的三件事
接入 Bot 的前置条件很少，但每一步都涉及凭据处理，值得先看清楚。
凭据与身份
机器人由官方提供的 BotFather 入口创建，创建后会得到一段 token 字符串。token 等同于机器人的调用凭据，一旦出现在前端代码、日志或截图中就应视为已泄露并立即重置（来源：官方文档关于 token 的说明）。
官方文档在 Bot API usage 章节提醒：如果使用自建服务端，可以把 API 请求路由到本机，从而不在公网暴露接口地址（来源：core.telegram.org/bots/api，2026-10-19 查阅）。
- token 只放在服务端环境变量中，不写进任何会被打包进前端的内容（依据：官方文档的调用方式示例）。
- 日志中不要打印完整请求体，一次误打印就可能暴露全部群组标识（场景：线上问题排查阶段）。
- 多人协作时用环境变量分发，而不是通过聊天工具互发（依据：通用凭据管理要求）。
接收更新的两条路径
官方文档给出了 2 种接收更新的方式，二者在同一时间只能使用一种。
| 参数 | 含义 | 文档写明的取值范围 | 使用建议 |
|---|---|---|---|
| offset | 确认游标 | 整数，需大于 0 | 按 update_id 递增去重 |
| limit | 单次返回上限 | 1 至 100 条 | 取较小值以降低内存占用 |
| timeout | 长轮询等待 | 0 至 50 秒 | 取接近上限减少请求次数 |
| allowed_updates | 订阅类型 | 类型名数组 | 只订阅用得上的类型 |
长轮询的注意点
长轮询的关键是把 timeout 参数用足。官方文档给出的 timeout 上限为 50 秒，这意味着一次请求最多挂起 50 秒，而不是无限等待（来源：core.telegram.org/bots/api 的 getUpdates 章节）。
offset 的用法是：把上一次收到的最大 update_id 加 1 后作为下一次请求的 offset，官方文档说明确认后的更新会被丢弃（来源：官方文档关于 offset 的说明）。这个参数一旦漏传，就会出现重复处理的问题。
Webhook 的注意点
官方文档写明 webhook 的 url 必须使用 HTTPS 协议，且端口只能是 443、80、88、8443 这 4 个之一（来源：core.telegram.org/bots/api 的 setWebhook 章节，2026-10-19 查阅）。
并发连接数由 max_connections 参数控制，文档给出的范围是 1 至 100（来源：官方文档）。设置 webhook 后应删除轮询逻辑，否则更新会在两条路径之间重复到达。
| 参数或方法 | 文档口径 | 踩坑点 |
|---|---|---|
| setWebhook 的 url | 必须为 HTTPS | 自签证书不可用 |
| 可用端口 | 4 个固定取值 | 自建端口需反代 |
| max_connections | 1 至 100 | 默认并发偏低 |
| deleteWebhook | 可丢弃积压更新 | 调用后确认状态 |
| getWebhookInfo | 返回当前配置 | 排查配置首选 |
发送侧：最容易超限的 5 个参数
下面 5 个上限是中文项目最常踩的边界，写在前面可以省掉大量调试时间。
| 参数 | 方法 | 上限 | 备注 |
|---|---|---|---|
| text | sendMessage | 4096 字符 | 与 caption 上限不同 |
| caption | sendPhoto 等 | 1024 字符 | 媒体说明单独计算 |
| items 数量 | sendMediaGroup | 2 至 10 个 | 少于 2 个不成立 |
| 缩略图体积 | sendDocument 的 thumb | 小于 200 KB | 宽高需不超过 320 |
| 下载体积 | getFile 返回文件 | 20 MB | 大文件需分片 |
格式化与解析
parse_mode 参数决定消息中的格式标记如何被解析，文档列出的取值包含 Markdown、MarkdownV2 与 HTML 3 种模式，切换模式会改变转义规则（来源：core.telegram.org/bots/api 的 Formatting options 章节）。
使用 HTML 模式时需要自行转义尖括号与 & 符号，否则会出现解析错误。中文项目常见的做法是先生成纯文本，再按需要叠加模式（场景：同一段文案要发到 2 种不同场景）。
对象模型速查
下面 12 个术语按官方文档的命名整理，用途是帮助中文读者快速对齐概念，定义以官方文档为准。
- Update
- 一次更新事件的容器对象，内部含 message、callback_query 等内容类型。
- Message
- 消息对象，包含 chat、text、caption 等字段。
- Chat
- 会话对象，可表示私聊、群组或频道。
- CallbackQuery
- 内联按钮被点击时产生的对象，需要在限定时间内回应。
- InlineQuery
- 用户在输入框输入后联机查询产生的对象。
- Inline keyboard
- 附着在消息下方的按钮组，通过 callback_data 回传内容。
- Webhook
- 由官方服务器主动推送到指定 HTTPS 地址的接入方式。
- Long polling
- 程序主动调用 getUpdates 拉取更新的接入方式。
- BotFather
- 官方提供的机器人创建与配置入口。
- Token
- 调用接口所需的凭据字符串，泄露后需立即重置。
- offset
- getUpdates 的去重游标，需按 update_id 递增传递。
- parse_mode
- 控制消息格式解析方式的参数，取值以官方文档为准。
更多通用名词
站内另有一份面向全部读者的术语对照表，把账号、会话、频道这类日常名词与开发者名词放在同一张表里，方便对照阅读。
错误处理与自查
接入出问题的时候，按下面 4 步排查，基本可以覆盖绝大多数情况。
- 确认凭据有效：token 是否被撤销，机器人是否仍在运行状态（依据：官方文档的凭据管理说明）。
- 确认路径互斥：设置过 webhook 之后，确认 getUpdates 是否已停止使用（来源：官方文档的互斥说明）。
- 确认参数范围：把报错信息里的参数名与表 1、表 3 逐项比对（依据：本文整理的文档数值）。
- 确认日志级别：临时打开调试输出只看 1 次请求，记录后立即关闭（场景：线上环境排查）。
本文提到的接口均为官方文档中公开定义的内容，本站不提供任何托管、代跑或代注册服务，也不代收 token。需要其他语言版本的完整文档时，请直接查阅官方文档页面。
三个数值最容易记混
把 3 个常被混用的数值放在一起对照，可以一次看清它们的适用边界（全部转述自官方文档，核对日期 2026-10-19）。
- 文本消息 4096 字符：这是在线聊天场景的上限，与普通账号发送文件的上限不是同一类指标（来源：core.telegram.org/bots/api 的 sendMessage 章节）。
- 等待时间 50 秒：这是长轮询挂起的上限，请求超时后程序需要自行重连（来源：官方文档的 getUpdates 章节）。
- 并发 100 条连接：这是 Webhook 场景下的并发上限，填得过高会在突发流量时放大服务端压力（来源：官方文档的 setWebhook 章节）。