Comment fonctionne la vérification de téléphone sur Telegram
Un bot Telegram ne voit jamais le numéro de l'expéditeur : la vérification y fonctionne donc autrement que sur WhatsApp. Voici le parcours, les contrôles effectués et ce que reçoit votre application.
WhatsApp a été le premier canal de Phone-Verif, mais tout le monde ne s'en sert pas. Telegram est désormais un second canal : même API, même résultat, et il est actif par défaut. La mécanique sous-jacente est différente, et mérite d'être comprise avant de le proposer.
Sur WhatsApp, la preuve est un message envoyé par la personne : il arrive depuis son numéro, c'est l'idée du Reverse OTP. Un bot Telegram ne dispose pas de ce signal. Il identifie les personnes par un identifiant de compte numérique, et leur numéro reste privé tant qu'elles ne choisissent pas de le partager. Le bot doit donc le demander, et la preuve doit venir d'ailleurs que de l'expéditeur.
Ce que fait la personne
Il n'y a aucun code à lire ni à saisir. Tout le parcours tient en deux appuis dans Telegram.
1. Ouvrir le lien
Votre page affiche un QR code ou un bouton. Les deux mènent à notre bot, avec le jeton de session dans le lien.
2. Appuyer sur Démarrer
Ce geste transmet le jeton au bot, qui associe ce compte Telegram à la session.
3. Partager le numéro
Le bot affiche un unique bouton pour partager le numéro. L'appui envoie la fiche de contact Telegram du compte.
4. Terminé
Le bot confirme, la session passe à vérifiée, et votre application reçoit son webhook et son statut.
Pourquoi un contact partagé vaut preuve
N'importe qui peut envoyer une suite de chiffres à un bot : les numéros saisis sont donc refusés d'emblée, et le bot réaffiche le bouton. Seule une fiche de contact est lue, et elle doit passer quatre contrôles avant que la session puisse se terminer.
C'est bien son propre contact
L'identifiant sur la fiche correspond au compte qui l'envoie. La fiche d'une autre personne échoue ici.
Elle vient du bon compte
L'expéditeur est le compte qui a appuyé sur Démarrer pour cette session : une fiche ne peut pas terminer la session de quelqu'un d'autre.
Elle n'a pas été transférée
Une fiche transférée depuis une autre conversation est refusée, même s'il s'agit de celle de l'expéditeur.
Elle est récente
La fiche a été envoyée après l'ouverture de la session : une ancienne fiche ne peut pas être rejouée.
Une fiche qui échoue à l'un de ces contrôles ne change rien : le bot redemande et la session reste ouverte. Un numéro sur liste de blocage est refusé sur Telegram comme sur WhatsApp.
Chaque session ne se termine qu'une fois
Un double appui sur le bouton envoie deux fiches, et une nouvelle tentative de livraison peut envoyer deux fois la même. La fin de session est donc réservée de façon atomique : une seule fiche l'emporte, avec un seul résultat, un seul webhook et un seul crédit consommé.
Une session ne peut aussi se terminer que sur un seul canal. Par défaut, elle est ouverte à WhatsApp, au SMS et au bot, et dès que l'un d'eux la termine, les autres refusent son jeton. Une session verrouillée sur Telegram ou sur WhatsApp refuse l'autre canal dès le départ. Le lien du bot redirige de la même façon pour tout jeton : il ne permet donc pas de savoir quels jetons sont actifs.
Un numéro, une identité
Telegram et WhatsApp n'écrivent pas les numéros de la même façon : le numéro est donc normalisé sous une forme unique avant toute autre chose. C'est important, car les identités reposent dessus.
Une personne qui se vérifie sur WhatsApp aujourd'hui et sur Telegram demain obtient le même user_id. C'est un seul utilisateur, pas deux, et flow=login renvoie is_new_user en conséquence.
Nous nous en servons nous-mêmes. Sur notre page de connexion, Telegram Connect et WhatsApp Connect mènent au même compte pour un même numéro, quel que soit le premier utilisé.
Ce que vous recevez
Votre intégration lit la même réponse de statut et reçoit le même webhook que sur WhatsApp, et une vérification consomme les mêmes crédits. Les flux phone, login et 2fa fonctionnent tous.
Une seule chose s'ajoute. Avec flow=phone, une session Telegram vérifiée contient aussi un objet telegram avec user_id, username, first_name et last_name. Login et 2FA l'omettent : ils répondent par un identifiant ou une correspondance, et un pseudo identifierait la personne autant qu'un numéro.
Ce que cela ne prouve pas
Une session vérifiée montre que ce compte Telegram détient ce numéro. Elle ne dit rien de la personne qui a la carte SIM aujourd'hui : c'est une limite commune à tout canal fondé sur un compte, comme l'explique l'article sur le SIM swap.
Le contrôle de propriété dépend aussi de l'identifiant que Telegram indique sur la fiche de contact. La documentation de la Bot API ne décrit pas comment ce champ est renseigné : ici, vous faites confiance à la plateforme, comme pour le numéro de l'expéditeur sur WhatsApp.
Il y a aussi des limites pratiques. La personne doit avoir Telegram, et une session verrouillée sur Telegram n'a pas de repli par SMS.
L'ajouter
Les sessions sont ouvertes à Telegram par défaut : il n'y a aucun paramètre à ajouter. Envoyez provider=telegram pour verrouiller une session sur le bot, ou provider=whatsapp pour l'en exclure.
curl -X POST "https://api.phone-verif.com/start-verification" \
-H "X-API-Key: $PHONE_VERIF_API_KEY"La réponse contient un bloc telegram à côté de whatsapp et sms, sauf si Telegram est indisponible. Encodez qr_code_url dans votre QR code, et utilisez direct_link pour un bouton sur mobile.
{
"whatsapp": { "...": "..." },
"sms": { "...": "..." },
"telegram": {
"qr_code_url": "https://t.phone-verif.com/tg/<token>",
"direct_link": "https://t.me/PhoneVerif_com_bot?start=<token>"
}
}Vous pouvez l'essayer sans compte sur la démo Telegram. Le guide d'intégration couvre toute l'API.