以编程方式接收 Truecaller 短信验证码

Truecaller 的 API 调用链是怎样的？

Truecaller 的服务 id 是 truecaller，下面所有调用都对 https://otproute.com/api/v1 发起，并使用前缀为 or_live_ 的 Bearer 密钥。

1. GET /api/v1/countries 给出国家 id；请缓存起来。
2. GET /api/v1/prices?country=<id>&service=truecaller 返回实时价格，以及此刻是否有可用线路。
3. POST /api/v1/activations，请求体为 {"service": "truecaller", "country": "in"}（或任何其他国家 id），预留号码并返回激活 id。
4. 在测试设备的 Truecaller 应用中输入该号码并请求验证。
5. 验证码以 activation.sms_received Webhook 事件的形式到达，或者你轮询 GET /api/v1/activations/{id}。
6. 如果测试被放弃，POST /api/v1/activations/{id}/cancel 会立即退款。

一个账号支持 10 个 API 密钥、5 个 Webhook 端点，限速为每分钟 300 次请求。API 集成指南涵盖了重试和超时。

Webhook 处理程序应该如何处理 Truecaller 事件？

每次投递都带有 X-OTPRoute-Signature: t=<unix>,v1=<hex>。用端点密钥对时间戳、一个点号和原始请求体重新计算 HMAC-SHA256，以恒定时间方式比较，并拒绝时间戳过旧的请求。

所有处理都以激活 id 为键。Webhook 可能被重试，因此如果处理程序把验证码存了两次，或让测试推进了两次，就会产生不稳定的结果；行动之前，请先检查该激活是否已被标记为完成。把 activation.expired 和 activation.cancelled 视为终态，告诉你的测试运行器停止等待。在没有公网端点的本地开发环境中，轮询可以作为后备方案。

Truecaller 为什么一定要手机号？

Truecaller 是一款来电显示和垃圾电话拦截应用，手机号就是账号本身。注册时会先确认用户掌控该号码，然后才创建个人资料，在重新安装应用或换到新设备时会再次校验。在某些设备上，应用可能尝试用电话而不是短信来验证。OTP Gateway 号码只接收短信，所以基于电话的校验不会在激活上产生验证码；窗口只会走完，钱包随即退款。

团队验证 Truecaller 账号的正当理由包括：检查公司外呼的客服或配送号码在某个市场的用户那里是如何被标注的，对集成了来电识别的应用做 QA，以及运营人员需要一个与个人手机分开的工作资料。

哪些国家有 Truecaller 线路？

实时快照显示 Truecaller 线路覆盖 198 个国家，其中包括印度、巴基斯坦、孟加拉国、尼日利亚、肯尼亚，以及埃及、印度尼西亚、斯里兰卡、尼泊尔、沙特阿拉伯、阿联酋、巴西、墨西哥、南非、英国和美国。

请选择与测试用例匹配的国家。来电标签、垃圾电话举报和应用语言都跟随市场，所以检查你的拉各斯客服线路如何显示，就应使用尼日利亚线路，而不是随便挑最便宜的。可用情况在一天中会变化；每次运行前请查询价格接口。

非开发人员能在控制台完成吗？

可以。登录，打开 OTP Gateway，选择 Truecaller 和一个国家，确认显示的价格，号码就会出现在一张激活卡片上。在 Truecaller 中输入它并请求验证码，短信到达后，验证码就会显示在同一张卡片上。20 分钟窗口在卡片上清晰可见。如果没有收到验证码，或者你取消了，全额款项会自动退回钱包。钱包可通过银行卡或 USDT/USDC 充值，每次都会通过邮件发送 PDF 发票；请参见价格。

Truecaller 验证码为什么可能收不到？

常见原因：

• Truecaller 因为把该号码视为虚拟号码而拒绝了它。有些服务就是这样；这也是你会获得退款的原因。
• 应用选择了基于电话的验证，而不是短信。
• 线路暂时拥堵。请稍后重试，或换一个符合你测试的国家。
• 号码输入时漏掉了国家区号，或多带了一个多余的前导 0。

不要在循环里猛烈调用下单接口。请把尝试间隔拉开，并记录每个激活 id，以便发现规律。

什么时候专属号码对 Truecaller 更合适？

一次性号码在激活结束后就消失了。如果某个 Truecaller 资料之后必须重新验证，例如客服团队的工作设备被重置，请改用专属号码。专属号码在美国和加拿大即时可用，$1.95/月起，在控制台并通过 number.sms_received Webhook 接收短信，并从钱包续期，直到你释放它们。请参见虚拟号码。

OTP Route 只可用于你自己的合法账号和产品：每个真实的个人或企业一个账号，不得针对他人的号码进行举报或更改标签，并充分尊重 Truecaller 的条款和 OTP Route 的《可接受使用政策》。Truecaller 是其所有者的商标，OTP Route 与其没有关联。

常见问题

Truecaller 在 API 中的服务 id 是什么？

是 truecaller。在 GET /api/v1/prices 和 POST /api/v1/activations 的请求体中，把它与国家 id 搭配使用。

我能在虚拟号码上接收 Truecaller OTP 吗？

通常可以，但不总是；Truecaller 可能拒绝它归类为虚拟的号码。如果 20 分钟内没有收到验证码，费用会自动退款。

为什么 Truecaller 打电话而不是发短信？

在某些设备上，应用可以选择基于电话的验证。OTP Gateway 号码只接收短信，所以如果应用提供短信选项，请选择短信。

做 Truecaller 短信验证测试，应该选哪个国家？

选择你的测试所针对的市场，因为来电标签和语言跟随号码所属国家。请先用价格接口检查实时可用情况。

我能保留同一个 Truecaller 手机号以便以后登录吗？

可以，使用美国或加拿大的专属号码，$1.95/月起。一次性的 Gateway 号码无法重复使用。

如何避免重复的 Webhook 投递破坏我的测试？

让处理程序以激活 id 为键具备幂等性，并且在对载荷做任何处理之前先校验签名。

OTP Route 与 Truecaller 有关联吗？

没有。Truecaller 是其所有者的商标；OTP Route 提供号码，用于测试和运营你自己的合法账号。

服务名称均为其各自所有者的商标，OTP Route 与其无任何关联。请合法使用号码，并遵守各服务的条款及我们的可接受使用政策。