プログラムから Truecaller の SMS コードを受信する

Truecaller の API 呼び出しの流れはどうなっているか？

Truecaller のサービス ID は truecaller で、以下の呼び出しはすべて、or_live_ で始まる Bearer キーを使って https://otproute.com/api/v1 に対して行います。

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 で即座に返金されます。

1 アカウントでは、API キー 10 個、Webhook エンドポイント 5 個、1 分あたり 300 リクエストまで利用できます。再試行とタイムアウトについては、API 連携ガイドで解説しています。

Webhook ハンドラーは Truecaller のイベントをどう扱うべきか？

各配信には X-OTPRoute-Signature: t=<unix>,v1=<hex> が付いています。エンドポイントのシークレットで、タイムスタンプ、ドット、生のリクエスト本文に対する HMAC-SHA256 を再計算し、定数時間で比較して、古すぎるタイムスタンプは拒否してください。

処理はすべてアクティベーション ID をキーにします。Webhook は再試行されることがあるため、コードを二重に保存したりテストを二重に進めたりするハンドラーは不安定な結果を生みます。処理の前に、そのアクティベーションがすでに完了済みになっていないか確認してください。activation.expired と activation.cancelled は終端状態として扱い、テストランナーに待機をやめるよう伝えます。公開エンドポイントがないローカル開発では、ポーリングがフォールバックとして使えます。

Truecaller はそもそもなぜ電話番号を求めるのか？

Truecaller は発信者 ID とスパムブロックのアプリで、電話番号がそのままアカウントです。登録時には、プロフィールが作成される前に、ユーザーがその番号を管理していることが確認され、アプリの再インストールや新しい端末への移行時にも確認が繰り返されます。端末によっては、アプリが SMS ではなく通話で認証しようとすることがあります。OTP Gateway の番号が受け取れるのは SMS のみなので、通話による確認ではアクティベーションにコードが届かず、ウィンドウが終了して料金がウォレットに返金されます。

チームが Truecaller アカウントを認証する正当な理由には、特定の市場の人々に自社のサポート用や配送用の発信番号がどう表示されるかの確認、発信者識別と連携するアプリの QA、個人の電話とは別の仕事用プロフィールを必要とする運用スタッフの利用などがあります。

Truecaller のルートがあるのはどの国か？

最新のスナップショットでは、198 か国に Truecaller のルートがあり、インド、パキスタン、バングラデシュ、ナイジェリア、ケニアのほか、エジプト、インドネシア、スリランカ、ネパール、サウジアラビア、アラブ首長国連邦、ブラジル、メキシコ、南アフリカ、英国、米国などが含まれます。

国はテストケースに合わせて選んでください。発信者のラベル、スパム報告、アプリの言語は市場に連動するため、ラゴスのサポート回線がどう表示されるかを確認するなら、たまたま最安のルートではなくナイジェリアのルートを使います。提供状況は一日の中で変わるため、実行のたびに価格エンドポイントを照会してください。

開発者でなくてもダッシュボードから実行できるか？

はい。サインインして OTP Gateway を開き、Truecaller と国を選んで表示された価格を確認すると、アクティベーションカードに番号が表示されます。Truecaller に番号を入力してコードを要求すると、SMS が届いた時点で同じカードにコードが表示されます。20 分のウィンドウはカード上で確認できます。コードが届かない場合やキャンセルした場合は、全額が自動的にウォレットに戻ります。ウォレットのチャージはカードまたは USDT/USDC で行え、そのたびに PDF の請求書がメールで届きます。詳しくは料金をご覧ください。

Truecaller のコードが届かないのはなぜか？

主な原因は次のとおりです。

• Truecaller が、仮想番号とみなして番号を拒否した。サービスによってはそうなることがあり、そのために返金があります。
• アプリが SMS ではなく通話による認証を選んだ。
• ルートが一時的に混雑していた。時間をおくか、テストに合う別の国で試してください。
• 番号を国番号なしで入力した、または余分な先頭の 0 が付いていた。

注文のエンドポイントをループで叩き続けないでください。試行の間隔をあけ、各アクティベーション ID を記録しておくと、パターンが見えてきます。

Truecaller では、どんなときに専用番号のほうが適しているか？

ワンタイム番号は、アクティベーションが終わると消えます。Truecaller のプロフィールを後で再認証する必要がある場合、たとえばリセットされるサポートチームの業務端末などには、専用番号を使ってください。専用番号は米国とカナダで即時に利用でき、月額 $1.95 からで、SMS をダッシュボードと number.sms_received の Webhook で受信し、解約するまでウォレットから更新されます。詳細は仮想番号をご覧ください。

OTP Route は、自社の正当なアカウントとプロダクトにのみご利用ください。アカウントは実在する個人または事業者 1 つにつき 1 つとし、他人の番号に対する報告やラベル変更は行わず、Truecaller の規約と OTP Route の利用規約（Acceptable Use Policy）を完全に守ってください。Truecaller はその所有者の商標であり、OTP Route は Truecaller と提携していません。

よくある質問

API で Truecaller のサービス ID は何ですか？

truecaller です。GET /api/v1/prices と POST /api/v1/activations の本文で、国 ID と組み合わせて使います。

仮想番号で Truecaller の OTP を受信できますか？

受信できることが多いですが、常にではありません。Truecaller が仮想と判断した番号を拒否することがあります。20 分以内にコードが届かなければ、料金は自動的に返金されます。

Truecaller が SMS ではなく電話をかけてきたのはなぜですか？

端末によっては、アプリが通話による認証を選ぶことがあります。OTP Gateway の番号が受け取れるのは SMS のみなので、アプリに選択肢があれば SMS を選んでください。

Truecaller の SMS 認証のテストには、どの国を選べばよいですか？

テストの対象となる市場を選んでください。発信者のラベルや言語は番号の国に連動します。まず価格エンドポイントで最新の提供状況を確認してください。

後のログイン用に、同じ Truecaller の電話番号を保持できますか？

はい。米国またはカナダの専用番号（月額 $1.95 から）を使えば可能です。ワンタイムの Gateway 番号は再利用できません。

Webhook の重複配信でテストが壊れないようにするには？

ハンドラーをアクティベーション ID に対して冪等にし、ペイロードを処理する前に署名を検証してください。

OTP Route は Truecaller と提携していますか？

いいえ。Truecaller はその所有者の商標です。OTP Route は、テストと、自社の正当なアカウントの運用のために番号を提供するサービスです。

サービス名はそれぞれの所有者の商標です。OTP Route はこれらの企業と提携していません。番号は合法的にご利用いただき、各サービスの利用規約および当社の利用規定に従ってください。