Viber 号码查询 API：校验与获取资料数据
Viber 在东欧、希腊、菲律宾以及亚洲部分地区仍是主流的即时通讯应用，对当地许多受众来说，它才是真正会被阅读的渠道。如果你的触达或数据管道覆盖这些地区，校验号码是否在用 Viber，并补全昵称和头像，就很有价值。Viber 号码查询 API 对每个号码只需一次简单的 HTTP 调用。
本文介绍如何校验 Viber 注册状态、拉取资料数据、以可直接嵌入的形式获取头像，并说明如何正确处理三态结果和响应外层结构。
第一步：获取 API Key
注册后在控制台复制一个有效 Key。账户赠送免费点数，下面每个调用都可以直接试。
第二步：校验注册状态
check 是最轻量的接口，接收国际格式的手机号 number，只返回号码和 registered，不带资料和头像数据。开头的 + 可有可无，接口会统一成纯数字。
curl "https://api.opendata-api.com/api/project/viber/check?key=YOUR_API_KEY&number=447700900123"registered 是三态值：true 表示已注册，false 表示未注册，null 表示暂时无法判断。null 属于临时性情况，比如超时，message 字段会说明原因。请稍后重试，千万不要把它算作「没有 Viber」。
这里有一个和很多接口不同的地方：Viber 的响应被包在 {"code", "data"} 里，HTTP 状态码始终是 200，结果体现在 code 和 data.registered 中。平台还会再包一层，所以原始 JSON 里 registered 位于 data.data.registered。只检查 raise_for_status() 是不够的，必须看响应体；下面的 Python 封装会帮你拆开这些外层。
第三步：获取资料
user-info 返回注册状态以及账号的公开资料：Viber 昵称（viberName）、内部标识 memberId 和 viberId、message，以及查询耗时 durationMs。它还会返回 serverStatus，这是针对该号码的权威结果，1 表示已注册，3 表示未注册。
curl "https://api.opendata-api.com/api/project/viber/user-info?key=YOUR_API_KEY&number=447700900123"在去重或把 Viber 账号关联到 CRM 联系人时，可以用 memberId 或 viberId 作为稳定的键。
第四步：获取头像
get-avatar 以多种开箱即用的形式返回头像：
signedUrl：一个有效期数小时的临时图片链接，任何客户端无需认证即可直接访问。imageUrl：用于获取当前图片的稳定链接。imageBase64与dataUrl：内嵌的图片内容，可以直接放进<img>标签。hasImage：为false表示账号没有公开头像或没有注册。
响应还会带上 registered、viberName 和以字节计的图片大小 imageLen。
curl "https://api.opendata-api.com/api/project/viber/get-avatar?key=YOUR_API_KEY&number=447700900123"signedUrl 会过期，所以如果之后还要用图片，请下载一次并自行保存文件，不要只存这个链接。
完整的 Python 示例
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://api.opendata-api.com/api/project/viber"
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()
# The reply is wrapped as {"code": ..., "data": {...}}, and the platform wraps it once more
while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
body = body["data"]
return body
def viber_profile(number):
status = get("check", number=number)
registered = status.get("registered")
if registered is None:
return {"number": number, "registered": None, "retry": True, "reason": status.get("message")}
if registered is False:
return {"number": number, "registered": False}
info = get("user-info", number=number)
avatar = get("get-avatar", number=number)
photo = None
if avatar.get("hasImage") and avatar.get("signedUrl"):
photo = requests.get(avatar["signedUrl"], timeout=30).content
return {
"number": number,
"registered": True,
"name": info.get("viberName"),
"member_id": info.get("memberId"),
"viber_id": info.get("viberId"),
"photo_bytes": photo,
}
print(viber_profile("447700900123"))这个函数对每个号码只花一次便宜的 check，只有号码已注册时才去取资料和头像。无法判断的结果会带上重试标记返回，方便你的任务队列稍后再试。
Viber 与其他号码检测的分工
| 你想知道什么 | 该看哪里 |
|---|---|
| 号码有没有 Viber，资料昵称是什么 | Viber 的 user-info |
| 同样的问题，换成注重隐私的通讯工具 | Signal 号码查询 |
| 有没有 Telegram，有没有公开用户名 | Telegram 号码检测 |
| 下一条消息该走哪个渠道 | 线索核验工作流 |
Viber 在它是当地默认通讯工具的市场里最有价值。面对覆盖全球的名单，建议同时查多个渠道，按联系人选择渠道，而不是默认只用一个应用。
应用场景
- 区域营销：在 Viber 占主导的东欧、希腊等地，把消息路由到 Viber。
- 线索补全：为 Viber 渗透率高的市场里的联系人补充 Viber 昵称和头像。
- 客服工具：在会话开始前，向客服人员展示对方的头像。
- 渠道选择：按联系人选对消息渠道，而不是凭猜测。
- 名单清洗：从 Viber 专项发送中剔除未注册号码。
最佳实践
- 号码归一化。 使用带国家区号的纯数字，开头的
+可有可无。 - 先校验，再补全。 对整份名单先跑
check，只对已注册的号码调用user-info和get-avatar。 null当作重试。 无法判断的结果延迟后重新入队，不要直接丢弃。- 去重并缓存。 保存结果时带上时间戳，避免为同一次查询重复付费。
- 不要直接引用头像链接。
signedUrl是临时的，请保存图片本身。 - 保持合规。 只处理你有合法依据使用的号码，并遵守 Viber 条款与当地隐私法规。
常见问题
怎么检查一个手机号有没有注册 Viber？
用国际格式的号码调用 check 接口，返回里的 registered 为 true、false 或 null。null 表示当时无法判断，请稍后重试。
为什么 Viber 接口的 HTTP 状态码总是 200？
Viber 的响应被包在 {"code", "data"} 里，结果通过 code 字段和 data.registered 表达，而不是 HTTP 状态码。平台还会再包一层，所以原始 JSON 里 registered 位于 data.data.registered。请务必读取响应体，不要只依赖状态码。
serverStatus 是什么意思？
这是 user-info 返回的、针对该号码的权威结果：1 表示号码已注册 Viber，3 表示未注册。
能通过手机号拿到 Viber 头像吗？
账号有公开头像时可以。get-avatar 会返回 hasImage，以及 signedUrl、imageUrl 和内嵌的 dataUrl。hasImage 为 false 时，说明账号没有公开头像或没有注册。
signedUrl 能用多久？ 它是有效期数小时的临时链接。需要的时候下载图片并自行保存文件，不要长期保存这个链接。
立即体验
在 Viber 号码校验页面在线测试，或阅读 check、user-info 与 get-avatar 接口文档。查看定价了解每次请求的成本。