线索验证流程:先归一化去重,再花最便宜的检测
周衡管着杭州一家分期公司的周五外呼队列。今早邮箱里是三家供应商拼来的 18400 行。上个月他才搞明白:对每个单元格把所有渠道扫一遍,不叫验证流程。同一个手机号会以 +86 138…、0086…、带空格的粘贴同时出现;他为同一个人付了五次存在性检测,又拉了一次头像,再打了一次 Telegram peer,而三月的屏蔽表里早就有这条。他现在跑的是生产任务:先把文件缩小,一次做成规范号码,先花最便宜的那一跳,每批写完就落盘,进程挂了是续跑,不是把账单重开一遍。
打开本页或复制示例不会发查询。跑脚本才会,并且扣点数。登录 后从控制台复制你有权使用的平台 Key,放到打开 CSV 那台机器的 OPENDATA_API_KEY。文中的 YOUR_API_KEY 只是占位。Key 走查询串,不要写进工单、截图、仓库,也不要当成表格里的一列。
先把名单缩小再花钱
跨渠道任务最贵的习惯,是把每一行都当成每个平台上的新用户。点数会花在解析失败、三种写法的同一条 E.164、未注册号码的资料接口、以及你根本不会去发的第二个渠道。手册顺序和演示相反:丢掉垃圾格,合并重复,只打和这次活动匹配的最便宜存在性检测,先把原始响应落盘,再决定要不要打第二条渠道或补资料。
HTTP 成功不是注册结论。缺 Key、Key 无效、参数校验失败、传输失败,表现为 HTTP 4xx/5xx。网关信封是 {code, message, data},code 不是 200 同一条规则——信封里没有渠道结论。不要为了表格好看去写 false。HTTP 2xx 且网关 code 为 200,只说明这跳送达了,这时才读 isExist、exists、registered 或批量里的 exist。送达的 null 仍是业务结果:未判定,不是崩溃,排进重试。拆开之后没有这些字段,是空或畸形,不是一串「否」。
补资料是后面那一笔。WhatsApp、Telegram 在便宜检测命中时会签发 userHash,有效 24 小时,用来授权头像、签名或图片。只缓存给紧随其后的补全,不要靠拉资料来「看看在不在」。活动只走 WhatsApp,WhatsApp 为 true 就可以分流——停。Signal、Viber、Snapchat 各自有便宜检测,谁也不能当谁的代理。字段名和隐私边界见 WhatsApp 查询、Telegram 检测、Signal、Viber、Snapchat。前两者怎么选是另一篇:WhatsApp 与 Telegram 号码查询对比。文件级 WhatsApp 续跑在批量校验。
终态 false 要进屏蔽表并带时间戳。按计划重查(活跃名单从每月一次起),不要每次发送前都打,也不要每次崩溃都当新工单。
归一化和去重一次做完
按原始单元格去重,就是周衡把同一个人扣了三次的原因。一次扫描必须吐出唯一规范键,以及塌缩进来的来源行。用带国家码的纯数字,不含空格和标点(不带 + 的 E.164)。查询接口能容忍前导 +;WhatsApp 还接受空格、短横线和 00 前缀;Snapchat、Signal、Viber 会在服务端规整数字。那是给线路的宽容,不是给你索引的。缺国家码就猜,会得到一个言之凿凿的未注册,而你手里其实从来没有那个号。
解析不了的直接丢掉。N/A、空格、分机、没有国家码的本地号,不是「稍后再说」,是这场任务之外的东西。规范号码旁边留来源行 id,后面的 true/false 才能扇回所有指向它的 CRM 记录。
import json
import re
from collections import defaultdict
IN_JSONL = "leads.jsonl" # each line: {"row_id": "...", "phone": "..."}
OUT_MAP = "canonical.jsonl"
def canonical(raw):
text = str(raw).strip()
digits = re.sub(r"\D", "", text)
if text.startswith("00") and len(digits) > 8:
digits = digits.lstrip("0") or digits
if not (8 <= len(digits) <= 15):
return None
return digits
# One pass: drop junk, collapse aliases, remember every source row.
groups = defaultdict(list)
for line in open(IN_JSONL, encoding="utf-8"):
rec = json.loads(line)
key = canonical(rec.get("phone", ""))
if key is None:
continue
groups[key].append(rec["row_id"])
with open(OUT_MAP, "w", encoding="utf-8") as fh:
for number, row_ids in sorted(groups.items()):
fh.write(json.dumps({"number": number, "row_ids": row_ids}) + "\n")
print("unique", len(groups), "from", sum(len(v) for v in groups.values()), "parseable rows")
文中已经出现过的 +1 555 123 4567、0015551234567、15551234567 会收成一把钥匙。not a number 丢掉。剩余三个不要再塞占位号把批量「凑满」;假的未命中会在续跑时被当成已经干完。
最便宜的渠道先查
便宜有两层:存在性接口,不是资料接口;以及你真的会去发的渠道,不是把密钥下所有项目逛一遍。同一把有权限的平台 Key、同一份点数余额,覆盖 WhatsApp、Telegram、Signal、Viber、Snapchat。这不是把它们全打一遍的理由。从这次活动用的市场开始。周衡的队列是 WhatsApp。batch-check-10 用 accounts 一次最多十个完整国际号码。一到十都合法,十一个是坏请求。送达的每一行给 exist 和 isBusiness。isBusiness 只适合旁记分段,不是注册结论,也不会签发 userHash。表单当场只有一个人在等,用 check-exist-by-phone——为了「顺便走批量」去凑九个号,付的是延迟。
需要第二条渠道时,只把仍然值得打的号扇出去:重试后仍是 WhatsApp 未知,或 WhatsApp 为 false 而柜台实际走 Telegram / Viber。Telegram check-exists 的 peer 用 +phone。Signal check 和 Viber check 用 number。Snapchat check-phones-batch 一次最多 50 个逗号分隔号码。不要对名单批量探测 Snapchat 邮箱;那条路径走账号找回,命中可能给机主发一封真的找回邮件。
每批成功后写检查点。把本次请求的号码和原始返回放在一起,立刻 flush()。重启时,TTL 内已有终态 true / false 的号跳过。null、缺行、返回条数不够、以及从未给出业务正文的调用,都要重试。摊平字段是看过真实信封之后的第二步,不要默认按下标对齐。
import json
import os
import time
import requests
ROOT = "https://api.opendata-api.com/api/project"
KEY = os.environ["OPENDATA_API_KEY"].strip()
STATE = "channel_state.jsonl"
# Documented request shape only — running it spends credits.
# GET {ROOT}/whatsapp/batch-check-10?key=YOUR_API_KEY&accounts=15551234567
def unwrap(body):
while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
if body.get("code") not in (200, "200"):
return None
body = body["data"]
return body
def load_done(path):
done = {}
if not os.path.exists(path):
return done
for line in open(path, encoding="utf-8"):
rec = json.loads(line)
for n in rec.get("requested", []):
done.setdefault(n, rec)
return done
def whatsapp_batch(numbers):
resp = requests.get(
f"{ROOT}/whatsapp/batch-check-10",
params={"key": KEY, "accounts": ",".join(numbers)},
timeout=30,
)
if resp.status_code >= 400:
return None # no verdict — do not write false
return unwrap(resp.json())
done = load_done(STATE)
todo = [n for n in open("canonical.jsonl", encoding="utf-8") for n in [json.loads(n)["number"]] if n not in done]
chunks = [todo[i:i + 10] for i in range(0, len(todo), 10)]
with open(STATE, "a", encoding="utf-8") as fh:
for group in chunks:
payload = whatsapp_batch(group)
if payload is None:
time.sleep(2)
continue # leave the group out of done; next run retries
fh.write(json.dumps({"requested": group, "channel": "whatsapp", "raw": payload}) + "\n")
fh.flush()
并发先开小。第一遍就用线程池对每个号并行打 Telegram、Signal、Viber,两千行会在你反应过来之前变成八千次扣点,而 WhatsApp 那一列其实已经够分流。
评分分流,以及把同一号码再扣一遍的写法
评分是对已经落盘的结果做折叠,不是再开一轮 GET。至少有一个送达的 true,就在这些渠道上可触达——按你对该市场的顺序分流,本轮活动把其余渠道压掉。唯一的非未命中是 null,状态是 retry,不是 unreachable。你实际使用的渠道上全部送达 false,本周期就是不可达;写进屏蔽表,免得下周导入再付一遍。来源很硬(比如付费客户)却任何渠道都没注册,更像录入错误:交给人看,不要自动补资料。空的资料字段是隐私选择,不是质量扣分,而且必须先有便宜检测的 true 才轮得到它们。
注册不等于授权。存在性检测为 true,只说明该号码在该平台有账户,不意味着你可以发消息。尊重退订,保留合法依据,遵守各平台规则。这是操作建议,不是法律意见。
把同一号码再扣一遍的写法都是机械的,仪表盘再好看也挡不住:
- 名单还没做成规范号码,就打第二条渠道或资料接口。 同一条 E.164 的别名会看起来像新工单。
- HTTP 4xx/5xx、网关
code不是 200、缺字段、批量条数不够,却写成false。 这些是「没有结论」。要续跑。解析器若编一个未命中,这个号会永远被跳过,表格还显示绿灯。 - 把
null当成否。 未判定需要退避后再打便宜检测,不是进屏蔽表。 - 崩溃之后从头再来,因为检查点存的是漂亮的布尔值,而不是请求名单加原始正文。飞行中那一批会再付一次,你也看不见服务器哪些输入根本没回答。
- 给剩余块塞占位号,或对名单喷 Snapchat 邮箱探测。 占位行会变成假的结案。邮箱找回探测可能真的给机主发信。
- 每次发送都重查屏蔽表,或因为检测便宜就跳过授权。 新鲜度是计划。许可是另一套系统。
文件还小的时候,故意把进程杀掉一次。下次运行如果把同一批号码再打一遍,检查点就是摆设,账单会证明这一点。