Telegram API 开发指南

Telegram 为机器人、第三方客户端和验证码发送场景提供不同的开发接口。开始开发前，应先根据项目用途选择 Bot API、Telegram API、TDLib 或 Gateway API，再阅读相应的官方文档、申请所需凭据并完成安全配置。

本站仅整理 Telegram API 的中文入门信息，并非 Telegram 官方开发文档。接口参数、功能限制和使用条款可能随时更新，实际开发请以 Telegram Core 官方文档为准。

Telegram 提供哪些 API？

不同 API 面向的使用场景并不相同。机器人通常使用 Bot API；需要开发完整客户端时，应了解 Telegram API 或 TDLib；需要向用户发送登录验证码的企业服务，则可以查看 Gateway API。

Bot API 是面向 Telegram 机器人的 HTTP 接口。开发者可以用它接收消息、发送内容、处理按钮、管理群组功能，以及接入小程序或支付能力。机器人账号通常通过 @BotFather 创建，并获得用于调用接口的机器人令牌。

机器人令牌相当于访问凭据，不应写入公开代码仓库、网页源码或前端 JavaScript。正式项目应把令牌保存在服务器环境变量或受保护的配置中，并在发现泄露后立即重新生成。

查看 Telegram 机器人开发说明 和 Bot API 方法文档。

Telegram API 面向需要实现账号授权、聊天同步、文件传输和完整客户端功能的开发者。它与 Bot API 的用途不同：Bot API 操作的是机器人账号，而 Telegram API 可用于构建面向普通用户账号的客户端应用。

开发者需要先在 Telegram 指定页面注册应用并获取 API ID 与 API Hash。这些凭据应按照官方要求使用，不得用于仿冒客户端、绕过平台限制或未经授权收集用户数据。

TDLib 是 Telegram 提供的跨平台客户端开发库。它封装了网络连接、本地数据处理、更新同步和部分加密实现，让开发者能够把更多精力放在界面、交互和业务功能上。

与直接实现 MTProto 相比，TDLib 更适合希望缩短客户端开发周期的团队。选择之前仍需确认目标平台、语言绑定、构建环境和许可证是否符合项目要求。

Gateway API 面向需要发送登录或验证代码的应用、网站和企业服务。验证码通过 Telegram 发送给符合条件的用户，可作为传统短信验证之外的一种选择。

接入前应确认服务覆盖范围、计费方式、发送条件和用户体验，并为未安装 Telegram、无法接收消息或网络异常的用户保留备用验证方式。

Bot API 使用机器人令牌；Telegram API 通常需要 API ID 和 API Hash；其他服务也可能要求单独的访问凭据。申请完成后，应区分测试与生产环境，并限制可以读取凭据的人员和服务器。

不要把令牌、API Hash、会话文件、登录验证码或两步验证密码提交到 GitHub，也不要通过聊天、截图或公开日志传递这些信息。

接口能够返回数据并不代表已经可以上线。开发者还应测试授权失效、网络中断、频率限制、重复更新、文件上传失败和数据中心迁移等情况。对可重试错误设置合理的等待时间，避免无限循环请求或在短时间内大量重试。

上线前应检查 Telegram 的 API 使用条款、隐私政策和品牌要求，说明应用会收集和处理哪些数据，并为用户提供退出登录、删除数据和联系支持的方式。第三方客户端还应明确自己的开发者身份，避免让用户误认为它是 Telegram 官方应用。

访问令牌、API Hash 和会话数据应只保存在受控环境中，并通过最小权限原则限制访问。日志系统应主动隐藏敏感字段，备份文件也需要加密和访问控制。怀疑泄露时，应立即撤销旧凭据、终止异常会话并检查访问记录。

客户端必须按照官方授权流程处理手机号码、验证码、二维码登录和两步验证。不应绕过安全提示，也不能把用户密码保存为明文。需要支持通行密钥或二维码登录时，应先阅读对应流程的最新文档。

Telegram 云端聊天与私密聊天采用不同的工作方式，不能把所有聊天笼统描述为端到端加密。如果客户端需要实现私密聊天、语音或视频通话，应严格遵循官方协议和安全检查，不要自行简化密钥验证步骤。

详细实现要求请查看 MTProto 安全指南和端到端加密文档。

只收集完成具体功能所必需的数据，并为数据设置明确的保存期限。如果使用第三方分析、云存储或错误监控服务，应在隐私说明中向用户披露，避免把聊天内容、联系人或身份凭据发送给不必要的第三方。