How Phone Verification Works on Telegram
A Telegram bot never sees a sender's phone number, so verifying one there works differently from WhatsApp. Here is the flow, the checks behind it, and what comes back to your application.
WhatsApp was the first channel for Phone-Verif, but not everyone lives there. Telegram is now a second one: same API, same result, and on by default. The mechanics underneath are different, and they are worth understanding before you offer it.
On WhatsApp, the proof is a message the person sends: it arrives from their number, which is the idea behind Reverse OTP. A Telegram bot has no such signal. It identifies people by a numeric account ID, and their phone number stays private unless they choose to share it. So the bot has to ask, and the proof has to come from somewhere other than the sender.
What the person does
There is no code to read or type. The whole flow is two taps inside Telegram.
1. Open the link
Your page shows a QR code or a button. Both lead to our bot with the session token carried in the link.
2. Press Start
Pressing Start hands that token to the bot, which ties this Telegram account to the session.
3. Share the number
The bot shows a single button, "Share my phone number". Tapping it sends Telegram's own contact card for the account.
4. Done
The bot confirms, the session becomes verified, and your application gets its webhook and status result.
Why a shared contact counts as proof
Anyone can send a bot a string of digits, so typed numbers are refused outright: the bot answers by showing the button again. Only a contact card is read, and it has to pass four checks before the session can complete.
It is their own contact
The user ID on the card matches the account sending it. Someone else's card from an address book fails here.
It comes from the right account
The sender is the account that pressed Start on this session, so a card cannot complete a session opened by someone else.
It was not forwarded
A card forwarded from another chat is refused, even if it is the sender's own.
It is fresh
The card was sent after the session was opened, so an old one cannot be replayed.
A card that fails any check changes nothing: the bot asks again and the session stays open. A number on the blocklist is refused on Telegram just as it is on WhatsApp.
Each session finishes once
A double tap on the button sends two contact cards, and a retried delivery can send the same one twice. Completing a session is therefore claimed atomically: one card wins, and there is one result, one webhook and one credit spent.
A session can also finish on one channel only. By default it is open to WhatsApp, SMS and the bot, and once one of them completes it, the others refuse its token. A session locked to Telegram or to WhatsApp refuses the other channel from the start. The bot link redirects the same way for any token, so it cannot be used to find out which tokens are live.
One number, one identity
Telegram and WhatsApp write phone numbers differently, so the number is normalized to the same form before anything else happens. That matters because identities are keyed on it.
A person who verifies on WhatsApp today and on Telegram tomorrow gets the same user_id. They are one user, not two, and flow=login reports is_new_user accordingly.
We rely on this ourselves. Telegram Connect and WhatsApp Connect on our own sign-in page lead to the same account for the same number, whichever one the person used first.
What comes back
Your integration reads the same status response and receives the same webhook as on WhatsApp, and a verification costs the same credits. The phone, login and 2fa flows all work.
One thing is added. On flow=phone, a verified Telegram session also carries a telegram object with the account's user_id, username, first_name and last_name. Login and 2FA leave it out: they answer with a user ID or a match, and a handle would identify the person just as a number does.
What it does not prove
A verified session shows that this Telegram account holds this number. It says nothing about who has the SIM card today, which is a limit it shares with every channel built on an account, as the SIM swap article explains.
The ownership check also depends on the user ID Telegram reports on the contact card. Telegram's Bot API documentation does not describe how that field is filled in, so here you are trusting the platform, as you are with the sender number on WhatsApp.
There are practical limits too. The person needs Telegram, and a session locked to Telegram has no SMS fallback.
Adding it
Sessions are open to Telegram by default, so there is no parameter to add. Send provider=telegram to lock a session to the bot, or provider=whatsapp to keep the bot out.
curl -X POST "https://api.phone-verif.com/start-verification" \
-H "X-API-Key: $PHONE_VERIF_API_KEY"The response carries a telegram block next to whatsapp and sms, unless Telegram is unavailable. Encode qr_code_url in your QR code, and use direct_link for a button on mobile.
{
"whatsapp": { "...": "..." },
"sms": { "...": "..." },
"telegram": {
"qr_code_url": "https://t.phone-verif.com/tg/<token>",
"direct_link": "https://t.me/PhoneVerif_com_bot?start=<token>"
}
}You can try it without an account on the Telegram demo. The integration guide covers the full API.