Telegram 用户名检测：账号存在性与名称可用性
了解 Telegram 用户名存在性检测与名称可用性检测的区别，以及如何使用 TG Validator 对用户名列表进行批量测试。
用户名可用性工具用于查询某个标识符是否可供注册，而存在性检测则用于确认列表中的标识符是否属于真实的 Telegram 账号。
Telegram 用户名存在性检测与常见的用户名检查工具所解决的问题不同。可用性工具会告知您某个标识符是否可供注册；而存在性检测则会告知您列表中的标识符在当前时刻是否关联着一个 Telegram 账号。对于列表处理，TG Validator 通过 tg_username_batch 服务处理后者，而 tg_username_profile_batch 则为同类文件增加了额外的个人资料列。两者均作为异步批量任务运行，并返回一个可下载的 result.csv 文件。
两个问题，一个搜索词
搜索“telegram username checker”的结果通常会将两个看似相似但实则不同的任务混为一谈。
第一个任务是可用性。用户希望为品牌、频道或机器人获取一个新的标识符，并询问该标识符是否可以注册。Telegram 将此记录为一项登录后的操作：官方的 account.checkUsername method 会验证用户名并报告其是否可用。第三方工具封装了相同的逻辑，有些还会查看市场上待售或被持有的标识符。
第二个任务是存在性。团队已经拥有一个从表单、CRM 备注、社区导出数据或合作伙伴表格中收集的标识符列表，并希望了解其中哪些标识符仍指向真实的账号。该答案用于列表清理，而非名称注册。
这两个答案甚至可能看起来是相反的。在可用性工具中显示为“已被占用”的标识符，在存在性检测中即为“已存在”。“可用”的标识符是指当前未解析到任何账号的标识符。如果您运行了错误的工具，您将反向解读输出结果，因此在选择工具之前，请先确定您要解决的问题。
存在性检测的报告内容
对于用户名文件，TG Validator 提供两种异步批量服务：
| 服务 | 对每个用户名的报告内容 |
|---|---|
| tg_username_batch | 该用户名是否属于现有的 Telegram 账号 |
| tg_username_profile_batch | 相同的存在性结果，外加账号的 uid、activedays 和头像 URL |
用户名书写时可以带或不带前缀 @，因此混合了 "@example_name" 和 "example_name" 的表格无需预先重写。与电话号码批量任务不同，用户名任务不需要您选择国家/地区。
两条阅读说明有助于准确理解输出结果。首先，activedays（若存在）是自上次活动以来的大致天数，当 Telegram 隐藏了确切的最后在线信息时，该数值可能为近似值。其次，存在性结果仅描述了检测时该标识符的状态。它仅告知您该标识符解析到了一个账号；它不描述是谁在操作该账号，也不描述该用户如何使用 Telegram。
通过批量任务运行用户名列表
无论您使用 Web 控制面板还是 REST API，工作流程都是相同的。
- 收集标识符：将其整理为 TXT 或 CSV 文件，每行一个用户名。不支持 XLSX 文件，因此请从电子表格中导出纯文本列。
- 清理明显干扰项：删除空行、粘贴到单元格中的完整 t.me 链接以及末尾空格。避免重复；同一个标识符被检查两次会占用两个处理条目。
- 选择服务：当您仅需了解哪些标识符存在时，使用
tg_username_batch。当您的清理规则还需要 uid、activedays 或头像 URL 时，使用tg_username_profile_batch。 - 提交任务：在 API 中，此操作为 POST /api/v1/bulk-tasks。任务余额在提交时预留，并在完成时进行核算，未消耗的部分将释放。
- 轮询状态：GET /api/v1/bulk-tasks/{id} 会报告 processing、success 或 failed。由于不公开每个条目的进度，请不要以超过每 30 秒一次的频率进行检查。
- 下载 result.csv：任务成功后下载该文件。文件使用标识符列显示您的原始条目，并使用 activated 列显示结果；额外列取决于服务类型，可能为空。
每项任务均有规模限制，因此在规划超大型文件之前，请在 API 文档中确认当前数值，而不要依赖从文章中复制的数字。
将结果转化为列表决策
请将 result.csv 视为过滤器，而非最终定论。一种实用的模式是保留三个工作组。
- 已存在：解析到账号的标识符。这些标识符保留在活跃列表中，并可进入下一步审查。
- 未注册：未返回账号的标识符。这些是移除的候选对象，或者需要与提供该条目的人员进行后续核实，因为拼写错误和已废弃的标识符在此处表现一致。
- 需要二次查看：可选列为空的行。个人资料列中的空值是正常结果，因此不要将空白的头像 URL 或 activedays 视为导入错误。
当您使用 tg_username_profile_batch 时，uid 列作为稳定键非常有用。标识符可以由所有者重命名，而 uid 则始终关联该账号，因此将其存储在用户名旁边，以便您日后核对记录。uid 是您自己记录的数据库键，并不代表账号背后的个人信息。
任何 activedays 阈值均属于您自己的业务规则。团队可能会将超过特定天数的行归档以进行轻量级列表管理，但本产品并未定义何为“活跃”，且该数值始终为近似值。
检查用户名时的常见错误
- 在清理列表中使用可用性工具：它会告诉您哪些标识符可供注册，这与清理工作的需求正好相反。
- 在同一个文件中混合电话号码和用户名：电话号码任务需要国家/地区和国际区号；用户名任务则不需要。请将它们保存在单独的文件中并提交单独的任务。
- 期望获取实时在线状态：没有任何用户名服务会报告谁当前在线，也不会暴露私人聊天、群组或联系人。
- 将缺失的标识符视为已删除的人员：用户可能更改了标识符，导致旧标识符失效。在删除联系人记录之前，请先咨询数据所有者。
- 过度轮询：提交任务后每隔几秒请求一次状态会浪费调用次数。轮询间隔请至少保持 30 秒。
如果您的列表包含电话号码而非标识符，则实时的 tg 服务和电话号码批量服务更为合适，并且可以通过在各自的任务中检查每种输入类型来结合这两种方法。
常见问题解答
Telegram 用户名存在性检测与可用性检测有什么区别？
可用性检测询问标识符是否可以被注册，通常通过登录后的 Telegram 操作完成。存在性检测询问列表中的标识符当前是否属于某个 Telegram 账号，这是列表清理工作所关注的问题。
哪些 TG Validator 服务可以检查用户名？
tg_username_batch 报告用户名的账号存在性，tg_username_profile_batch 则额外提供 uid、activedays 和头像 URL。两者均为异步批量服务，生成单个 result.csv 文件。
团队在提交文件前应如何格式化用户名？
使用每行一个用户名的 TXT 或 CSV 文件。用户名书写时可以带或不带前缀 @，且用户名文件无需选择国家/地区。
团队应如何解读用户名个人资料结果中的 activedays？
请将其解读为自上次活动以来的大致天数。当 Telegram 隐藏了确切的最后在线信息时，该数值可能为近似值，每个团队需自行设定处理旧数据的阈值。
用户名和电话号码可以在同一个任务中检查吗？
不能。电话号码任务和用户名任务具有不同的输入规则，因此团队需将其作为单独的文件和任务提交。
了解更多
选择符合您工作流程下一步的产品信息。