Как настроить каскад в умном шлюзе

Коротко: каскад настраивается в запросе. Вы указываете каналы, таймауты и статусы успеха — платформа сама переключает каналы по цепочке.

Кому подходит

• Роль: Разработчик
• Уровень: Опытный

Что это

Каскад — последовательность каналов, по которым отправляется сообщение. Если один канал не дал результата — платформа переключается на следующий.

Здесь — практические рекомендации для OTP: как выбрать параметры под задачу. Полное описание параметров — в API-разделе.

Перед началом

• Есть API-ключ с правами omni-api.
• Есть имя отправителя со статусом Активно.
• Настроен endpoint для вебхука (если нужны статусы доставки).
• Вы понимаете, какие каналы будете использовать.

Два способа: один канал или каскад

Правило: SMS — всегда последний канал

Как выбрать successOn

successOn — статус, при котором каскад считает канал успешным и не переключается на следующий.

Как выбрать timeout

timeout — сколько секунд ждать наступления successOn перед переключением на следующий канал.

Рекомендация для OTP:

• Начинайте с 15–30 секунд для быстрых каналов — WhatsApp, Telegram Gateway, Mobile Push, FlashCall.
• 30–60 секунд — для SMS, RCS, TTS.
• Не ставьте таймаут в минутах — пользователь не будет ждать так долго.

Когда использовать cooldown

cooldown — время в секундах, на которое блокируется контакт после неудачи.

Для OTP — когда нужен:

• Контакт недоступен (телефон выключен, номер не существует) — блокировка не даёт тратить деньги на повторные попытки до мёртвого номера.
• Защита от частых запросов — если пользователь несколько раз подряд запрашивает код, а канал не доставляет, блокировка снижает нагрузку и расходы.

Для OTP — когда не нужен:

• Если пользователь может запросить новый код через минуту — жёсткий cooldown на 24 часа помешает ему.
• Если нужна доставка любой ценой — блокировка не даст попробовать снова.

Рекомендация для OTP: используйте короткий cooldown (например, 30–60 секунд) — чтобы избежать повторных попыток на мёртвый номер, но не блокировать пользователя надолго.

Когда нужен sendNextAfterFail

sendNextAfterFail — флаг, который определяет, отправлять ли следующее сообщение каскада, если после успеха по successOn приходит статус failed.

Рекомендация для OTP: используйте successOn: "delivered" — тогда sendNextAfterFail не нужен.

Как тарифицируется каскад

Рекомендуемые цепочки для OTP

SMS — всегда последний канал. Все каналы в цепочках — из списка 9 каналов OTP.

Пример: WhatsApp → TTS → SMS

{
  "contact": "79991234567",
  "isOtp": true,
  "webhook": "https://your-site.com/webhook",
  "cooldown": 60,
  "messages": [
    {
      "channel": 4,
      "senderId": "<имя отправителя WhatsApp>",
      "successOn": "delivered",
      "timeout": 30,
      "payload": {
        "text": "Ваш код: 1234"
      }
    },
    {
      "channel": 11,
      "senderId": "<имя отправителя TTS>",
      "successOn": "delivered",
      "timeout": 45,
      "payload": {
        "text": "Ваш код 1234",
        "language": "ru",
        "repeat_count": 1
      }
    },
    {
      "channel": 1,
      "senderId": "<имя отправителя SMS>",
      "payload": {
        "text": "Ваш код: 1234"
      }
    }
  ]
}

Что происходит:

1. Платформа отправляет сообщение по WhatsApp и ждёт delivered 30 секунд.
2. Если статус получен — каскад завершён. Статус delivered финальный.
3. Если не получен — переход на TTS, ожидание delivered 45 секунд.
4. Если не получен — переход на SMS — последний канал цепочки.
5. Если SMS тоже не доставлено — контакт блокируется на 60 секунд (cooldown на верхнем уровне).

Мгновенный переход

Если от провайдера приходит статус «абонент недоступен», «номер не существует» или «отклонено» — платформа переключается на следующий канал немедленно, без ожидания таймаута.

Результат

Сообщение отправлено по каскаду. Вы получаете статусы доставки на указанный вебхук или запрашиваете их через GET /edrs.

Частые проблемы

См. также

Нужна помощь?

• OTP-коды: support@otpcod.ru