如何查询号码是否注册了 Telegram(检测 API)

发布于 2026年8月23日 · 更新于2026年10月16日

userHash 是 get-about 和 get-picture 唯一收的字段。手机号、@用户名、user:<id> 在这两个接口上都会被拒。check-exists 只在对象确实在 Telegram 上时签发这张 24 小时票;后面两个接口只负责花掉它。这篇 Telegram 号码检测 讲的就是交接:先签发、窗口内复用、过期再签。

不必登录 Telegram 账号,也不要去造票。userHash 只能由检测接口在 exists=true 时签发,客户端拼一个看起来像 token 的字符串没有用。要在控制台拿到你有权使用的平台密钥(没有账号先登录)。Python 从服务端环境变量 OPENDATA_API_KEY 读取;curl 示例里的 YOUR_API_KEY 只是占位符。查询串带着密钥,不要写进网页、仓库、截图或完整 URL 日志,生产环境在服务端调用。打开本文或复制示例不会发请求,主动执行才会查数、扣点数。

先拿到 userHash 再往下走

简介和头像都等 userHash。这张票又等一个公开字段:peer。三种写法:

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

手里只有对方公开用户名时,直接传用户名,不必硬凑手机号。已经有数字 ID 时用 user:<id>,避免再绕一次号码解析。requests 会编码加号;手写 URL 必须把 + 写成 %2B,否则会被当成空格,reason 看起来像号码本身写错。

先看 HTTP 状态,再看网关信封 {code, message, data}。code=200 才是业务成功。对象不存在仍可能是业务成功:exists=false,reason 为 PHONE_NOT_OCCUPIED 或 USERNAME_NOT_OCCUPIED,用来区分号码和用户名。干净的未占用不要当传输失败去重试,也别立刻去拉简介。

exists=true 时会带数字用户 ID、用户名(若有)、显示名称和 userHash。显示名称和用户名可以先入库,但不要把它们当成下一跳的入参——下一跳只认 hash。下面的号码只是文档形态,不保证命中。

把返回里的 userHash 和签发时间一起存。没有这张票,后面两步没有合法输入。名单很长时,先把检测结果落库,再按业务需要挑一批去补全,不要检测完立刻对每一行拉头像。

检测存在与签发票

hash 绑在你刚检测的那个 peer 上,24 小时内可重复使用,过期即作废。网关在服务端还原对象,消费接口只收 userHash,不会把票转给 Telegram。缺失、未知或过期的 hash 直接被拒(HTTP 400,业务失败),不会去拉简介。要新票,再跑一次 check-exists。

没有批量接口。先去重、归一化(手机号带 + 和区号),每个对象只检测一次,把 exists、reason、身份字段、userHash 和签发时间一起存。只对还要补全、且未满 24 小时的对象去花票。窗口还在就反复检测,等于把便宜的存在性查询当成刷新按钮,既浪费点数,也把旧票作废的节奏打乱。

import base64
import os
from datetime import datetime, timedelta, timezone

import requests

BASE = "https://api.opendata-api.com/api/project/telegram"
KEY = os.environ["OPENDATA_API_KEY"].strip()
TTL = timedelta(hours=24)


def call(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={"key": KEY, **params},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Transport failure; inspect redacted logs") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    try:
        envelope = response.json()
    except ValueError:
        raise RuntimeError("Expected JSON") from None
    if not isinstance(envelope, dict) or envelope.get("code") != 200:
        raise RuntimeError("Gateway business failure; review redacted diagnostics")
    payload = envelope.get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Unexpected operation payload")
    return payload


def mint(peer):
    found = call("check-exists", peer=peer)
    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("check-exists did not mint a userHash")
    return {
        "peer": peer,
        "exists": True,
        "username": found.get("username"),
        "userHash": user_hash,
        "issued_at": datetime.now(timezone.utc),
    }


def enrich(ticket, want_photo=False):
    if not ticket.get("exists"):
        return ticket
    issued = ticket.get("issued_at")
    if not isinstance(issued, datetime) or datetime.now(timezone.utc) - issued >= TTL:
        raise RuntimeError("userHash expired; mint again with check-exists")
    about = call("get-about", userHash=ticket["userHash"])
    profile = {
        "peer": ticket["peer"],
        "exists": True,
        "username": ticket.get("username") or about.get("username"),
        "about": about.get("about") or None,
    }
    if want_photo:
        picture = call("get-picture", userHash=ticket["userHash"])
        if picture.get("pictureSet") and picture.get("data"):
            profile["photo"] = base64.b64decode(picture["data"])
        else:
            profile["pictureSet"] = False
    return profile


ticket = mint("+8613800138000")
print(enrich(ticket) if ticket.get("exists") else ticket)
handle = mint("@some_username")
print(enrich(handle, want_photo=True) if handle.get("exists") else handle)

头像是可选项。很多名单只要「在不在」加简介;跳过 get-picture 能少一次请求。用户名和简介会变,按计划复查,不要每次展示都重签。过期后先 mint,再 enrich,不要拿旧票去碰消费接口。同一张票在有效期内可以多次花:先拉简介、过一会儿再拉头像,不必重新检测。

Telegram 和 WhatsApp 不能互相替代:前者能查公开用户名并返回用户 ID,后者只认号码,且注册标记是三态。渠道怎么选见WhatsApp 与 Telegram 查询接口对比。检测不是发信,用 Python 发送和读取 Telegram 消息走的是已登录账号;多渠道组合见线索核验工作流。

用 hash 拉简介和头像

只传已保存的 hash,不要再带 peer。服务端会从票里还原对象;你再传一遍号码或用户名,接口也不会用。消费接口看不到你当初用的是手机号还是用户名,它们只认这张仍在有效期内的票。

get-about 返回公开简介,以及数字用户 ID 和用户名。about 为空表示没设或隐藏了,这是正常结果,接口不会编造文本。若对象其实是群或频道,会返回表示请求错误的业务码,而不是简介——停下来,不要去解不存在的字段,也不要把这次失败当成「用户把简介藏起来了」。

get-picture 把头像以 base64 放在 data 里,MIME 为 image/jpeg,因为 Telegram 头像没有公开链接。解码即字节,自行落盘;不要指望一个可长期访问的图片 URL。pictureSet=false 表示没有头像或被隐私隐藏,不是传输失败,也不该换个 hash 重试同一对象。

可在 Telegram 号码校验页面用自己的密钥试,或看 check-exists、get-about、get-picture。超出赠送点数时见定价。

把 24 小时窗口用丢的写法

  • 往简介或头像接口传 peer。它们不收这个参数,hash 本身就是身份。
  • 窗口未过就反复跑 check-exists。把票和签发时间存下来,过期或需要新的存在性结论时再签。
  • hash 过期后死磕 get-picture。过期票在网关就被拒,先重签再花。
  • 把 HTTP 200 当成「已注册」。业务成功仍可能是 exists=false;过期票是 HTTP 400,不是隐藏简介。
  • 手写 URL 不编码加号,空格让 reason 看起来像号码错误。
  • 对未占用对象补全简介和头像。只有 exists=true 且票仍有效才花。
  • 把空 about 或 pictureSet=false 当故障。隐藏或未设置是合法答案。
  • 把带 key= 的完整 URL 打进日志,或把密钥塞进浏览器。
  • 只有用户名却强行要手机号。peer 已支持用户名和 user:<id>。
  • 拿 Telegram 的 hash 去调别的项目。票只绑这次检测的 peer。
  • 把群或频道的业务错误当成短暂超时。那不是重试窗口,是对象类型不对。

只处理你有正当依据使用的联系人。24 小时够补全一份短名单,不够当每次翻页都重查的理由。