如何查询号码是否注册了 Telegram(检测 API)
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 小时够补全一份短名单,不够当每次翻页都重查的理由。