Viber 号码查询 API:校验注册、昵称与头像

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

华沙跨境支付的客服主管每天要给乌克兰、保加利亚、希腊号码分流。她按「有没有即时通讯」一刀切,提醒打进没人打开的应用。这些市场里还会亮起来的信箱仍是 Viber;只有是/否、没有显示名和头像,坐席还得猜对面是谁。

真正容易踩坑的不是号码格式,而是:HTTP 200 并不等于已注册。Viber 查询也不是别的查号接口换了个名字。你拿到三态 registered、公开显示名,以及能嵌进工单的头像 URL——前提是读嵌套的 data,而不是只看状态行。

东欧和东南亚还在用的信箱

Viber 在东欧、希腊、菲律宾和东南亚部分地区仍是默认聊天工具。名单偏北美时几乎无感;来自索非亚、基辅、雅典或马尼拉时,验证码备选或客服会话发错应用,就会石沉大海。

所以它不是「又一个查号接口」。Viber 号码校验把三件事放在同一条链路上:号在不在、公开显示名是什么、能不能把照片放进工单。别的查询可以停在布尔值;这里有用的产物是名字,外加一张能直接嵌入的图。

在控制台复制自己有权使用的 Key(需先登录),只放服务端。Key 走查询串,日志、截图和分享链接都要脱敏。打开本页或复制示例不会发请求;换成真实 Key 并执行才会调用、扣额度。文档示例号 447700900123 只说明输入形态(国际区号、纯数字、前导 + 可有可无),不保证是真实在网账号。

一次 GET 分类号码

先打最轻的 check:一次 GET、一个 number,不带头像和资料。

curl --get \
  'https://api.opendata-api.com/api/project/viber/check?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

前导 + 可省略。号码里可能有加号时用 --data-urlencode,免得变成空格。

registered 是三态:true 已注册,false 未注册,null 暂时无法判断(常见于超时,原因在 message)。稍后重试,不要把 null 当成没有 Viber。

业务包在 {"code", "data"} 里,HTTP 状态始终是 200,结论在 code 和 data.registered。平台再包一层,原始 JSON 里 registered 位于 data.data.registered。只调用 raise_for_status(),或把 HTTP 200 当成「在」,整份名单都会标错。

先看网关 code / message,再拆到真正带 registered 的对象。Key 从服务端环境变量 OPENDATA_API_KEY 读取,需自行安装 requests。准备扣额度时再调用。

import os
import requests

BASE = "https://api.opendata-api.com/api/project/viber"


def viber_get(operation, **params):
    response = requests.get(
        f"{BASE}/{operation}",
        params={"key": os.environ["OPENDATA_API_KEY"], **params},
        timeout=30,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    body = response.json()
    if not isinstance(body, dict) or body.get("code") not in (200, "200"):
        raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
    # Viber wraps as {code, data}; the platform wraps once more
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        body = body["data"]
    return body

registered 为 None 就入重试队列;为 False 不要补资料。只有 True 才去拿名字和头像。

显示名和头像怎么拿

确认在网后,两次较重的 GET 填工单。user-info 给出公开显示名 viberName、稳定标识 memberId / viberId、可读 message、耗时 durationMs,以及权威 serverStatus:1 已注册,3 未注册。CRM 用 memberId 或 viberId 做主键,避免换号后拆成两条。

curl --get \
  'https://api.opendata-api.com/api/project/viber/user-info?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

布尔查询给不了的是照片。get-avatar 直接给出能嵌的图:signedUrl 是数小时有效的临时直链,客户端不用带平台 Key 也能 GET;imageUrl 是取当前图的稳定路径;imageBase64 / dataUrl 可放进 <img>;hasImage 为 false 表示没有公开头像或未注册。同时回显 registered、viberName、imageLen。

curl --get \
  'https://api.opendata-api.com/api/project/viber/get-avatar?key=YOUR_API_KEY' \
  --data-urlencode 'number=447700900123'

不要长期引用 signedUrl,它会过期。工单要留照片,就当场下载并自己存文件。已注册但 hasImage=false,是没有公开头像,不是查询失败。名单先跑 check,只对 registered=true 再打后两个接口。

这个接口不会给你什么

这是公开资料查询,不是 Viber 客户端。它不发消息、不读会话、不返回最后在线,也不给你私密头像,更不会把号码映射成邮箱或证件。viberName 是当时的公开显示名,不是法定姓名。

signedUrl 不是能缓存数周的 CDN。空名字或 hasImage=false 是合法结果,不要重试到「必须出现一张脸」。HTTP 200 不是「已注册」,网关 code 不是 serverStatus,registered=null 也不是 false。三件事当成一件,清洗任务就会删掉只是暂时判不了的号码。

接口不给渠道排名,也不替你决定下一封消息走哪。Viber 仍是当地默认信箱时,它告诉你这个号有没有可展示的身份;渗透率低的市场查不到就是查不到,不要编造资料。费用见定价,字段见 check、user-info、get-avatar。只处理你有合法依据使用的号码。