注册并联系客服，免费领取 100 次检测。免费注册
TG Validator

Telegram 电话号码 API 选项：Bot API、客户端 API 或注册检测 API

哪种 Telegram 电话号码 API 适合您的工作：获取共享号码、编写用户账户脚本，还是检查号码列表的注册状态。

TG Validator 编辑团队发布于 2026年10月21日6 分钟阅读
TG Validator 工作流示意图：Telegram 电话号码 API 选项：Bot API、客户端 API 或注册检测 API
本文所述工作流的示意图（TG Validator）。

一份面向开发者的指南，对比了 Telegram Bot API、Telegram 客户端 API 以及用于处理电话号码相关工作的注册检测 API。

Telegram 并没有单一的“电话号码 API”。Telegram Bot API 仅在用户主动选择共享时接收电话号码；Telegram 客户端 API 通过真实用户账户及其凭据运行；而像 TG Validator 这样的注册检测 API 则用于回答提交的号码是否已在 Telegram 注册。请根据您的任务选择合适的工具：从意愿用户处收集号码、自动化您自己的账户，或检查您现有的号码。

开发者所指的 Telegram 电话号码 API 是什么

搜索“telegram phone number api”通常源于以下三种任务之一：

  1. 在 Bot 内收集用户号码，例如将 Telegram 聊天与客户账户关联。
  2. 自动化 Telegram 用户账户，例如管理联系人或构建自定义客户端。
  3. 检查您现有的号码，例如在选择沟通渠道前，标记哪些 CRM 联系人拥有 Telegram 账户。

每项任务都对应不同的接口，具有不同的凭据、限制和责任。选择错误的接口是集成工作停滞的最常见原因。

Bot API：接收用户选择共享的号码

Telegram Bot API 不会通过电话号码查找用户。Bot 仅在用户发送号码时才能接收：

  • 设置了 request_contact 的回复键盘按钮会要求用户以联系人形式共享其电话号码。参考文档指出，此功能仅适用于私聊。
  • 共享的消息包含一个 Contact 对象，其中包含电话号码以及（可选的）用户 Telegram 标识符。

当您希望客户通过其明确操作将 Telegram 聊天连接到您的服务时，这是正确的工具。它无法检查号码列表，且 Bot 无法调用客户端 API 的联系人导入方法，Telegram 文档明确该方法仅供用户使用 (contacts.importContacts)。

客户端 API：自动化真实的 Telegram 账户

Telegram 客户端 API (MTProto) 是官方和第三方应用程序所使用的接口。TDLib、Telethon 和 Pyrogram 等库对其进行了封装，大多数开源的“电话号码检查器”脚本也是基于此构建的。

在基于此构建之前，请注意 Telegram 在 Obtaining api_id 中记录的内容：

  • 您需要从 my.telegram.org 获取 api_id 和 api_hash，这些凭据需通过现有的 Telegram 账户创建；每个电话号码只能关联一个 api_id。
  • 第三方客户端必须遵守 API 服务条款。使用非官方客户端的账户会被置于观察之下，通过 API 进行洪水攻击或发送垃圾信息可能导致永久封禁。
  • 导入联系人会将它们存储在运行代码的账户中。

客户端 API 非常适合构建真正的 Telegram 客户端或自动化您自己的账户。对于检查业务联系人列表，这意味着公司数据将存储在某个人的账户中，一旦该账户丢失，工作流就会中断。

注册检测 API：回答号码是否在 Telegram 上

注册检测 API 专为第三种任务而构建。TG Validator 的 REST API 无需您拥有任何 Telegram 账户即可运行：

  • 单次检查： 使用带有 sk_ 前缀密钥的 X-API-Key 请求头调用 POST /api/v1/check。JSON 正文需指定 tg 服务类型以及 E.164 格式的电话号码。
  • 小批量检查： POST /api/v1/batch-check 每个请求最多可接受 100 个号码。
  • 同步响应流： 两个端点均在响应中直接返回结果；无需提交任务或轮询。
  • 响应封装： 文档化的封装结构为每个答案提供了业务代码和消息。已完成的结果会在同一响应中告知您该号码是否已在 Telegram 注册。无法判定的检查将返回非零业务代码且无已完成结果。
  • 余额： GET /api/v1/balance 允许您的服务在执行大型任务前检查剩余余额。

当前的 API 文档描述的是用户并发和超时控制，而非每分钟请求限制：最多支持 5 个并发检查，单次检查超时为 60 秒，多号码检查超时为 300 秒，且每个账户同时只能进行一个多号码检查。在调整工作进程前，请务必在文档中确认这些限制，因为它们可能会发生变化。

对于远超 100 个号码的列表，独立的异步批量端点支持上传 TXT 或 CSV 文件，并在任务完成后返回一个 result.csv 文件。

Telegram 电话号码 API 对比

问题 Bot API 客户端 API 注册检测 API
能否检查您持有的号码列表？ 不能 通过用户账户的联系人导入功能 可以，支持单次、每请求最多 100 个或批量文件
凭据 Bot Token api_id、api_hash 和已登录的用户账户 来自仪表板的 API 密钥
涉及谁的账户？ Bot 自身 真实个人的 Telegram 账户 无需 Telegram 账户
主要风险 范围仅限于主动共享的用户 账户限制及条款合规性 服务成本及文档化的使用控制
最适合 将用户聊天关联到您的服务 构建客户端或自动化您自己的账户 路由和清理联系人记录

许多产品结合了其中两种方式：使用 Bot 与选择加入的用户进行对话，并使用注册检测来决定哪些现有联系人适合通过 Telegram 进行邀请。

注册检测 API 集成清单

  • 先进行标准化处理。 在调用 API 之前，将号码转换为 E.164 格式（加号、国家代码，无主干前缀或标点符号）。
  • 密钥保留在服务器端。 切勿将其包含在移动应用或浏览器包中，并从仪表板管理密钥。
  • 处理三种结果。 已注册、未注册和无法判定。将无法判定的检查结果单独存储并稍后重试，而不是将其标记为负面结果。
  • 遵守并发限制。 根据文档化的并发限制调整工作池大小，并在遇到错误时进行退避，而不是在紧密循环中重试。
  • 存储检查时间。 注册状态是检查时刻的信号；保留日期以便在结果过期时进行刷新。
  • 为已确定的检查预留预算。 无论结果如何，每次已完成的确定性检查都会按适用费率收费，因此请在发送前进行去重。
  • AI 客户端： https://tgvalidator.com/mcp 处的 MCP 端点向兼容 MCP 的客户端公开了相同的响应检查和余额查询功能，使用带有相同密钥和余额的 Bearer 认证。批量任务仍需通过 REST API 执行。

常见问题解答

Telegram Bot 可以通过电话号码查找用户吗？

不能。Bot 仅在用户共享电话号码时才能接收，通常是通过私聊中请求联系人的回复键盘按钮。检查号码列表需要使用客户端 API 的用户账户或注册检测 API。

团队如何在没有 Telegram 账户的情况下检查 Telegram 注册状态？

使用注册检测 API。TG Validator 支持通过 POST /api/v1/check 提交 E.164 格式号码，或通过 POST /api/v1/batch-check 提交最多 100 个号码，并使用 X-API-Key 请求头进行认证，在同一响应中返回结果。

TG Validator API 有每分钟请求限制吗？

没有发布每分钟请求限制。文档描述的是用户并发和超时控制，因此集成时应根据这些控制调整工作进程，并查看当前文档以获取变更信息。

团队如何在进行大规模推广前试用 API？

注册用户可以联系支持团队获取 100 次免费检查额度，这足以测试输入标准化、无法判定结果的处理以及针对小样本的日志记录。

了解更多

选择适合您工作流下一步的产品信息。

参考来源