Каскадная доставка OTP (каскад, fallback)

Каскадная доставка (каскад, fallback) — стратегия верификации, при которой подтверждение отправляют пользователю по нескольким каналам по очереди: если первый канал не довёл результат, система переходит к следующему. Классическая цепочка — Telegram → звонок → SMS: канал меняют до первого успеха, чтобы поднять доходимость и не переплачивать.

Зачем нужен каскад: доходимость и экономия

Ни один канал не доставляет 100%: у пользователя может не быть Telegram, обратный флеш-колл — не пройти, а SMS — задержаться у оператора. Каскад решает это сразу с двух сторон: повышает доходимость (шанс, что хотя бы один канал сработает) и помогает экономить — недорогие каналы закрывают основную массу трафика, а дорогой запасной подключается только при неудаче. Порядок каналов вы задаёте сами под свою аудиторию.

Пример цепочки каналов

Как собрать каскад через API: по шагам

В Verificahub нет параметра «каскад» — цепочку вы оркеструете на своей стороне, вызывая POST /v1/verify по одному методу за раз и переключая канал по исходу.

1. Вызовите POST /v1/verify с первым method (например telegram_otp).
2. Дождитесь исхода: для telegram_otp проверьте код через POST /v1/verify/check, а reverse_flash_call подтверждается автоматически по Caller ID — код никто не вводит.
3. Если при создании пришла ошибка доставки (delivery_unavailable, no_gateway_available) или сессия завершилась статусом expired/failed, повторите POST /v1/verify со следующим method.
4. Исход ловите вебхуками verification.verified / verification.expired / verification.failed, а не опросом по таймеру.

// Каскад оркеструется на вашей стороне: одна сессия — один method.
// Секрет используем только на сервере (server-to-server).
const channels = ['telegram_otp', 'reverse_flash_call']; // порядок — под вашу аудиторию

async function startCascade(phone) {
  const auth = 'Basic ' + Buffer.from(`${API_KEY}:${API_SECRET}`).toString('base64');

  for (const method of channels) {
    const res = await fetch('https://api.verificahub.ru/v1/verify', {
      method: 'POST',
      headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
      body: JSON.stringify({ phone_number: phone, method })
    });

    if (res.status === 201) {
      // Сессия создана: telegram_otp проверяем через /v1/verify/check,
      // reverse_flash_call подтверждается сам по Caller ID. Исход ловим вебхуком.
      return res.json();
    }

    const err = await res.json();
    // Меняем канал только на ошибках доставки. Остальное сменой канала не лечится.
    if (!['delivery_unavailable', 'no_gateway_available'].includes(err.error_code)) {
      throw new Error(err.error_code);
    }
  }
  throw new Error('all_channels_failed');
}

Каскад в Verificahub: одна сессия — один метод

Важно и честно: в API Verificahub одна сессия привязана к одному методу — единого параметра «каскад» нет, список каналов в один запрос не передаётся. Каскад вы оркеструете на своей стороне: вызываете POST /v1/verify с первым method, а если пришла ошибка доставки (delivery_unavailable, no_gateway_available) или сессия завершилась статусом expired/failed, делаете новый вызов /v1/verify со следующим методом. Отслеживать неудачу удобнее по вебхукам verification.expired / verification.failed, а не по таймерам. Готовую цепочку по шагам разбираем в гайде Каскадная доставка OTP. Плюс биллинга «оплата за результат»: неуспешные шаги каскада не тарифицируются — вы платите только за тот канал, который довёл верификацию до конца.