--- title: Настройка каскада в Multi API description: Каскад в Multi API — эндпоинт /omnimessages, параметры successOn, timeout, cooldown, полный curl-пример --- > **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. > **Коротко:** каскад настраивается в запросе через эндпоинт `/omnimessages`. Вы указываете каналы, таймауты и статусы успеха. ## Кому подходит - Роль: Разработчик - Уровень: Опытный ## Что это **Каскад** — способ отправки сообщения, при котором платформа автоматически переключается на следующий канал, если сообщение не доставлено по предыдущему. Последовательность каналов, таймауты и статусы успеха задаются **в запросе** — без настройки в интерфейсе. ## Перед началом - [ ] У вас есть API-ключ с правами `omni-api`. - [ ] У вас есть имя отправителя со статусом **Активно** для каждого канала в цепочке. - [ ] Вы знакомы с форматами `payload` — [Форматы payload по каналам →](https://iba-platform.jamdesk.app/03-multiapi/02-api/mapi-104-omni-payload). ## Эндпоинт **URL:** `https://web.multiapi.ru/api/v1/omnimessages` **Метод:** `POST` ## Параметры запроса | Поле | Тип | Обязательно | Что указать | |---|---|---|---| | `contact` | string | Да | Номер получателя с кодом страны, без «+» | | `messages` | array | Да | Массив сообщений — по объекту на каждый канал каскада | | `webhook` | string | Нет | URL для приёма статусов | | `isOtp` | boolean | Нет | `true` — если сообщение содержит одноразовый код | | `cooldown` | integer | Нет | Секунды блокировки контакта при неудаче всего каскада. По умолчанию отключено. Максимум **86400** (1 день) | | `sendNextAfterFail` | boolean | Нет | Отправлять ли следующее сообщение при статусе `failed` после наступления `successOn`. По умолчанию `false` | ### Поля внутри элемента `messages` | Поле | Тип | Обязательно | Что указать | |---|---|---|---| | `channel` | integer | Да | Номер канала | | `senderId` | string | Да | Имя отправителя для этого канала | | `successOn` | string | Нет | Статус успеха: `sent`, `delivered`, `seen`. По умолчанию **`sent`** | | `timeout` | integer | Нет | Секунды ожидания `successOn`. По умолчанию **1200** (20 минут). Максимум **259200** (3 дня) | | `payload` | object | Да* | Содержимое сообщения | | `template` | object | Да* | Содержимое шаблона: `id` и `params` | | `clientInfo` | string | Нет | Произвольное поле, сохраняется в EDR | | `cooldown` | integer | Нет | Свой cooldown для этого шага — переопределяет значение верхнего уровня | | `ttl` | integer | Нет | Время жизни сообщения | > *- нужен либо `payload`, либо `template`. **`successOn` по умолчанию — `sent`.** Если не указать `successOn` явно, платформа переключится на следующий канал, как только сообщение уйдёт провайдеру. Чтобы гарантировать доставку — укажите `successOn: "delivered"`. ## Пример запроса **Каскад RCS → SMS:** ```bash curl --location 'https://web.multiapi.ru/api/v1/omnimessages' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <ваш-ключ>' \ --data-raw '{ "contact": "905063565285", "webhook": "https://ваш-сайт.com/webhook", "isOtp": true, "cooldown": 86400, "messages": [ { "channel": 2, "senderId": "", "successOn": "delivered", "timeout": 60, "payload": { "RCSMessage": { "textMessage": "Ваш код: 1234" } } }, { "channel": 1, "senderId": "", "payload": { "text": "Ваш код: 1234" } } ] }' ``` **Что произойдёт:** 1. Платформа отправит сообщение по RCS. 2. Будет ждать статус `delivered` в течение **60 секунд**. 3. Если статус не получен — переключится на SMS. **Если RCS сразу вернёт статус `failed` или `undeliverable`** — SMS отправится **немедленно**, без ожидания таймаута. ## Статусы успеха | Статус | Что означает | |---|---| | `sent` | Отправлено провайдеру | | `delivered` | Доставлено на устройство получателя | | `seen` | Просмотрено (доступно не во всех каналах) | ## Таймаут Сколько ждать `successOn` перед переходом на следующий канал. - **По умолчанию** — 1200 секунд (20 минут). - **Максимум** — 259200 секунд (72 часа). ## Cooldown Сколько блокировать контакт при неудаче всего каскада. - **По умолчанию** — отключено. - **Максимум** — 86400 секунд (24 часа). **Cooldown можно указать на двух уровнях:** - **Верхний уровень** — блокировка действует для всего каскада. - **Уровень сообщения** — переопределяет значение для конкретного шага. Пример: общий `cooldown: 86400` на весь каскад, но для SMS-шага — свой `cooldown: 3600`. ## Мгновенный переход Если от провайдера приходит статус, что абонент **недоступен**, **номер не существует** или **сообщение отклонено** — переход на следующий канал происходит **немедленно**, без ожидания таймаута. ## Экономия бюджета **Начинайте с дешёвого канала, заканчивайте дорогим.** Если сообщение доставлено по первому каналу — остальные не отправляются. Так вы сокращаете расходы. **SMS — самый дорогой канал.** Остальные каналы дешевле. **Как строить цепочку:** - Первым ставьте **дешёвый канал** — если он сработает, дорогой не понадобится. - Последним ставьте **дорогой канал** — как резерв на случай, если дешёвые не сработали. **Конечная стоимость зависит от:** - **Страны** отправки сообщения. - **Оператора** получателя. - **Канала** — SMS дороже остальных. Рекомендуемые цепочки по задачам — в статье [Что такое каскад →](https://iba-platform.jamdesk.app/05-channels/00-overview/cascade). Актуальные цены по каналам, странам и операторам — в разделе [Тарифы →](https://iba-platform.jamdesk.app/06-reference/02-pricing/pricing-overview). ## Результат Каскад настроен. Платформа будет автоматически переключаться между каналами по заданным правилам. - [Как выбрать канал →](https://iba-platform.jamdesk.app/03-multiapi/03-channels/mapi-202-channel-choice) - [OMNI API — отправка →](https://iba-platform.jamdesk.app/03-multiapi/02-api/mapi-103-omni-api) - [Что такое каскад →](https://iba-platform.jamdesk.app/05-channels/00-overview/cascade) ## Частые проблемы ### Каскад не переключается на следующий канал **Причина:** статус, указанный в `successOn`, уже наступил. По умолчанию `successOn` = `sent`, поэтому переход не происходит. **Решение:** явно укажите `successOn: "delivered"` для каждого сообщения каскада. ### Переключается слишком рано **Причина:** маленький `timeout`. **Решение:** увеличьте значение — например, для WhatsApp до 600 секунд, для SMS до 900 секунд. ### Сообщение дублируется **Причина:** неверный статус успеха — например, `sent` вместо `delivered`. **Решение:** проверьте `successOn` для каждого шага. [Статусы сообщений →](https://iba-platform.jamdesk.app/03-multiapi/02-api/mapi-106-api-statuses) ### 400 Bad Request: sender not found **Причина:** имя отправителя для какого-то канала не привязано к API-ключу. **Решение:** откройте ключ в разделе **API Подключения** и добавьте нужные имена. [Как создать API-ключ →](https://iba-platform.jamdesk.app/06-reference/01-api/api-keys) ### 401 Unauthorized **Причина:** неверный или отсутствующий API-ключ. **Решение:** проверьте заголовок `X-API-Key`. [Ошибка 401 →](https://iba-platform.jamdesk.app/06-reference/03-troubleshooting/ts-mapi-401) ## См. также 13 каналов Multi API с номерами Что подходит для вашей задачи Эндпоинты /messages и /omnimessages Push и pull — два способа получения JSON-примеры для каждого канала Логика и рекомендуемые цепочки ## Нужна помощь? - **Multi API:** support@multiapi.ru