--- title: Как настроить каскад в умном шлюзе description: Практические рекомендации по настройке каскада в умном шлюзе OTP — выбор successOn, timeout, cooldown и рекомендуемые цепочки из 9 каналов --- > **For AI agents:** the complete documentation index is at [llms.txt](https://docs.mydialogi.ru/llms.txt). Append `.md` to any page URL for its markdown version. > **Коротко:** каскад настраивается в запросе. Вы указываете каналы, таймауты и статусы успеха — платформа сама переключает каналы по цепочке. ## Кому подходит - Роль: Разработчик - Уровень: Опытный ## Что это Каскад — последовательность каналов, по которым отправляется сообщение. Если один канал не дал результата — платформа переключается на следующий. Здесь — **практические рекомендации** для OTP: как выбрать параметры под задачу. Полное описание параметров — в API-разделе. **Все технические детали** (поля запроса, ограничения, значения по умолчанию) — в статье [OMNI API — отправка кодов](https://docs.mydialogi.ru/02-otp/08-api/otp-api-omni). ## Перед началом - [ ] Есть API-ключ с правами `omni-api`. - [ ] Есть имя отправителя со статусом **Активно**. - [ ] Настроен endpoint для вебхука (если нужны статусы доставки). - [ ] Вы понимаете, какие каналы будете использовать. **Доступные каналы.** В умном шлюзе доступно 9 каналов OTP. Номера для поля `channel` — в таблице [Какие каналы использовать для OTP](https://docs.mydialogi.ru/02-otp/04-channels/otp-401-which-channels). ## Два способа: один канал или каскад **Отправка через один канал — допустима.** Если одного канала достаточно для вашей задачи, каскад не обязателен. Укажите в `messages` одно сообщение — платформа отправит его по одному каналу. | Способ | Когда использовать | |---|---| | **Один канал** | Задача решается одним каналом — например, только SMS или только WhatsApp | | **Каскад** | Нужна повышенная доставляемость — если первый канал не сработал, сообщение уйдёт по следующему | ## Правило: SMS — всегда последний канал **SMS в каскаде всегда должен быть последним каналом.** SMS тарифицируется за отправку (за каждый сегмент) — независимо от того, дошло сообщение или нет. Остальные каналы тарифицируются за доставку. Поэтому ставить SMS первым или в середине цепочки — значит платить за отправку, даже если сообщение можно было доставить бесплатно через другой канал. SMS — резервный канал, который работает везде и на всех устройствах. Он должен быть последним. ## Как выбрать successOn `successOn` — статус, при котором каскад считает канал успешным и не переключается на следующий. | Значение | Когда использовать для OTP | |---|---| | `sent` | Если важна скорость, а не гарантия доставки. Платформа перейдёт дальше, как только сообщение ушло провайдеру | | `delivered` | **Стандарт для OTP.** Гарантирует, что код дошёл до устройства | | `seen` | Если нужна уверенность, что код прочитан (доступно не для всех каналов) | **`delivered` — финальный статус.** Если пришёл `delivered`, значит сообщение доставлено — статус уже не изменится. После `delivered` статус `failed` прийти не может. Поэтому для OTP рекомендуется `successOn: "delivered"` — это гарантия, что код дошёл, прежде чем каскад переключится на следующий канал. **По умолчанию `successOn` = `sent`.** Если не указать явно — платформа переключится на следующий канал, как только сообщение уйдёт провайдеру. Для OTP это слишком рано — указывайте `delivered`. ## Как выбрать timeout `timeout` — сколько секунд ждать наступления `successOn` перед переключением на следующий канал. **Для OTP скорость критична.** Пользователь ждёт код — если он не приходит за 30–60 секунд, он запросит новый. Поэтому таймаут для OTP измеряется **в секундах**, а не в минутах. **Рекомендация для OTP:** - **Начинайте с 15–30 секунд** для быстрых каналов — WhatsApp, Telegram Gateway, Mobile Push, FlashCall. - **30–60 секунд** — для SMS, RCS, TTS. - Не ставьте таймаут в минутах — пользователь не будет ждать так долго. **Технические ограничения по API:** - По умолчанию: **1200 секунд** (20 минут). - Максимум: **259 200 секунд** (72 часа). Эти значения — для API. Для OTP они слишком большие. Используйте секунды. ## Когда использовать cooldown `cooldown` — время в секундах, на которое блокируется контакт после неудачи. **Для OTP — когда нужен:** - **Контакт недоступен** (телефон выключен, номер не существует) — блокировка не даёт тратить деньги на повторные попытки до мёртвого номера. - **Защита от частых запросов** — если пользователь несколько раз подряд запрашивает код, а канал не доставляет, блокировка снижает нагрузку и расходы. **Для OTP — когда не нужен:** - **Если пользователь может запросить новый код через минуту** — жёсткий `cooldown` на 24 часа помешает ему. - **Если нужна доставка любой ценой** — блокировка не даст попробовать снова. **Рекомендация для OTP:** используйте короткий `cooldown` (например, 30–60 секунд) — чтобы избежать повторных попыток на мёртвый номер, но не блокировать пользователя надолго. ## Когда нужен sendNextAfterFail `sendNextAfterFail` — флаг, который определяет, отправлять ли следующее сообщение каскада, если **после успеха по `successOn`** приходит статус `failed`. **Флаг актуален только когда `successOn` менее строгий, чем `delivered`.** Например, если `successOn: "sent"` — платформа считает канал успешным, как только сообщение ушло провайдеру. Но провайдер может потом вернуть `failed` — сообщение не дошло. В этом случае `sendNextAfterFail = true` отправит следующее сообщение каскада. Если `successOn: "delivered"` — флаг не срабатывает: `delivered` финальный, `failed` после него не придёт. | Значение `successOn` | `sendNextAfterFail` актуален? | Когда включать | |---|---|---| | `delivered` | ❌ Нет | Не нужен — `delivered` финальный | | `seen` | ❌ Нет | Не нужен — `seen` финальный | | `sent` | ✅ Да | Включайте `true`, если хотите доставить любой ценой | **Рекомендация для OTP:** используйте `successOn: "delivered"` — тогда `sendNextAfterFail` не нужен. ## Как тарифицируется каскад **SMS тарифицируется за отправку** — за каждый сегмент. **Остальные каналы тарифицируются за доставку.** Если сообщение не доставлено — например, у получателя не установлено приложение или его нет в нужной соцсети или мессенджере — **за это сообщение деньги не списываются**. В каскаде **списание происходит только один раз** — по тому каналу, через который сообщение фактически доставлено. ## Рекомендуемые цепочки для OTP **SMS — всегда последний канал.** Все каналы в цепочках — из списка 9 каналов OTP. | Задача | Цепочка | |---|---| | **Универсальная, дешёвая** | Telegram Gateway → WhatsApp → TTS → **SMS** | | **Классическая** | TTS → **SMS** | | **Для стран с дешёвым FlashCall** | FlashCall → **SMS** | | **Для Telegram-аудитории** | Telegram Gateway → **SMS** | | **Только SMS** | **SMS** — без каскада, когда достаточно одного канала | Цепочки зависят от страны получателя: доступность каналов, скорость доставки и стоимость различаются по регионам. Для конкретной страны подбирайте цепочку с учётом этих особенностей. ## Пример: WhatsApp → TTS → SMS ```json { "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`. ## Частые проблемы ### Каскад не переключается на следующий канал **Причина:** статус, указанный в `successOn`, уже наступил. По умолчанию `successOn` = `sent` — переход не происходит. **Решение:** явно укажите `successOn: "delivered"` для каждого сообщения каскада. ### Сообщение уходит дважды **Причина:** `successOn` = `sent`, `sendNextAfterFail` = `true`, и после `sent` пришёл `failed` — платформа отправила следующее сообщение каскада. **Решение:** используйте `successOn: "delivered"` — тогда `delivered` финальный, дублирования не будет. ### Контакт заблокирован раньше времени **Причина:** `cooldown` указан на уровне сообщения — он срабатывает, если конкретное сообщение не доставлено, даже если каскад ещё продолжается. **Решение:** если блокировка нужна только после исчерпания всех каналов — указывайте `cooldown` только на верхнем уровне. ### SMS стоит не последним каналом **Причина:** SMS тарифицируется за отправку, а не за доставку. Если он в середине — платите за отправку даже при успешной доставке по другому каналу. **Решение:** ставьте SMS последним каналом в цепочке — это резерв, который работает везде. ## См. также Режим, в котором вы генерируете код Пошаговый сценарий 9 каналов OTP и их номера в API Стоимость и возможности Алгоритм выбора Полное описание параметров Каскад в массовых рассылках Общий обзор каскада Создание и управление ключами ## Нужна помощь? - **OTP-коды:** support@otpcod.ru