GitHub 上的 Telegram 注册检测与托管 API 对比

本文对运行 GitHub 上的开源 Telegram 注册检测脚本与使用托管式 Telegram 注册检测 API 及仪表板进行了中立对比。

GitHub 上的 Telegram 注册检测脚本（例如 Bellingcat 的开源脚本）运行在您个人的 Telegram 用户账户和开发者凭据之上，因此适合需要人工监控账户并维护代码的临时性研究工作。托管 API 则更适合周期性的业务流程，因为团队只需调用已记录的 REST 端点并使用 API 密钥，无需将个人 Telegram 账户登录到自动化程序中。选择哪种方案取决于检测量、账户风险、维护时间以及结果如何集成到其他系统中。

开源 Telegram 注册检测工具的工作原理

GitHub 上大多数开源检测工具遵循相同的模式。脚本通过客户端 API 以普通用户身份登录 Telegram，将目标号码添加为联系人，读取哪些号码匹配到了账户，然后将其删除。Telegram 官方记录的 contacts.importContacts 方法描述了此行为：它导入联系人列表并返回已在 Telegram 上的联系人。该方法仅适用于用户账户，不适用于机器人。

最著名的例子是 Bellingcat 的 telegram-phone-number-checker，这是一个采用 MIT 许可的 Python 工具。其文档列出了所需条件：

• 一个拥有活跃电话号码的 Telegram 账户。
• 在 my.telegram.org 上创建的 api_id 和 api_hash。
• 通过命令行或交互方式输入的号码或用户名列表。

该工具会返回可用的用户名、姓名和账户号码，可以下载头像，并将结果写入 JSON 文件。其文档还警告称，Telegram 可能会封禁用于自动化的个人账户，并建议使用新账户。

运行 GitHub 脚本的实际成本

下载是免费的，但运营成本存在于其他方面。

凭据与账户设置

Telegram 关于 obtaining api_id 的指南解释说，每个电话号码只能关联一个 api_id，且通过非官方客户端登录的账户会被置于监控之下。同一页面警告称，将 API 用于滥发消息或垃圾信息会导致永久封禁。因此，团队需要一个专门的号码和账户，并指派专人负责维护该号码的状态。

账户限制

从单个账户导入大量联系人可能会触发限制。一旦发生这种情况，脚本将停止返回有效答案，且账户可能需要恢复。为了规避此问题而将任务分散到多个账户的做法，属于 Telegram 服务条款所不欢迎的范畴。

维护

Telegram 会更新其 API 层，客户端库也会随之更改。无人值守的脚本可能会在依赖项更新后失效，届时必须有人查看问题、锁定版本并重新测试。对于每月仅检查少量号码的研究部门来说，这尚可管理；但对于 CRM 流程而言，这会变成一项计划外的工程任务。

数据处理

由于脚本将号码导入到真实账户的联系人中，目标数据会经过该账户。Telegram 的 FAQ 指出，同步的联系人会保持同步直到被删除，因此清理步骤必须成为流程的一部分。

托管式 Telegram 检测 API 的区别

托管式注册检测服务消除了个人账户层。使用 TG Validator 时，集成通过 X-API-Key 标头中的 API 密钥进行身份验证，并将一个 E.164 格式的电话号码发送至 POST /api/v1/check（服务类型为 tg），或将最多 100 个号码发送至 POST /api/v1/batch-check。结果会在相同的响应中返回，包含已记录的 code、msg 和 data 信封；无法判定的检测会返回非零业务代码，而不是已完成的结果。

同一账户还为团队提供了一个 Web 仪表板，包含“单次检测”选项卡、“批量检测”选项卡（最多可粘贴 500 个号码）、检测历史记录、使用报告和 API 密钥管理。对于大型文件，异步批量任务支持 TXT 或 CSV 上传，并返回一个可下载的 result.csv，同时提供可选服务，以添加用户名、上次活跃的大致天数或基于头像的估算值。官方的 MCP 集成通过相同的密钥、余额和限制，为兼容的 AI 客户端提供单号码检测和余额工具。

公共 API 文档描述的是每用户并发和超时控制，而非每分钟速率限制，因此客户端应排队请求并妥善处理超时。

对比概览

两种方案各有优劣。脚本提供了对代码的完全控制和透明度；托管服务则以牺牲这种控制为代价，换取了可预测的运营。

何时选择哪种 Telegram 注册检测方案

GitHub 脚本通常适用于：

• 工作是偶尔进行的、调查性的或学术性的，且数据量较小。
• 有技术人员可以监督账户并更新代码。
• 结果由人工读取，而非输入到生产系统中。

托管 API 通常适用于：

• 检测在计划任务中运行，或集成在注册、CRM 或支持流程中。
• 多名团队成员（包括非开发人员）需要查看结果和历史记录。
• 组织倾向于不将业务流程与个人 Telegram 账户绑定。
• 结果需要一致的状态（包括明确的“无法判定”结果），以供下游逻辑使用。

有些团队会同时使用两者：用脚本进行临时研究，用托管服务处理周期性流水线。如果计划这样做，请将两组结果分开，因为它们对负面结果的定义不同。

选择前需考虑的问题

1. 每月检测多少号码，频率如何？ 周期性的大批量需求更适合具有明确行为记录的服务。
2. 脚本使用的 Telegram 账户归谁所有？ 如果是员工的个人账户，请重新考虑。
3. 当结果无法判定时会发生什么？ 确保下游系统能够存储该状态。
4. 结果将存放在哪里？ 在首次运行前规划好字段映射、时间戳和保留策略。
5. 检测的目的是什么？ 注册结果有助于渠道规划；它不能建立身份、同意或回复的可能性。

先回答这些问题通常会让选择变得显而易见，并使工作流程符合 Telegram 的 API 服务条款 以及团队自身的数据政策。

常见问题解答

Bellingcat 的 Telegram 注册检测工具可以免费使用吗？

该工具采用 MIT 许可，可免费下载。它需要一个拥有活跃电话号码的 Telegram 账户以及来自 my.telegram.org 的开发者凭据，且其文档警告称，Telegram 可能会封禁用于自动化的个人账户。

为什么 GitHub 上的检测工具必须使用 Telegram 账户？

它们以普通用户身份使用 Telegram 客户端 API，通常通过将号码导入为联系人并读取哪些号码匹配到了账户来实现。该方法仅适用于用户账户，因此必须有一个已登录的账户。

团队如何在不丢失历史记录的情况下从脚本迁移到托管 API？

导出脚本过去的检测结果及其日期，将其保存在单独的字段或表中，并开始记录新的托管检测结果。由于注册状态会随时间变化，在重复使用旧记录前请重新进行检测。

托管 API 返回的数据与开源脚本相同吗？

不一定。托管式注册检测返回的是已记录的注册状态，可选的批量服务会添加特定列，如用户名或大致活跃度。脚本返回的是代码从已登录账户中读取到的任何内容，因此输出格式和定义有所不同。

了解更多

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

• 查看产品文档 →
• 联系团队 →