Как работают потоки подтверждения
Общая схема одна для всех методов: POST /v1/verify создаёт сессию, а результат вы узнаёте либо по
вебхуку, либо опрашивая GET /v1/verify/{request_id}. Отличается только середина —
то, как пользователь проходит подтверждение.
Статусы сессии: sent → delivered (необязательный) → verified, либо expired (истёк TTL) /
failed (терминальная ошибка).
Какой метод выбрать
Главный вопрос — нужно ли вам поле ввода кода.
| Без ввода кода | С вводом кода |
|---|---|
reverse_flash_call — пользователь звонит сам | sms · flash_call · pass_call |
mts_id — подтверждение на SIM, но с откатом на код | telegram_otp · max_otp · max_bot |
Какие методы доступны вашему аккаунту и сколько стоят — см. Методы подтверждения и тарифы.
reverse_flash_call — без ввода кода
Пользователь сам звонит на выданный номер, мы подтверждаем по Caller ID. Код никто не вводит.
→ Подробнее про reverse_flash_call
sms — код в SMS
Код приходит пользователю по SMS; он вводит его у вас, вы отправляете на проверку. Та же схема
«код → /v1/verify/check → verified» работает и у остальных методов с вводом кода.
flash_call — код из номера входящего звонка
Мы делаем звонок-сброс, и код — последние code_length цифр входящего номера. Пользователь
считывает их с экрана.
pass_call — робот диктует код голосом
Робот звонит и проговаривает код. В отличие от flash_call, на звонок нужно ответить.
telegram_otp — код из Telegram
Код доставляет официальный бот Telegram.
max_otp — код в мессенджере MAX
Сообщение приходит само, без ссылок и действий со стороны пользователя.
max_bot — код через бота в MAX
Пользователь открывает бота по deep_link и жмёт «Поделиться номером» — код приходит только после
этого. Списание — по факту доставки.
mts_id — подтверждение через оператора
Два пути, и заранее не известно, какой сработает: обычно оператор подтверждает прямо на SIM, но при
неудаче происходит откат на SMS-OTP. Не показывайте поле ввода кода сразу — ждите вебхук
verification.code_required или флаг awaiting_code: true.
Узнать результат: вебхук или опрос
Оба способа рабочие, и их можно комбинировать (вебхук как основной, опрос — как страховка):
- Вебхук — мы сами присылаем событие на ваш URL (см. Вебхуки).
- Опрос — периодически запрашивайте
GET /v1/verify/{request_id}до терминального статуса.
Источник истины при расхождениях — GET /v1/verify/{request_id}.