Smart Pass — умная верификация номера телефона в один клик

Мы запустили Smart Pass — новую услугу для верификации клиентов по номеру телефона. Она решает давнюю проблему: как подтвердить, что номер действительно принадлежит пользователю, и при этом не потерять его на полпути.

Классический путь — отправить СМС с кодом. Но у него есть минусы:

• Часть пользователей бросает ввод кода на полпути.
• СМС долго идёт, стоит денег, а иногда и не доходит.
• Мошенники используют виртуальные номера.

Smart Pass решает эти проблемы: система сама выбирает самый быстрый и незаметный способ проверки. Если оператор уже знает пользователя — верификация проходит вообще без его участия. Если нет — пользователь подтверждает вход одним касанием или вводит код из СМС. В большинстве случаев до кода дело не доходит.

Ниже — что это за услуга, сколько стоит, как подключить и какие есть подводные камни.

Smart Pass — это умная верификация по номеру телефона. Клиент вводит номер, а система запускает каскад:

1. Seamless — незаметно, если оператор уже знает пользователя.
2. Push — подтверждение в одно касание.
3. SMS-код — классический одноразовый код.

Если оператор поддерживает Seamless и пользователь в мобильной сети (не в Wi-Fi и не в VPN) — проверка проходит вообще без действий со стороны пользователя. Если нет — система автоматически переходит к отправке Push, а затем на СМС. Пользователь в худшем случае вводит код, но чаще всего обходится без этого.

Для бизнеса: выше конверсия, меньше мошенничества, один запрос вместо трёх сервисов.

Для клиента: минимум усилий — без приложений, паролей и лишних шагов.

Smart Pass можно подключить двумя способами:

Оба способа используют одни и те же методы создания задачи и проверки кода. Разница только в том, кто рисует интерфейс — вы или виджет.

Полное описание методов, полей запросов и ответов смотрите в официальной документации OpenAPI: lcab.talk-me.ru/cabinet/json-doc/sender#tag/Smartpass. Ниже — только логика, рекомендации и подводные камни.

Оплата за Smart Pass списывается только за успешно запущенную задачу — то есть когда верификация реально началась и дошла до результата. Если задача не создалась (например, номер невалидный или уже есть активная задача на этот номер) — деньги не списываются.

Стоимость не зависит от того, какой способ проверки сработал. Задача с одним Seamless, задача с Push или задача, дошедшая до СМС-кода, стоят одинаково. Вы платите за результат верификации, а не за количество задействованных методов.

Тарифы индивидуальны и зависят от объёма и условий работы. Актуальную стоимость уточняйте в личном кабинете.

Отдельно про validate: true. Если при создании задачи передать validate: true, задача не будет создана и деньги не спишутся — это режим проверки валидности номера и баланса. Удобно для тестирования интеграции.

На текущий момент Smart Pass работает только с номерами РФ. Если номер зарубежный — задача не создастся.

В будущем география может расшириться. Следите за обновлениями в личном кабинете или в документации.

Smart Pass работает по схеме «сервер-сервер». Ваш backend создаёт задачу на верификацию, получает taskId и далее узнаёт результат двумя способами:

1. Webhook — мы сами присылаем вам уведомление об изменении статуса задачи.
2. Опрос статуса — вы сами запрашиваете текущее состояние задачи.

• Создать токен можно в личном кабинете в разделе «Личный кабинет и рассылки».
• Обязательно передайте номер абонента (recipient). Без него задача не создастся.
• webhookUrl — опционален. Если не укажете — результат придётся опрашивать самостоятельно через метод получения статуса. Если укажете — мы сами будем присылать события.
• validate: true — полезно на этапе тестирования: проверяет валидность номера и наличие баланса, но задачу не создаёт и деньги не списывает.
• Одна активная задача на номер. Пока предыдущая задача в процессе — создать новую для того же номера нельзя. Это защита от спама и дублей.
• tags — используйте для фильтрации в отчётах. Например: ["2026", "Регистрация", "Промо-акция"].
• opsosAllowed / opsosDisallowed — если нужно ограничить список операторов (например, работать только с МТС).

У задачи есть несколько состояний. Полную таблицу смотрите в OpenAPI, здесь — ключевое:

• Задача сформирована — на этом этапе может появиться hheUri, который нужно «дёрнуть» со страницы пользователя, чтобы оператор связи узнал своего абонента. Это делается невидимой картинкой.
• Отправлен код — пользователю ушёл одноразовый код. Именно в этом статусе нужно вызвать проверку кода.
• Успешно — верификация пройдена.
• Ошибка — верификация не пройдена, детали придут в webhook.
• Отклонено — пользователь отказался или не подтвердил.

На этапе «задача сформирована» задача может «зависнуть» на несколько секунд, пока идёт попытка Seamless. Если она не удалась — система автоматически переходит к Push, но статус остаётся тем же.

hheUri — это ссылка, которую должен запросить браузер пользователя. Простой способ — создать невидимую картинку:

<img src="<hheUri>" style="display:none">

Подводные камни:

• hheUri приходит не для всех операторов. Мелкие региональные операторы Seamless не поддерживают — сразу идёт Push.
• Даже если hheUri пришёл — проверка может не пройти, если пользователь в Wi-Fi или VPN. Это нормально: система продолжит каскад и отправит Push.
• Не блокируйте интерфейс, пока hheUri «дёргается». Это фоновая операция.

• Проверка производится с помощью метода /smartpass/sendCode
• Обязательно передайте code — код, который пользователь получил в СМС.
• Обязательно передайте taskId — идентификатор задачи, который вы получили при создании.
• Вызывайте проверку кода только в статусе «отправлен код». В других статусах вернётся ошибка.
• Если задача просрочена — вернётся expired. Нужно создать новую задачу.
• Если пользователь исчерпал попытки ввода — вернётся access_denied. Нужно создать новую задачу.

Если вы указали webhookUrl при создании задачи, мы будем присылать на него POST с JSON-телом при каждом изменении статуса.

Что важно:

• Ваш обработчик должен всегда возвращать 200 OK. Тело ответа не важно.
• Обрабатывайте события идемпотентно: одно и то же событие может прийти дважды.
• Не полагайтесь только на webhook — если ваш сервер был недоступен, событие может потеряться. Для критичных сценариев дублируйте опросом статуса.
• Формат тела и список возможных действий (action) смотрите в OpenAPI.

Логика обработки событий:

Готовый UI-компонент, который закрывает весь сценарий верификации: показывает лоадер, поле ввода кода, результат. Вам не нужно самостоятельно рисовать интерфейс и вызывать проверку кода — виджет сделает это сам.

Подходит, если вы хотите встроить верификацию на сайт «в одну строку».

Виджет использует внутренний comet-канал и не обращается к вашему API. Единственное, что ему нужно — taskId, который вы создаёте на своём backend.

Важно: виджет не вызывает ваш API проверки кода. Если вы используете виджет, webhookUrl не нужен — виджет сам знает результат.

html

<script src="https://lcab.talk-me.ru/support/smartpass.js"></script>

html

<div id="smart-pass"></div>

Ваш backend создаёт задачу и возвращает taskId на фронт.

html

<script>
SmartPass({
    taskId: "4a7c3854e35faf15f72e2144d6998121",
    container: "#smart-pass",
    onSuccess: () => {
        alert("Номер успешно проверен!");
    },
    onError: (error) => {
        alert(error);
    }
});
</script>

1. Лоадер — пока идёт проверка.
2. Если доступен Seamless — проверка проходит незаметно, пользователь сразу видит успех.
3. Если нужен код — виджет показывает поле ввода и кнопку «Отправить».
4. Успех — галочка и сообщение «Проверка номера телефона пройдена успешно».
5. Ошибка — сообщение «Не удалось проверить номер телефона».

• Одна активная задача на номер — пока предыдущая задача не завершена, создать новую для того же номера нельзя.
• Один виджет на страницу — технически можно смонтировать несколько, но практического смысла нет.
• Закрытие страницы прерывает проверку — если пользователь ушёл со страницы, процесс не завершится. При возврате придётся начать заново.
• Мобильные браузеры поддерживаются.
• Ограничений по домену нет — виджет можно грузить с любого сайта.

Виджет работает через widget.me-talk.ru и не требует X-Token. taskId — единственный идентификатор, который нужен фронту.

Что если номер не поддерживается оператором?
Система попробует Seamless, затем Push, затем СМС. Если ни один способ не сработал — задача завершится со статусом «ошибка», детали придут в webhook.

Что если пользователь закрыл страницу?
Проверка прерывается. При возврате придётся создать новую задачу и начать заново.

Что если пользователь не ввёл код?
Задача завершится по таймауту со статусом «ошибка». Детали — в webhook.

Можно ли создать вторую задачу для того же номера?
Нет. Пока первая задача активна, вторая не создастся — вернётся ошибка.

Нужен ли webhookUrl, если я использую виджет?
Нет. Виджет сам знает результат и вызовет onSuccess / onError. webhookUrl нужен только для server-to-server сценариев без виджета.

Какой способ интеграции выбрать?
Если хотите быстро и без своего UI — выбирайте виджет. Если нужен полный контроль над интерфейсом и логикой — используйте API напрямую.

Что делать с hheUri?
«Дёрнуть» его со страницы пользователя невидимой картинкой. Если пользователь в Wi-Fi или VPN — проверка может не пройти, это нормально: система продолжит каскад.

Есть ли ограничения по домену для виджета?
Нет, виджет можно грузить с любого сайта.

Что если пользователь использует VPN?
Seamless может не сработать. Система автоматически перейдёт к Push или СМС.

Где смотреть полное описание методов?
В официальной документации OpenAPI: lcab.talk-me.ru/cabinet/json-doc/sender#tag/Smartpass.

Сколько стоит Smart Pass?
Оплата списывается только за успешно запущенную задачу. Стоимость не зависит от того, какой способ проверки сработал — Seamless, Push или СМС. Актуальные тарифы — в личном кабинете.

Работает ли Smart Pass с зарубежными номерами?
Пока нет — услуга доступна только для номеров РФ. Если номер зарубежный, задача не создастся.