Telegramで電話番号認証を行う仕組み
Telegramのボットは送信者の電話番号を見ることができないため、WhatsAppとは異なる方法で認証を行います。そのフロー、裏側のチェック、アプリケーションに返される内容を解説します。
WhatsAppはPhone-Verifの最初のチャネルでしたが、誰もがWhatsAppを使っているわけではありません。Telegramが第2のチャネルとして加わりました。APIも結果も同じで、標準で有効になっています。ただし内部の仕組みは異なるため、提供する前に理解しておく価値があります。
WhatsAppでは、本人が送信するメッセージが証明になります。そのメッセージは本人の番号から届きます。これがReverse OTPの考え方です。一方、Telegramのボットにはそのような手がかりがありません。ボットは数値のアカウントIDで相手を識別し、電話番号は本人が共有を選ばない限り非公開のままです。そのためボットから番号を尋ねる必要があり、証明は送信者以外のところから得なければなりません。
ユーザーの操作
読み取るコードも入力するコードもありません。Telegram内での2回のタップだけで完了します。
1. リンクを開く
ページにQRコードまたはボタンを表示します。どちらも、セッショントークンを含んだリンクから当社のボットにつながります。
2. 「開始」を押す
「開始」を押すとそのトークンがボットに渡され、ボットがこのTelegramアカウントをセッションに紐付けます。
3. 番号を共有する
ボットには「電話番号を共有」というボタンが1つだけ表示されます。これをタップすると、Telegram標準の連絡先カードがアカウントから送信されます。
4. 完了
ボットが確認メッセージを返してセッションが認証済みになり、アプリケーションにwebhookとステータス結果が届きます。
共有された連絡先が証明になる理由
数字の羅列であれば誰でもボットに送れるため、入力された番号は一切受け付けず、ボットはボタンを再表示して応答します。読み取られるのは連絡先カードだけで、セッションを完了するには4つのチェックを通過する必要があります。
本人の連絡先であること
カードのユーザーIDが、送信しているアカウントと一致します。アドレス帳にある他人のカードは、ここで弾かれます。
正しいアカウントから届くこと
送信者は、このセッションで「開始」を押したアカウントです。そのため、他の人が開いたセッションをカードで完了させることはできません。
転送されていないこと
別のチャットから転送されたカードは、送信者本人のものであっても拒否されます。
新しいものであること
カードはセッションが開かれた後に送信されたものに限られるため、古いカードを再利用することはできません。
いずれかのチェックに失敗したカードは何も変更せず、ボットが再度番号を尋ね、セッションは開いたままです。ブロックリストに載っている番号は、WhatsAppと同様にTelegramでも拒否されます。
セッションは1回だけ完了する
ボタンをダブルタップすると連絡先カードが2回送信され、配信の再試行で同じカードが2回届くこともあります。そのため、セッションの完了はアトミックに確保されます。勝つのは1枚のカードだけで、結果もwebhookも消費されるクレジットも1つだけです。
また、セッションを完了できるチャネルは1つだけです。標準ではWhatsApp、SMS、ボットのすべてに開かれており、いずれかが完了すると、ほかのチャネルはそのトークンを拒否します。TelegramまたはWhatsAppに固定したセッションは、最初からもう一方のチャネルを拒否します。ボットのリンクはどのトークンでも同じようにリダイレクトされるため、有効なトークンを探り出す手段にはなりません。
1つの番号に、1つのID
TelegramとWhatsAppでは電話番号の表記が異なるため、何よりも先に番号を同じ形式に正規化します。IDがこの番号をキーにして管理されているためです。
今日WhatsAppで、明日Telegramで認証した人には、同じuser_idが返ります。2人ではなく1人のユーザーとして扱われ、flow=loginでもそれに応じてis_new_userが返されます。
当社自身もこの仕組みを利用しています。当社のサインインページにあるTelegram ConnectとWhatsApp Connectは、どちらを先に使ったかにかかわらず、同じ番号であれば同じアカウントにつながります。
返される内容
連携先のシステムは、WhatsAppと同じステータスレスポンスを読み取り、同じwebhookを受信します。認証にかかるクレジットも同じです。phone、login、2faの各フローがすべて利用できます。
追加されるのは1点だけです。flow=phoneでは、認証済みのTelegramセッションに、アカウントのuser_id、username、first_name、last_nameを含むtelegramオブジェクトも付きます。ログインと2FAでは含まれません。これらはユーザーIDまたは一致結果を返すだけで、ハンドルネームは電話番号と同様に本人を特定できてしまうためです。
証明できないこと
認証済みのセッションが示すのは、このTelegramアカウントがこの番号を保有しているということです。現在そのSIMカードを誰が持っているかについては何も示しません。これはアカウントに基づくすべてのチャネルに共通する限界で、SIMスワップに関する記事で解説しています。
所有者のチェックは、Telegramが連絡先カード上で報告するユーザーIDにも依存しています。TelegramのBot APIのドキュメントには、このフィールドがどのように設定されるかの記載がないため、WhatsAppの送信者番号と同様に、プラットフォームを信頼することになります。
実用上の制約もあります。ユーザーがTelegramを使っている必要があり、Telegramに固定したセッションにはSMSへのフォールバックがありません。
導入方法
セッションは標準でTelegramに開かれているため、追加するパラメータはありません。セッションをボットに固定するにはprovider=telegramを、ボットを除外するにはprovider=whatsappを送信します。
curl -X POST "https://api.phone-verif.com/start-verification" \
-H "X-API-Key: $PHONE_VERIF_API_KEY"Telegramが利用できない場合を除き、レスポンスにはwhatsappとsmsに加えてtelegramブロックが含まれます。qr_code_urlをQRコードにエンコードし、モバイルのボタンにはdirect_linkを使用してください。
{
"whatsapp": { "...": "..." },
"sms": { "...": "..." },
"telegram": {
"qr_code_url": "https://t.phone-verif.com/tg/<token>",
"direct_link": "https://t.me/PhoneVerif_com_bot?start=<token>"
}
}アカウントなしでTelegramデモをお試しいただけます。API全体については連携ガイドをご覧ください。