如何查询号码是否注册了 Telegram（检测 API）

Telegram 拥有超过十亿用户，在许多地区和社群里，它是最主要的消息渠道。因此在搭建触达、客服或验证流程之前，「这个联系人用 Telegram 吗」是值得先回答的问题。Telegram 号码检测只需一次成本很低的 API 调用就能给出答案，第二步还可以为确实存在的账号补充公开简介和头像。

本文介绍如何检测手机号、用户名或用户 ID，userHash 两段式流程是怎么回事，以及如何用 Python 处理各种返回结果。这些查询都不需要你登录任何 Telegram 账号。

第一步：获取 API Key

注册，打开控制台，复制一个有效的 API Key。账户赠送免费点数，可用于测试。

第二步：检测对象是否存在

check-exists 接口接收一个 peer，支持三种写法：

• +手机号：以加号开头的数字，例如 +8613800138000。
• @用户名，或不带 @ 的用户名。
• user:<id>：数字形式的 Telegram 用户 ID。

curl "https://api.opendata-api.com/api/project/telegram/check-exists?key=YOUR_API_KEY&peer=%2B8613800138000"

手动拼接 URL 时，加号要写成 %2B，否则会被当成空格。当你手里只有对方的 Telegram 用户名而没有手机号时，直接传用户名就特别实用。

对象存在（exists=true）时，响应会包含数字形式的 Telegram 用户 ID、用户名（对方设置了的话）、显示名称，以及一个 userHash。不存在时 exists 为 false，reason 会给出 PHONE_NOT_OCCUPIED 或 USERNAME_NOT_OCCUPIED 之类的代码，让你知道问题出在号码还是用户名上。

第三步：获取简介和头像

userHash 用来授权两个更重的查询，有效期 24 小时，缺失、未知或已过期的 hash 会被拒绝。这两个接口只需要传 hash，不接受 peer 参数。

# bio (About text), plus numeric user ID and username
curl "https://api.opendata-api.com/api/project/telegram/get-about?key=YOUR_API_KEY&userHash=USER_HASH"

# profile photo, returned base64-encoded
curl "https://api.opendata-api.com/api/project/telegram/get-picture?key=YOUR_API_KEY&userHash=USER_HASH"

解读结果时请注意这几点：

• about 为空表示用户没有设置简介，或者隐藏了简介，这不是错误。
• get-picture：Telegram 的头像没有公开链接，所以图片以 base64 编码放在 data 字段里，并附带 MIME 类型（image/jpeg），解码 data 即可得到图片字节。
• pictureSet=false 表示用户没有头像，或者通过隐私设置把头像隐藏了。
• 如果这个对象其实是群组或频道而不是用户，get-about 会返回一个表示请求错误的业务码，而不是简介。

完整的 Python 示例

import base64
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.opendata-api.com/api/project/telegram"


def get(operation, **params):
    params["key"] = API_KEY
    resp = requests.get(f"{BASE}/{operation}", params=params, timeout=30)
    resp.raise_for_status()
    body = resp.json()
    # A reply can be wrapped more than once as {"code": ..., "data": {...}}
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        body = body["data"]
    return body


def telegram_profile(peer, want_photo=False):
    found = get("check-exists", peer=peer)   # requests encodes "+" for you
    if found.get("exists") is False:
        return {"peer": peer, "exists": False, "reason": found.get("reason")}

    user_hash = found.get("userHash")
    if found.get("exists") is not True or not user_hash:
        raise RuntimeError(f"unexpected reply: {found}")
    about = get("get-about", userHash=user_hash)
    profile = {
        "peer": peer,
        "exists": True,
        "username": found.get("username"),
        "about": about.get("about") or None,
    }
    if want_photo:
        picture = get("get-picture", userHash=user_hash)
        if picture.get("pictureSet") and picture.get("data"):
            profile["photo"] = base64.b64decode(picture["data"])
    return profile


print(telegram_profile("+8613800138000"))
print(telegram_profile("@some_username", want_photo=True))

头像查询是可选的。很多时候只要知道账号存在、再加上简介就足够了，跳过头像可以为每个联系人省下一次请求。

批量名单与缓存

Telegram 没有批量接口，所以需要循环处理名单，把工作量控制得小一些：

1. 先对号码和用户名去重并归一化。手机号要带开头的 + 和国家区号。
2. 每个对象只调用一次 check-exists，把 exists、reason、用户 ID 和 userHash 连同时间戳一起保存。
3. 只对真正需要补全的对象调用 get-about 和 get-picture，并且只在 hash 生成不到 24 小时的时候。超时后，重新跑一次 check-exists 获取新的 hash。
4. 按计划周期复查，而不是每次触达都查一遍，因为用户名和简介都可能变化。

Telegram 与 WhatsApp 的区别

两个应用都可以按手机号检测，但并不能互相替代。Telegram 还能按公开用户名查询并返回用户 ID，而 WhatsApp 只能按号码查。如果你在决定先验证哪个渠道，可以看WhatsApp 与 Telegram 查询接口对比。想从「检测」进一步到真正联系对方，用 Python 发送和读取 Telegram 消息用的是已登录账号的方式；多个渠道如何组合使用，则见线索核验工作流。

应用场景

• 渠道路由：只对确认在用 Telegram 的联系人走 Telegram 发送。
• 社群与线索研究：为 Telegram 用户名补全简介和头像数据。
• 验证流程：确认联系人拥有一个可触达的 Telegram 账号。
• 名单清洗：从 Telegram 专项活动中剔除未注册的联系人。
• ID 解析：把用户名或手机号转换成数字形式的 Telegram 用户 ID。

最佳实践

• 号码和用户名都接受。 当你只有用户名时，不要强求手机号。
• 先校验，再补全。 没通过检测的对象，直接跳过简介和头像查询。
• userHash 在 24 小时内缓存复用。 同一个对象重复查资料时，用已保存的 hash，不必重新调用 check-exists。
• 用 reason 排查问题。 它能区分是号码有问题还是用户名有问题，你可以修正输入，而不是盲目重试。
• 遵守平台规则和隐私法规。 只处理你有正当依据使用的联系人。

常见问题

怎么检查一个手机号有没有注册 Telegram？ 把号码按国际格式写成 +手机号 传给 check-exists，在原始 URL 里加号要编码成 %2B。返回结果会告诉你它是否存在，存在时还会给出用户 ID、用户名、显示名称和 userHash。

可以查用户名而不是手机号吗？ 可以。peer 支持 @用户名、不带 @ 的用户名，以及表示数字 ID 的 user:<id>。用户名不存在时返回 exists=false，reason 为 USERNAME_NOT_OCCUPIED 之类的代码。

userHash 是做什么的，能用多久？ 它用来授权针对某个对象的 get-about 和 get-picture 查询，有效期 24 小时。缺失或已过期的 hash 会被拒绝，再跑一次 check-exists 就能拿到新的。

为什么简介是空的？ about 为空，表示用户没有设置简介或把简介隐藏了。这是正常的结果，不是失败，接口也不会编造文本。

怎么保存 Telegram 头像？ get-picture 会把图片以 base64 编码放在 data 里，并附上 MIME 类型，因为 Telegram 的头像没有公开链接。把字符串解码后把字节写入文件即可。pictureSet 为 false 时，说明没有可见的头像。

立即体验

在 Telegram 号码校验页面在线测试，或阅读 check-exists、get-about 与 get-picture 接口文档。需要超出免费点数时，请查看定价。