Guides
Telegram 访问令牌详解：Bot Token、API ID、API Hash 与会话字符串
Telegram 访问令牌：先弄清你真正需要哪种凭据
很多人搜索“Telegram 访问令牌”，仿佛 Telegram 会发放一把通用钥匙。事实并非如此。Telegram 有好几套身份验证体系，该用哪种凭据，取决于你的软件是在控制一个机器人、授权一个个人账号、让用户登录某个网站，还是重新连接一个已经授权过的客户端。
区分清楚很重要，因为这些凭据的权限各不相同。Bot Token 控制一个机器人。API ID 和 API Hash 用来识别一个开发者应用。登录验证码证明你暂时能访问某个手机号。会话字符串或会话文件可以保存一次已完成的个人账号授权，因此可能无需再次登录就能访问该账号。把这些值当作可以互换的东西，既是常见的实现错误，也是严重的安全隐患。
本指南会说明每种凭据的作用、来源以及如何安全地处理它。同时也会解释，为什么面向个人账号的 Telegram CRM 或 MCP 连接，与 Bot API 集成不是一回事。
快速对比
| 凭据 | 代表什么 | 常见来源 | 主要用途 | 敏感程度 |
|---|---|---|---|---|
| Bot Token | 一个 Telegram 机器人 | @BotFather |
调用 HTTP Bot API | 机密；持有者可以控制该机器人 |
| API ID | 一个 Telegram 开发者应用 | my.telegram.org |
识别 MTProto 客户端应用 | 单独使用并不足够 |
| API Hash | 与 API ID 配对的密钥 | my.telegram.org |
授权 MTProto 客户端应用 | 机密；绝不能公开 |
| 登录验证码 | 临时的账号验证码 | Telegram 服务消息或已授权的应用 | 完成个人账号登录 | 极其敏感，有效期很短 |
| 两步验证密码 | 额外的账号保护 | 由 Telegram 账号所有者设置 | 开启两步验证时完成登录 | 属于密码；绝不能交给第三方 |
| 会话字符串或会话文件 | 一个持久保存的已授权客户端会话 | 登录后由 MTProto 库生成 | 无需重走完整流程即可重新连接 | 极其敏感；可能代表一个有效的登录 |
| OAuth/OIDC 令牌 | 网站或应用的登录授权 | Telegram Login 流程 | 让用户登录另一个服务 | 取决于权限范围和有效期 |
如果某个教程让你提供“Telegram token”，先停下来，弄清它指的是表中哪一行，再复制任何东西。
Bot Token：属于机器人的凭据，而不是个人账号的
Telegram Bot Token 用于让机器人通过 Bot API 的身份验证。Telegram 的官方机器人教程指导开发者通过 @BotFather 创建机器人，通常使用 /newbot 命令。BotFather 会返回一个令牌，后端在调用 getMe、sendMessage 或 setWebhook 等方法时使用它。
Bot Token 通常由一串数字形式的机器人标识、一个冒号和一长串密钥组成。不要把真实的令牌粘贴到文档、截图、聊天消息、问题跟踪系统、客户端 JavaScript 或公开代码仓库中。Telegram 明确建议像对待密码一样对待这个令牌，因为任何持有它的人都能控制这个机器人。
Bot Token 有一个重要限制：它验证的是机器人的身份，而不是你个人的 Telegram 身份。机器人无法直接读取某个人现有的私人收件箱。Telegram 的机器人文档还说明，机器人不能主动向用户发起对话，必须由用户先联系机器人，或者把它拉进群组。在群组里，隐私设置还可能进一步限制机器人能收到哪些消息。
如果你要做的是机器人体验，就选择 Bot Token：命令、通知、菜单、客服接入、Mini App，或者用户明知自己在与机器人交互的自动化流程。
API ID 与 API Hash：属于 MTProto 应用的凭据
个人账号客户端使用的是 Telegram 的 MTProto API，而不只是依赖 HTTP Bot API。应用在能够授权 Telegram 用户之前，开发者需要先拿到 API ID 和 API Hash。
Telegram 的官方应用注册说明描述了这个流程：
- 使用一个已注册 Telegram 的有效手机号。
- 登录
my.telegram.org。 - 打开 API development tools。
- 注册应用。
- 妥善保存生成的
api_id和api_hash。
API ID 是数字形式的应用标识，API Hash 是与之配对的密钥。它们识别的是发起授权请求的软件，本身并不会让软件登录任何一个 Telegram 账号。用户授权流程仍然必不可少。
不要从随便某个 GitHub 项目或示例应用里复制 API 凭据。Telegram 提醒，其开源代码中的示例 API ID 是受限的，不适合面向用户发布的应用。生产环境的集成应使用注册在运营方组织名下的凭据，并遵守 Telegram 的 API 条款。
登录验证码与两步验证
当 MTProto 客户端授权个人账号时，Telegram 通常会通过现有的 Telegram 会话或其他受支持的渠道发送临时登录验证码。如果账号开启了两步验证，Telegram 还会要求输入该账号的额外密码。
这两者都不是开发者应该长期保存的 API 凭据。验证码只是临时证明：控制该账号的人同意这次登录。两步验证密码则是账号所有者的密码。一个正规的授权页面应当说明为什么需要这些值，安全地传输它们，并避免把它们记录到日志或分析系统中。
绝不要把 Telegram 登录验证码发给自称“客服”的人，也绝不要把它粘贴到与机器人的对话里。如果在登录流程之外有人向你索要验证码，这是账号被盗的强烈警示信号。
会话字符串与会话文件
授权成功后，MTProto 库通常会把会话持久保存下来。根据所用的库不同，会话可能存放在本地数据库文件、加密记录或一段可移植的字符串中。
有了会话，用户就不必在每次应用重启时重新输入登录验证码。正是这种便利让它高度敏感。一个有效的会话可能代表一台已经授权的设备，一旦泄露，其他人就可能在会话被撤销之前以该账号的身份行事。
请遵守以下规则：
- 绝不要把会话提交到 Git。
- 绝不要把会话放进浏览器代码或移动端分析数据里。
- 使用托管密钥对静态存储的会话加密，而不是把硬编码的密钥放在密文旁边。
- 生产环境的访问权限只授予尽可能少的服务角色。
- 在日志和错误报告中屏蔽会话内容。
- 提供清晰的方式来断开账号连接并删除已保存的会话。
- 如果会话泄露，在 Telegram 的设置 → 设备页面撤销它，并轮换相关的密钥。
会话字符串并不是更安全的 Bot Token。它是另一种凭据，潜在的访问范围可能更广。
Telegram Login 令牌是另一类凭据
Telegram 还支持通过 Telegram Login 登录网站和应用，其中包括 OpenID Connect 流程。这个流程让 Telegram 用户在另一个应用中完成身份验证，并返回经过签名的身份信息或有权限范围的令牌。它并不会自动授予读取用户个人 Telegram 收件箱的权限。
如果目标是“用 Telegram 登录我的服务”，就用 Telegram Login。如果要做机器人，就用 Bot API。只有当产品确实需要个人账号的能力，并且有清晰的授权同意和安全模型时，才使用经过授权的 MTProto 客户端。
MCP 连接使用的是哪种凭据？
MCP 描述的是 AI 客户端如何向服务器请求工具和操作。它并不能取代 Telegram 的身份验证。Telegram MCP 服务器背后仍然需要一个经过授权的 Telegram 层。
举例来说，Entergram 通过用户批准的授权流程把个人 Telegram 账号连接到工作空间。随后，托管的 Telegram MCP 服务器会向获得批准的 MCP 客户端开放一组定义好的 CRM 和消息工具。AI 客户端拿到的是工具访问权限，不应该拿到原始的 Telegram 登录验证码、API Hash 或可重复使用的账号会话。
这种分离是更安全的架构：
- Telegram 凭据留在负责 Telegram 授权的服务内部。
- MCP 服务器只开放范围明确的操作。
- 由 OAuth 和工作空间权限决定哪个人或哪个 AI 客户端可以调用这些操作。
- 审计日志记录业务操作，但不记录身份验证密钥。
- 撤销 MCP 客户端的访问时，用户不必暴露或轮换底层的每一个 Telegram 凭据。
两者在能力上的差异，请阅读 Telegram MCP 与 Bot API 对比。
安全实施检查清单
在上线任何 Telegram 集成之前，先回答下面这些问题：
身份与范围
- 这个集成是以机器人身份还是个人账号身份运行？
- 它实际需要访问哪些聊天、执行哪些操作？
- 用户能否排除私人对话或某些账号？
- 写入操作和只读操作是否分开？
密钥存储
- Bot Token、API Hash 和会话是否只存放在受信任的服务器上？
- 密钥在静态存储时是否加密，传输时是否受保护？
- 生产凭据是否排除在源码管理和预览部署之外？
- 日志、链路追踪系统和客服工具是否配置了屏蔽这些密钥？
授权与撤销
- 每个已连接的账号是否都有可识别的负责人？
- 管理员能否单独断开一个账号而不影响其他账号？
- 能否单独撤销某个 AI 客户端或某位员工的访问权限？
- 特权操作是否记录了操作者、时间、账号和结果？
事件响应
- 是否有成文的 Bot Token 轮换流程？
- 团队能否迅速让被盗的会话失效？
- 服务是否会对异常的登录地点或大批量操作发出警报？
- 备份是否加密，并且适用同样的删除策略？
常见错误
把所有凭据都叫作 token。 这会导致工程师把错误的值填进错误的字段，也让安全审查变得含糊。配置变量要命名准确：TELEGRAM_BOT_TOKEN、TELEGRAM_API_ID 和 TELEGRAM_API_HASH 比 TELEGRAM_TOKEN 清楚得多。
把 Bot Token 放进前端代码。 任何发送到浏览器的内容都应视为公开。Bot API 调用应通过受保护的后端转发。
以为 API ID 和 API Hash 就等于账号访问权。 它们识别的是应用，用户仍然需要授权账号。
把会话当成无害的缓存。 会话是身份验证材料，要像保护凭据一样保护它，并确保可以撤销。
索取超出流程所需的访问权限。 通知机器人不需要个人账号会话，报表流程可能也不需要发送消息的权限。从最小可行的设计开始。
实用结论
如果你想做一个 Telegram 机器人，就用 BotFather 创建它，并在后端使用它的 Bot Token。如果你在开发面向个人账号的授权 Telegram 客户端，就注册你自己的 API ID 和 API Hash，完成 Telegram 的用户授权流程，并保护好生成的会话。如果你只需要登录功能，就使用 Telegram Login，而不是申请收件箱访问权限。
对于希望让 AI 工具处理经过批准的个人 Telegram 账号的团队，一个带权限控制的 Telegram MCP 服务器可以避免把原始 Telegram 凭据交给每一个 AI 客户端。无论选择哪条路线，都不要让身份验证密钥出现在提示词、代码仓库、浏览器代码和截图中，并从第一天起就把撤销机制纳入设计。
