通过电话号码列表查找 Telegram 用户名
了解团队如何通过批量活动任务将 Telegram 用户名添加到电话号码列表中，以及如何读取 result.csv 列并处理空用户名。
本指南介绍了如何使用 tg_active_batch 批量服务将 Telegram 用户名添加到特定国家的电话号码列表中，内容涵盖文件准备、result.csv 列说明、空用户名处理及负责任的使用原则。
若要查找业务列表中电话号码对应的 Telegram 用户名，可将该列表通过批量活动任务（如 TG Validator 的 tg_active_batch）进行处理，该任务会返回每个号码的 Telegram 注册状态以及 uid、用户名和 activedays。当账户没有公开用户名时，用户名列将为空，因为在 Telegram 中用户名是可选的。请将输出结果视为对团队现有记录的丰富化，而非用于查找未知人员的工具。
为什么团队需要通过电话号码查找 Telegram 用户名
大多数针对此短语的指南描述的是消费者路径：将号码保存到通讯录，在应用中打开个人资料，如果显示用户名则读取它。这种方法适用于单个好友，但对于包含数千个潜在客户的 CRM 导出数据则不适用，且会将业务数据通过员工的个人通讯录进行处理。
业务团队通常有不同的目标：
- 支持团队需要用户名，以便在客户要求通过 Telegram 联系时，座席可以链接到客户的 Telegram 个人资料（使用 t.me 链接）。
- 社区和增长团队希望将现有联系人与已出现在其群组或频道中的账号进行匹配。
- CRM 团队希望在每个电话记录旁保留一个稳定的 Telegram 键值，以便合并重复项。
这三者都属于对组织现有记录的丰富化工作。这种定位对于方法选择以及后续数据的使用方式至关重要。
Telegram 用户名与电话号码的关系
在 Telegram 中，电话号码用于创建账户，而用户名是一个可选的公开账号。根据 Telegram FAQ 的说明，用户无需设置用户名，可以在“设置”中添加或删除用户名，并可以分享 t.me 链接，以便他人无需查看其电话号码即可联系。用户还可以自行决定谁能看到其电话号码以及谁能通过号码找到他们。
这带来了两个实际后果：
- 许多账户没有用户名，因此用户名列为空是正常结果，而非错误。
- 用户名可以更改或删除。今天获取的账号应标注获取日期。
Telegram uid 则不同：它是数字账户标识符，不会随用户名的更改而改变。因此，uid 比用户名更适合作为去重时的关联键。
哪种 TG Validator 服务返回用户名
仪表板中或通过 POST /api/v1/check 调用的单号码 Telegram 注册检测仅返回 Telegram 注册状态。它是判断号码是否拥有 Telegram 账户的正确工具，但不会返回用户名。
用户名由异步批量活动服务 tg_active_batch 提供。对于每个电话号码，它返回以下内容：
| result.csv 中的列 | 含义 | 备注 |
|---|---|---|
| identifier | 提交的电话号码 | 用于关联回源列表 |
| activated | Telegram 注册状态 | 与单次检测相同的窄范围账户存在信号 |
| uid | Telegram 数字账户标识符 | 用于去重的稳定键值 |
| username | 公开的 Telegram 用户名 | 账户无用户名时为空 |
| activedays | 距离上次活动的大致天数 | 当 Telegram 隐藏确切的最后在线时间时，此值为近似值 |
额外列取决于服务类型，某些行可能为空。如果团队还需要头像 URL 和基于头像的估算值，tg_profile_batch 是单独的个人资料服务；对于当前任务，tg_active_batch 是更专注的选择。
操作步骤：从电话列表到用户名列
- 每个文件选择一个国家。 电话号码批量任务要求选择一个国家，且文件中的号码应基本属于该国家。如果 10% 或更多的号码使用其他国家代码，文件将被拒绝，因此请先按国家拆分混合列表。
- 标准化为国际格式。 使用 ITU-T Recommendation E.164 定义的国家代码，移除主干零、空格和符号，并进行去重。
- 保存为 TXT 或 CSV，每行一个号码。 各产品的最大文件大小和条目数限制适用；请查看当前的 API 文档。
- 创建任务。 在仪表板的“批量检测”区域或通过
POST /api/v1/bulk-tasks创建任务，选择 tg_active_batch 和国家。 - 等待任务完成。 任务会报告 processing、success 或 failed 状态。通过 API 轮询时，频率请勿超过每 30 秒一次。
- 下载 result.csv 并根据 identifier 列将其关联回源列表。
提交任务时会预扣余额。任务完成后，返回结果的条目将被扣费，未使用的预扣余额将释放；失败的任务会释放全部预扣余额。
批量文件任务不支持中国大陆 (+86)、香港 (+852) 和澳门 (+853) 的号码，请勿将其包含在上传文件中。
读取和存储用户名结果
将 result.csv 关联回列表后，将行分类为实际组别：
- 账户存在，用户名存在。 将用户名和 uid 存储在专门的 CRM 字段中，并标注任务日期。
- 账户存在，用户名为空。 账户存在但没有公开账号。保留 uid 用于去重，并将用户名字段留空，不要自行编造值。
- 无账户。 标记 Telegram 字段，并保留号码用于其他渠道。
- 列因其他原因为空。 某些额外列在部分行中可能为空；请将其视为未知，而非零值。
一些存储习惯可以防止后续混淆：
- 存储用户名时去掉开头的 @ 并统一为小写，因为 Telegram 用户名不区分大小写。
- 在存在 uid 的情况下，以 uid 作为合并键，因为用户名可能会被更改或释放。
- 将 activedays 作为带有日期的近似值存储；它描述的是距离上次活动的天数，而非该用户当前是否在线。
- 按适合工作流的计划刷新丰富化数据，而不是将一次运行视为永久有效。
列表丰富化，而非人员查找
用户名告诉团队某个号码所关联的 Telegram 公开账号。它不会揭示电话持有者的身份，不能确认潜在客户是否如其所称，也不是向其发送消息的许可。
负责任的团队在进行丰富化之前会设定一些内部规则：
- 仅对为了 Telegram 联系或支持目的而收集的号码进行丰富化。
- 将保留的列限制在工作流所需的范围内。英国 ICO 关于 数据最小化 的指南要求个人数据应充足、相关且仅限于必要范围。
- 根据 ICO 的 准确性原则，更正或删除过时的值。
- 尊重选择不设置用户名的用户；空字段是他们的选择，而非需要通过其他方式填补的空白。
这些规则是内部政策的示例，而非针对特定司法管辖区的法律建议。
FAQ
为什么有些拥有 Telegram 账户的号码，其用户名列为空？
在 Telegram 中，用户名是可选的。当账户没有公开用户名时，tg_active_batch 仍会报告注册状态和其他可用列，但用户名列将保持为空。
单号码检测可以返回 Telegram 用户名吗？
不能。单号码 Telegram 注册检测仅返回注册状态。用户名、uid 和 activedays 来自 tg_active_batch 批量服务。
团队如何使用已有的用户名来丰富记录？
当起始列表包含用户名而非电话号码时，单独的 tg_username_batch 服务会检查这些用户名是否属于现有账户，而 tg_username_profile_batch 会添加 uid、activedays 和头像 URL。用户名任务无需指定国家，且接受带或不带 @ 的账号。
团队应该以 Telegram 用户名还是 uid 作为 CRM 记录的键值？
uid 是更好的键值，因为它在用户更改或删除用户名时保持不变。请将用户名作为显示字段存储，并标注其获取日期。
了解更多
选择适合您工作流下一步的产品信息。