Как работает верификация телефона в Telegram
Бот Telegram никогда не видит номер телефона отправителя, поэтому верификация там устроена иначе, чем в WhatsApp. Вот сам процесс, проверки за ним и то, что возвращается в ваше приложение.
WhatsApp был первым каналом Phone-Verif, но не все пользуются именно им. Теперь Telegram стал вторым каналом: тот же API, тот же результат, и он включён по умолчанию. Механика под капотом другая, и стоит разобраться в ней, прежде чем предлагать этот канал.
В WhatsApp доказательством служит сообщение, которое отправляет сам человек: оно приходит с его номера, и на этом построен Reverse OTP. У бота Telegram такого сигнала нет. Он идентифицирует людей по числовому идентификатору аккаунта, а их номер телефона остаётся приватным, пока они сами не решат им поделиться. Поэтому боту приходится спрашивать, а доказательство должно прийти не от самого отправителя.
Что делает человек
Не нужно читать или вводить код. Весь процесс — два нажатия внутри Telegram.
1. Откройте ссылку
На вашей странице показан QR-код или кнопка. Оба ведут к нашему боту, а токен сессии передаётся в ссылке.
2. Нажмите «Запустить»
Нажатие передаёт этот токен боту, и он связывает аккаунт Telegram с сессией.
3. Поделитесь номером
Бот показывает одну кнопку: «Поделиться номером телефона». По нажатию отправляется собственная карточка контакта Telegram для этого аккаунта.
4. Готово
Бот подтверждает результат, сессия становится верифицированной, а ваше приложение получает webhook и результат статуса.
Почему переданный контакт считается доказательством
Любой может отправить боту набор цифр, поэтому введённые вручную номера сразу отклоняются: бот снова показывает кнопку. Читается только карточка контакта, и перед завершением сессии она должна пройти четыре проверки.
Это собственный контакт
Идентификатор пользователя на карточке совпадает с аккаунтом, который её отправляет. Чужая карточка из адресной книги здесь не пройдёт.
Она пришла с нужного аккаунта
Отправитель — это аккаунт, нажавший «Запустить» в этой сессии, поэтому карточка не может завершить сессию, открытую кем-то другим.
Она не была переслана
Карточка, пересланная из другого чата, отклоняется, даже если это контакт самого отправителя.
Она свежая
Карточка отправлена после открытия сессии, поэтому старую карточку нельзя использовать повторно.
Карточка, не прошедшая любую из проверок, ничего не меняет: бот спрашивает снова, а сессия остаётся открытой. Номер из чёрного списка отклоняется в Telegram так же, как и в WhatsApp.
Каждая сессия завершается один раз
Двойное нажатие на кнопку отправляет две карточки контакта, а повторная доставка может отправить одну и ту же дважды. Поэтому завершение сессии захватывается атомарно: побеждает одна карточка, и результат один — один webhook и один списанный кредит.
Кроме того, сессию можно завершить только в одном канале. По умолчанию она открыта для WhatsApp, SMS и бота, и как только один из них её завершает, остальные отклоняют её токен. Сессия, закреплённая за Telegram или WhatsApp, отклоняет другой канал с самого начала. Ссылка на бота перенаправляет одинаково для любого токена, поэтому по ней нельзя выяснить, какие токены действуют.
Один номер — одна личность
Telegram и WhatsApp записывают номера телефонов по-разному, поэтому номер приводится к единому виду, прежде чем что-либо произойдёт. Это важно, потому что по нему строятся идентификаторы.
Человек, который сегодня проходит верификацию в WhatsApp, а завтра в Telegram, получает один и тот же user_id. Это один пользователь, а не два, и flow=login сообщает is_new_user соответственно.
Мы и сами на это полагаемся. Telegram Connect и WhatsApp Connect на нашей странице входа ведут к одному и тому же аккаунту для одного и того же номера, каким бы способом человек ни воспользовался первым.
Что возвращается
Ваша интеграция читает тот же ответ со статусом и получает тот же webhook, что и в WhatsApp, а верификация стоит столько же кредитов. Все сценарии phone, login и 2fa работают.
Добавляется одна вещь. В flow=phone верифицированная сессия Telegram содержит ещё и объект telegram с полями аккаунта user_id, username, first_name и last_name. В login и 2FA его нет: они отвечают идентификатором пользователя или совпадением, а имя пользователя идентифицирует человека так же, как и номер.
Чего это не доказывает
Верифицированная сессия показывает, что этот аккаунт Telegram владеет этим номером. Она ничего не говорит о том, у кого сегодня находится SIM-карта, и это ограничение общее для всех каналов, построенных на аккаунтах, как объясняет статья о SIM swap.
Проверка владения также зависит от идентификатора пользователя, который Telegram сообщает в карточке контакта. В документации Bot API Telegram не описано, как заполняется это поле, поэтому здесь вы доверяете платформе, как доверяете номеру отправителя в 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 описан в руководстве по интеграции.