对比选型 July 19, 2026

Telegram API ID、API hash 与 bot token 有什么区别？该用哪种凭证？

Telegram API ID、API hash 与 bot token 有什么区别？bot token 用来让一个 bot 通过 HTTP Bot API 完成身份验证，不能登录个人 Telegram 账号。API ID 和 API hash 用于标识客户端应用；如果要通过 Telegram 的 MTProto API 授权用户账号，包括验证码或扫码登录，就必须提供这两个值。选择凭证时，先看你要控制的身份：bot 身份 → bot token；现有用户账号 → API ID 和 API hash。

关键结论

如果集成要作为独立的 Telegram bot 运行，请从 @BotFather 获取 bot token。
如果应用需要授权现有 Telegram 用户账号，请从 my.telegram.org 获取 API ID 和 API hash。
bot token 不能代替 API ID/API hash，扫码登录也不会免除应用凭证要求。
不要把 bot token、API hash、登录验证码或已授权的 session 数据写入源码仓库或日志。
在 UnifyPort 中连接普通 Telegram 账号时，请按照 Telegram 授权指南使用 API ID 和 API hash，不要把 BotFather token 填入该流程。

Telegram API ID、API hash 与 bot token 有什么区别？

这三个值都会授予某种 Telegram 访问能力，名称很容易混淆，但它们属于不同的 API，验证的身份也不同。

你要构建的功能	所需凭证	获取位置	授权后的身份
HTTP Bot API 集成	Bot token	`@BotFather`	一个独立的 bot 账号
登录 Telegram 用户的客户端	API ID + API hash，再完成验证码、扫码或其他受支持的用户登录步骤	`my.telegram.org` → API development tools	完成授权的用户账号
在 UnifyPort 中连接用户账号	API ID + API hash，用于验证码或扫码授权	`my.telegram.org`	批准登录的 Telegram 账号

Telegram 官方 bot 教程对此说得很明确：bot token 验证的是 bot，而不是你的账号。调用 https://api.telegram.org/bot<TOKEN>/getMe 等 endpoint 时需要携带该 token，也可以随时在 @BotFather 中撤销它。

API ID 和 API hash 则属于 Telegram 客户端应用。登录 my.telegram.org 并填写 API development tools 表单后，Telegram 才会签发这两个值。用户授权流程会把应用凭证与用户掌控的登录步骤结合起来。例如，auth.sendCode 需要手机号、api_id 和 api_hash；授权成功后，生成的客户端 session 会绑定到该用户。

最关键的区别就在这里：bot token 选定的是 bot 身份，API ID/API hash 标识的则是参与用户账号登录的客户端应用。

应该选择哪一种凭证？

先确认需要收发消息的究竟是哪一种身份。

可以使用 bot 身份时，选择 bot token

如果用户会主动与某个 bot 用户名聊天、把 bot 加入群组，或使用 bot 专属功能，就应选择官方 Bot API。通过 @BotFather 创建 bot，像保护密码一样保存 token，再通过轮询或 Telegram webhook 接收 Bot API update。

对于围绕 bot 设计、只服务 Telegram 的产品，这通常是最简洁的方案。bot 生命周期由 Telegram 管理，API 也是官方提供的，并且不需要授权个人用户 session。我们的《Telegram 原生聊天自动化与跨渠道入站队列对比》进一步说明了这一官方模式最适合哪些场景。

必须使用用户账号身份时，选择 API ID 和 API hash

如果产品必须授权现有 Telegram 账号，而不是创建新的 bot 身份，就需要走 Telegram 客户端 API 流程。应用先通过 API ID 和 API hash 标识自身，再由账号所有者完成用户登录，例如输入验证码、扫码确认，以及在已启用时完成 2FA。

不要把 API ID/API hash 本身理解为一个已登录账号。它们标识的是应用，只有用户完成授权后才会生成账号 session。同样，手机号或 QR code 也不能代替应用凭证。

如果最终目标是把现有 Telegram 账号的消息转入其他系统，可以参考《用 Cursor 构建 Telegram 到 Slack 消息转发》，了解账号连接完成后的下游 webhook 架构。

如何通过 my.telegram.org/auth 获取 API ID 和 API hash

Telegram 的官方流程并不长，但页面名称需要选对：

在 Telegram 官方应用中注册并保留一个有效手机号。
打开 my.telegram.org，在 /auth 完成账号登录。
选择 API development tools。
填写应用信息表单。
将获得的 api_id 和 api_hash 存入服务器端的凭证库。

Telegram 目前规定每个手机号只能申请一个 API ID，并明确提醒客户端库的滥用行为会受到监控。正式发布的应用应使用自己的应用凭证，遵守 Telegram API 服务条款，也不要把 Telegram 开源客户端中用途受限的示例 API ID 用于生产环境。

扫码登录仍然需要 API ID 和 API hash 吗？

需要。扫码改变的是用户批准登录的方式，不会改变发起请求的客户端应用。

Telegram 官方扫码流程从 auth.exportLoginToken 开始，该方法的参数中就包含 api_id 和 api_hash。客户端把返回的 token 渲染为 tg://login QR code，再由已经登录的 Telegram 应用扫码并确认。Telegram 说明该 login token 通常约 30 秒后过期，因此 QR code 过期后必须刷新。

所以，“该用 QR code 还是应用凭证”并不是正确的问题。授权用户账号时，QR code 是与应用凭证配合使用的一种批准方式。

UnifyPort 在这个流程中的位置

UnifyPort 通过非官方接口连接普通 Telegram 账号，不会创建 Telegram bot。因此，它的验证码和扫码授权都采用用户账号凭证流程。

使用验证码授权时，请以 provider: "telegram"、auth_mode: "code" 和以下真实字段创建账号：

{
  "provider": "telegram",
  "auth_mode": "code",
  "provider_data": {
    "api_id": 12345678,
    "api_hash": "0123456789abcdef0123456789abcdef",
    "phone": "+886912345678"
  }
}

使用扫码授权时，仍然必须提供 provider_data.api_id 和 provider_data.api_hash，再由账号所有者在 Telegram 中批准短时有效的 QR code。Telegram 授权 API 参考列出了验证码、扫码、2FA 和 session 的完整步骤。

授权完成后，Telegram 入站消息可以像其他已连接渠道一样，以签名的 message.received 事件送达。普通账号授权流程不会接收 BotFather token 作为输入。

限制与取舍

如果独立 bot 身份能够满足产品需求，请使用 Telegram 官方 Bot API。它专为 bot 而设计，也不需要维护用户账号 session。

只有确实需要现有账号时，才应采用客户端/用户账号流程。授权会生成敏感的 session 数据，账号仍须遵守 Telegram 的规则，获得 API 访问权限也不代表可以发送垃圾消息或进行其他被禁止的行为。UnifyPort 不会把 bot token 转换成用户 session，不会代替你创建 API ID，也不会移除 Telegram 的平台管控。

另外，不要把网站使用的 Telegram Login 与这里的凭证选择混为一谈。Telegram 当前的网站登录系统采用 OpenID Connect，并有自己独立的客户端配置；它既不能代替 Bot API token，也不能代替 MTProto 用户账号授权。

常见问题

Telegram API ID 和 bot token 是同一个东西吗？

不是。API ID 标识参与 Telegram API 授权的客户端应用，bot token 则让某一个 bot 通过 Bot API 完成身份验证。两者的签发位置不同，控制的身份也不同。

已经有 bot token，还需要 API ID 和 API hash 吗？

调用普通 HTTP Bot API 时不需要，只要使用该 bot 的 token。如果集成要通过客户端 API 授权 Telegram 用户，就需要 API ID 和 API hash；bot token 无法登录该用户账号。

my.telegram.org/auth 在哪里？

打开 https://my.telegram.org/，使用 Telegram 手机号登录。通过身份验证后，选择 API development tools，即可创建或查看与该手机号关联的 API ID 和 API hash。

没有 API hash，可以只用 QR code 登录吗？

不可以。Telegram 的 auth.exportLoginToken 请求同时包含 api_id 和 api_hash。QR code 是用户批准登录的步骤，不能代替应用凭证。

UnifyPort 可以用 BotFather token 连接 Telegram 吗？

普通 Telegram 账号授权流程不可以。验证码和扫码模式都使用 provider_data.api_id 和 provider_data.api_hash，验证码模式还需要账号手机号。如果目标身份是 bot，请直接使用官方 Bot API。

下一步

如果要连接现有 Telegram 账号，请打开 Telegram 授权指南，选择验证码或扫码流程。如果只需要 bot 身份，请继续使用 @BotFather 和官方 Bot API。

来源

来源与产品文档已于 2026-07-19 核验。