IBA Platform logo

Настройка каскада в Multi API

Каскад в Multi API — эндпоинт /omnimessages, параметры successOn, timeout, cooldown, полный curl-пример

Коротко: каскад настраивается в запросе через эндпоинт /omnimessages. Вы указываете каналы, таймауты и статусы успеха.

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

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

Что это

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

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

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

  • У вас есть API-ключ с правами omni-api.
  • У вас есть имя отправителя со статусом Активно для каждого канала в цепочке.
  • Вы знакомы с форматами payload — Форматы payload по каналам →.

Эндпоинт

URL: https://web.multiapi.ru/api/v1/omnimessages

Метод: POST

Параметры запроса

ПолеТипОбязательноЧто указать
contactstringДаНомер получателя с кодом страны, без «+»
messagesarrayДаМассив сообщений — по объекту на каждый канал каскада
webhookstringНетURL для приёма статусов
isOtpbooleanНетtrue — если сообщение содержит одноразовый код
cooldownintegerНетСекунды блокировки контакта при неудаче всего каскада. По умолчанию отключено. Максимум 86400 (1 день)
sendNextAfterFailbooleanНетОтправлять ли следующее сообщение при статусе failed после наступления successOn. По умолчанию false

Поля внутри элемента messages

ПолеТипОбязательноЧто указать
channelintegerДаНомер канала
senderIdstringДаИмя отправителя для этого канала
successOnstringНетСтатус успеха: sent, delivered, seen. По умолчанию sent
timeoutintegerНетСекунды ожидания successOn. По умолчанию 1200 (20 минут). Максимум 259200 (3 дня)
payloadobjectДа*Содержимое сообщения
templateobjectДа*Содержимое шаблона: id и params
clientInfostringНетПроизвольное поле, сохраняется в EDR
cooldownintegerНетСвой cooldown для этого шага — переопределяет значение верхнего уровня
ttlintegerНетВремя жизни сообщения

*- нужен либо payload, либо template.

successOn по умолчанию — sent. Если не указать successOn явно, платформа переключится на следующий канал, как только сообщение уйдёт провайдеру. Чтобы гарантировать доставку — укажите successOn: "delivered".

Пример запроса

Каскад RCS → SMS:

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": "<senderID_RCS>",
        "successOn": "delivered",
        "timeout": 60,
        "payload": {
          "RCSMessage": {
            "textMessage": "Ваш код: 1234"
          }
        }
      },
      {
        "channel": 1,
        "senderId": "<senderID_SMS>",
        "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 дороже остальных.

Рекомендуемые цепочки по задачам — в статье Что такое каскад →.

Актуальные цены по каналам, странам и операторам — в разделе Тарифы →.

Результат

Каскад настроен. Платформа будет автоматически переключаться между каналами по заданным правилам.

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

Причина: статус, указанный в successOn, уже наступил. По умолчанию successOn = sent, поэтому переход не происходит.

Решение: явно укажите successOn: "delivered" для каждого сообщения каскада.

Причина: маленький timeout.

Решение: увеличьте значение — например, для WhatsApp до 600 секунд, для SMS до 900 секунд.

Причина: неверный статус успеха — например, sent вместо delivered.

Решение: проверьте successOn для каждого шага.

Статусы сообщений →

Причина: имя отправителя для какого-то канала не привязано к API-ключу.

Решение: откройте ключ в разделе API Подключения и добавьте нужные имена.

Как создать API-ключ →

Причина: неверный или отсутствующий API-ключ.

Решение: проверьте заголовок X-API-Key.

Ошибка 401 →

См. также

Какие каналы доступны

13 каналов Multi API с номерами

Как выбрать канал

Что подходит для вашей задачи

OMNI API — отправка

Эндпоинты /messages и /omnimessages

Статусы сообщений

Push и pull — два способа получения

Форматы payload

JSON-примеры для каждого канала

Что такое каскад

Логика и рекомендуемые цепочки

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