注册并联系客服，免费领取 100 次检测。免费注册
AvatarLookup
AvatarLookup 工作流示意图：针对电话号码列表的 Telegram 头像解析
本文所述工作流的示意图（AvatarLookup）。

本指南详细介绍了 Telegram 电话号码批量产品的操作步骤，解释了为何无法进行实时查询，以及如何准备、运行和读取任务。

若要通过电话号码解析 Telegram 头像，请将准备好的列表提交至 AvatarLookup 的 Telegram 电话号码批量产品。Telegram 头像解析仅作为异步批量任务提供，因此不支持实时单次查询。您需要上传一个 TXT 或 CSV 文件（每行包含一个带国家代码的号码），跟踪任务直至完成，然后下载生成的 CSV 文件。结果仅描述公开头像，不显示账户所有者信息。

为何 Telegram 头像解析仅支持批量处理

通过电话号码搜索 Telegram 头像时，人们往往认为查询方式类似于联系人搜索：输入号码，即可看到头像。Telegram 的运作方式并非如此。它将电话号码和个人头像视为独立的隐私设置。在“隐私与安全”设置中，每个人都可以选择谁能看到自己的号码以及谁能看到自己的照片，选项包括所有人、仅限联系人或无人，Telegram 的 官方常见问题解答 对这些控制项进行了说明。因此，只有在所有者允许的情况下，照片才是可见的。

在 AvatarLookup 的产品目录中，Telegram 电话号码解析仅作为单一产品存在：异步批量任务。目前不存在实时 Telegram 查询（无论是单次还是多次），因此团队在规划集成时，不应预设能够获得单次查询的即时结果。实时和同步的多项查询仅适用于 WhatsApp 以及受支持的 Gmail、Yandex 和 Mail.ru 邮箱地址。

这种设计符合 Telegram 的典型使用场景，即审查列表而非查找个人。营销运营团队可能拥有来自区域数据库的数万个号码，他们关注的是其中有多少号码展示了公开头像，以及头像的类型。在后台运行并返回一个 CSV 文件的任务非常适合此类需求。

准备带国家代码的电话文件

文件准备工作决定了任务能否成功，因此请务必重视。Telegram 电话号码产品要求使用 TXT 或 CSV 文件，且每行仅包含一个标识符。系统不接受 XLSX 及其他电子表格格式，因此请将表格导出为 CSV 或将号码粘贴到纯文本文件中。

请遵循以下检查清单：

  1. 每个号码均需以数字形式书写，包含国家代码，且不得包含加号、空格、破折号或括号。
  2. 为任务选择一个国家/地区。列表中的号码应基本属于该国家/地区，因此请将跨国列表拆分为每个国家一个文件。
  3. 删除重复项、空行和标题行。
  4. 确认列表大小符合产品在 API 文档和定价页面中公布的最小和最大限制。
  5. 保留原始列表的副本，以便将结果与您的记录进行关联。

通过 API 提交时，请将任务发送至 POST /api/v1/bulk-tasks。在多部分提交中，国家/地区字段必须位于文件字段之前，当客户端库对表单部分进行重新排序时，这一点很容易出错。电话号码任务不接受 +86、+852 或 +853 号码，因为这些地区的号码仅可通过实时单次查询获得，且这些查询不涵盖 Telegram。

运行任务并下载 CSV

批量任务是异步的。提交文件后会返回一个可供跟踪的任务，您可以使用 GET /api/v1/bulk-tasks/{id} 检查其进度。服务未规定固定的完成时间，因此请根据状态而非时间来规划工作。

请遵循以下操作规则：

  • 轮询频率不得超过每 30 秒一次。更频繁的轮询只会增加负载，没有任何收益。
  • 当状态显示成功时，下载为该任务生成的单个 CSV 文件。
  • 下载链接的有效期为 12 小时。如果链接过期，请再次查询同一任务以刷新链接。
  • 请及时将 CSV 存储在您自己的系统中，并标注日期及提交的文件。

在大规模运行之前，请先使用接近产品最小限制的小文件进行测试，以确认您的格式、国家/地区选择和下游导入均正常工作。在小文件上修复标题问题，远比在处理完完整列表后才发现问题要高效得多。请通过 GET /api/v1/balance 密切关注账户余额，以免因额度不足导致长时间运行的任务停滞。

读取 Telegram CSV 时避免过度解读

Telegram 电话号码 CSV 拥有其特定的列，不应假设其与其他产品匹配。Viber、MAX、LINE、Zalo 和邮箱批量文件各自返回其特有的字段，因此请为每个产品编写单独的导入映射，而不是使用一个通用的架构。在构建映射之前，请阅读 API 文档中的列列表。

解读规则比列本身更重要：

  • 包含公开照片的行意味着已解析出公开头像。若存在外观属性，这些均为算法估算值，而非人口统计学事实。
  • 没有照片的行意味着没有可用的公开头像。这可能反映了所有者的照片隐私设置，并不代表该号码没有 Telegram 账户。
  • 无法判定行意味着查询未得出结论。这两种结果均不能证明账户不存在。
  • 即使结果为负面，已完成的行仍会计费。

将输出结果作为联系人审查的输入之一，例如将显示肖像的记录与显示徽标的记录分开，或优先进行人工检查。这并非身份验证，也不能证明谁在控制账户。针对用户名列表，还存在一个单独的 Telegram 用户名批量产品，用户名可以以纯用户名、@username 或 Telegram 链接形式提供。当您的来源是用户名而非号码时，请使用该产品，并将其结果保存在单独的表中。

常见问题解答

是否有针对单个号码的实时 Telegram 头像查询？

没有。Telegram 头像解析仅作为异步批量产品提供，分别针对电话号码和用户名。实时单次查询和同步多次查询仅涵盖 WhatsApp 以及受支持的 Gmail、Yandex 和 Mail.ru 邮箱，因此 Telegram 工作流应围绕文件和任务进行设计。

Telegram 电话号码产品接受什么文件格式？

TXT 或 CSV，每行一个标识符。号码应以带国家代码的数字形式书写，不带加号，且任务需选择一个国家/地区。系统不支持 XLSX 上传，因此电子表格应先导出为 CSV。

缺少照片是否意味着该号码没有 Telegram 账户？

不是。缺少照片可能反映了所有者的隐私设置，也可能仅仅是因为没有照片。团队应如何处理这些行？请将其视为“无头像”或“无法判定”的结果，避免就账户是否存在得出结论。

可以包含来自香港或澳门的 Telegram 号码吗？

批量任务不支持 +852、+853 或 +86 号码，这些号码仅限于实时单次查询，且这些查询不涵盖 Telegram。台湾 (+886) 的支持情况尚未确认，因此团队在包含此类号码前，应查阅最新文档。

了解更多

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

参考来源