Come funziona la verifica telefonica su Telegram
Un bot Telegram non vede mai il numero di telefono di chi scrive, quindi verificarlo lì funziona in modo diverso da WhatsApp. Ecco il flusso, i controlli che lo sostengono e ciò che torna alla Sua applicazione.
WhatsApp è stato il primo canale di Phone-Verif, ma non tutti vivono lì. Telegram è ora un secondo canale: stessa API, stesso risultato, e attivo per impostazione predefinita. La meccanica sottostante è diversa e vale la pena comprenderla prima di offrirlo.
Su WhatsApp la prova è un messaggio inviato dalla persona: arriva dal suo numero, ed è l'idea alla base del Reverse OTP. Un bot Telegram non dispone di un segnale simile. Identifica le persone tramite un ID account numerico e il loro numero di telefono resta privato, a meno che scelgano di condividerlo. Il bot deve quindi chiederlo, e la prova deve provenire da qualcosa di diverso dal mittente.
Cosa fa la persona
Non c'è alcun codice da leggere o digitare. L'intero flusso si riduce a due tocchi dentro Telegram.
1. Aprire il link
La Sua pagina mostra un codice QR o un pulsante. Entrambi portano al nostro bot, con il token della sessione incluso nel link.
2. Premere Start
Premendo Start si consegna quel token al bot, che associa questo account Telegram alla sessione.
3. Condividere il numero
Il bot mostra un unico pulsante, «Condividi il mio numero di telefono». Toccandolo viene inviata la scheda contatto di Telegram relativa all'account.
4. Fatto
Il bot conferma, la sessione risulta verificata e la Sua applicazione riceve il webhook e il risultato di stato.
Perché un contatto condiviso vale come prova
Chiunque può inviare a un bot una sequenza di cifre, perciò i numeri digitati vengono rifiutati a priori: il bot risponde mostrando di nuovo il pulsante. Viene letta soltanto la scheda contatto, che deve superare quattro controlli prima che la sessione possa concludersi.
È il contatto della persona stessa
L'ID utente sulla scheda corrisponde all'account che la invia. La scheda di un'altra persona presa da una rubrica fallisce qui.
Proviene dall'account giusto
Il mittente è l'account che ha premuto Start in questa sessione, quindi una scheda non può completare una sessione aperta da qualcun altro.
Non è stata inoltrata
Una scheda inoltrata da un'altra chat viene rifiutata, anche se è quella del mittente stesso.
È recente
La scheda è stata inviata dopo l'apertura della sessione, quindi una vecchia scheda non può essere riproposta.
Una scheda che non supera anche solo un controllo non cambia nulla: il bot lo richiede e la sessione resta aperta. Un numero presente nella blocklist viene rifiutato su Telegram esattamente come su WhatsApp.
Ogni sessione si conclude una sola volta
Un doppio tocco sul pulsante invia due schede contatto, e una consegna ripetuta può inviare due volte la stessa. Il completamento di una sessione viene quindi acquisito in modo atomico: una sola scheda prevale e si ottengono un solo risultato, un solo webhook e un solo credito speso.
Una sessione può inoltre concludersi su un solo canale. Per impostazione predefinita è aperta a WhatsApp, SMS e al bot, e appena uno di essi la completa, gli altri rifiutano il suo token. Una sessione bloccata su Telegram o su WhatsApp rifiuta l'altro canale fin dall'inizio. Il link del bot reindirizza allo stesso modo per qualsiasi token, quindi non può servire a scoprire quali token siano attivi.
Un numero, un'identità
Telegram e WhatsApp scrivono i numeri di telefono in modo diverso, perciò il numero viene normalizzato nella stessa forma prima di ogni altra operazione. È importante perché le identità sono indicizzate su di esso.
Una persona che si verifica oggi su WhatsApp e domani su Telegram ottiene lo stesso user_id. È un solo utente, non due, e flow=login restituisce is_new_user di conseguenza.
Ci affidiamo a questo comportamento anche noi. Telegram Connect e WhatsApp Connect sulla nostra pagina di accesso portano allo stesso account per lo stesso numero, a prescindere da quale sia stato usato per primo.
Cosa viene restituito
La Sua integrazione legge la stessa risposta di stato e riceve lo stesso webhook di WhatsApp, e una verifica costa gli stessi crediti. I flussi phone, login e 2fa funzionano tutti.
Si aggiunge un solo elemento. Su flow=phone, una sessione Telegram verificata include anche un oggetto telegram con user_id, username, first_name e last_name dell'account. Login e 2FA lo omettono: rispondono con un ID utente o una corrispondenza, e un handle identificherebbe la persona proprio come un numero.
Cosa non dimostra
Una sessione verificata mostra che questo account Telegram possiede questo numero. Non dice nulla su chi abbia oggi la scheda SIM, un limite che condivide con ogni canale basato su un account, come spiega l'articolo sullo SIM swap.
Il controllo di titolarità dipende inoltre dall'ID utente che Telegram riporta sulla scheda contatto. La documentazione della Bot API di Telegram non descrive come venga compilato quel campo, quindi qui ci si affida alla piattaforma, come accade con il numero del mittente su WhatsApp.
Esistono anche limiti pratici. La persona deve avere Telegram e una sessione bloccata su Telegram non prevede un fallback via SMS.
Come aggiungerla
Le sessioni sono aperte a Telegram per impostazione predefinita, quindi non c'è alcun parametro da aggiungere. Invii provider=telegram per bloccare una sessione sul bot, oppure provider=whatsapp per escludere il bot.
curl -X POST "https://api.phone-verif.com/start-verification" \
-H "X-API-Key: $PHONE_VERIF_API_KEY"La risposta contiene un blocco telegram accanto a whatsapp e sms, a meno che Telegram non sia disponibile. Codifichi qr_code_url nel Suo codice QR e usi direct_link per un pulsante su mobile.
{
"whatsapp": { "...": "..." },
"sms": { "...": "..." },
"telegram": {
"qr_code_url": "https://t.phone-verif.com/tg/<token>",
"direct_link": "https://t.me/PhoneVerif_com_bot?start=<token>"
}
}Può provarla senza un account sulla demo di Telegram. La guida all'integrazione illustra l'API completa.