# Каскадная отправка Каскадной отправкой называется технология переотправки сообщения по различным каналам. Последовательность каналов задается последовательностью объектов сообщений в массиве `cascade`– первое сообщение формируется сразу, следующие сообщения последовательно формируются и отправляются в случае неполучения статуса "Доставлено" или "Прочитано" предыдущим сообщением в течение его времени жизни. ## Отправка каскадных сообщений `POST` `https://direct.i-dgtl.ru/api/v1/message/cascade` Метод позволяет отправить массив каскадных сообщений **(от 1 до 1000)** #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------ | | Authorization\* | string | `Basic {TOKEN_1}` | | Content-Type\* | string | `application/json` | #### Request Body | Name | Type | Description | | ----------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | destination\* | string | Номер абонента | | tags | array |

Теги сообщения (массив строк).
Каждый тег должен соответствовать выражению ^\w+$ (допускаются буквы в любом регистре, цифры и нижнее подчеркивание "\_")

| | useLocalTime | boolean |

Флаг, отвечающий за таймзону, в которой будет отправлено сообщение:
true – отправка в таймзоне абонента
false – отправка по МСК
По умолчанию true

| | localSendTime | string |

Желаемое время отправки первого сообщения каскада (с учетом значения useLocalTime)
Дата в формате YYYY-MM-DD hh:mm:ss в диапазоне от (текущее время в UTC - 12 часов) до (текущее время в UTC + 7 дней)
По умолчанию сообщение будет отправлено сразу

| | localCompletionTime | string | Верхняя граница допустимого времени отправки сообщения (с учетом `useLocalTime`) в диапазоне от `localSendTime` до (текущее время в UTC + 70 дней) | | hours | array | Допустимые часы отправки (массив чисел). В массиве могут быть переданы целые числа от 0 до 23, каждое из которых соответствует разрешенному для отправки часовому интервалу с учетом `useLocalTime` | | days | array | Допустимые дни отправки (массив чисел). В массиве могут быть переданы целые числа от 1 (пн) до 7 (вс), каждое из которых соответствует разрешенному для отправки дню недели с учетом `useLocalTime` | | shortUrl | boolean |

Флаг, отвечающий за сокращение ссылок в сообщении:
true- ссылки в текстах сообщений будут сокращены
По умолчанию false

| | callbackUrl | string | Адрес для отправки callback | | callbackEvents | array | События, по которым будет отправлен callback (массив строк). При наличии `callbackUrl` и отсутствии `callbackEvents` в запросе, будет отправлен callback по событию `delivered` | | cascade\* | array | Массив с объектами сообщений; может содержать от 2 до 11 объектов включительно. | | cascade.channelType\* | string | Канал трафика сообщения | | cascade.senderName\* | string |

Имя отправителя; допустимые значения зависят от канала:
SMS: допускаются sms-отправители в статусе "Одобрено" с датой начала действия не позднее, чем время отправки запроса
VIBER: допускаются viber-отправители в статусе "Одобрено" с датой начала действия не позднее, чем время отправки запроса
VK, FLASHCALL, TEXT\_TO\_SPEECH: допускается любая строка
VOICECODE: необходимо отправлять значение voicecode

| | cascade.content\* | object | Содержимое сообщения; допустимые значения зависят от канала и описаны ниже | | cascade.condition | string |

Условие отправки следующего сообщения
По умолчанию – not\_delivered

| | cascade.ttl | string |

Время жизни сообщения в секундах. По истечении ttl: данному сообщению будет присвоен финальный статус, а также при выполнении cascade.condition будет создано следующее сообщение.
30 ≤ ttl ≤ 86400
По умолчанию время жизни сообщения составляет 25 часов

| {% tabs %} {% tab title="200" %} В случае успешного запроса возвращается ответ, в котором перечислены идентификаторы сообщений (в том числе ваши, если были переданы) и коды результата. При значении errors = false гарантируется, что все переданные сообщения успешно созданы. ``` { "errors": false, "items": [ { "messageUuid": "063474ec-a34f-4558-90c5-984395000004", "externalMessageId": "id123", "code": 201 }, { "messageUuid": "063564ec-a34f-4558-90c5-984395000005", "externalMessageId": "id124", "code": 201 } ] } ``` {% endtab %} {% tab title="401" %} Использование невалидного токена / отсутствие заголовка авторизации. ``` { "error": { "code": 4010, "msg": "Not Authenticated" } } ============================================= { "error": { "code": 4012, "msg": "Bad credentials" } } ``` {% endtab %} {% tab title="402" %} Недостаточно средств на балансе. ``` { "error": { "code": 402, "msg": "Insufficient funds" } } ``` {% endtab %} {% tab title="403" %} Использование неподходящего токена. ``` { "error": { "code": 4030, "msg": "Access Denied" } } ``` {% endtab %} {% tab title="422" %} Невалидные параметры в теле запроса или превышение максимального количества объектов. 
// Превышение количества сообщений
{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localSendTime
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localSendTime
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localCompletionTime
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localCompletionTime
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение senderName
{
    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение destination
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение content
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение tags
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение ttl
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение hours
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение days
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}
{% endtab %} {% endtabs %} {% hint style="warning" %} Рекомендуемое время ожидания ответа: 70 секунд.\ Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки. {% endhint %} {% hint style="info" %} Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку {% endhint %} Возможные варианты перечислений: | Параметр | Варианты | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | callbackEvents | [События для отправки callback](/extra/references.md#callback-events) | | cascade.channelType | | | cascade.condition | [Условия формирования каскадных сообщений](/extra/references.md#cascade-conditions) | {% hint style="info" %} Параметры, переданные в корневом объекте, применяются к каждому сообщению каскада: * destination * tags * useLocalTime * localSendTime * localCompletionTime * hours * days * shortUrl * callbackUrl * callbackEvents {% endhint %} {% hint style="info" %} В объектах callback, отправляемых по каскадным сообщениям, присутствует идентификатор первого сообщения каскада и порядковый номер данного сообщения – `cascade_message_uuid` и `cascade_step` соответственно (описано в разделе [Получение callback](/messages/callback.md)) {% endhint %} ## Содержимое SMS и VK-сообщений Для каналов SMS и VK передается объект `content` следующего вида: ``` "content": { "text": "текст сообщения" } ``` | Параметр | Тип | Описание | | ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | content.text |

string

required

|

Текст сообщения; строка в кодировке UTF-8 без Byte Order Mark

| ## Содержимое PUSH-сообщения Для канала PUSH формат и валидация объекта `content` описаны в разделе [Отправка PUSH](/messages/push-sending.md) ## Содержимое VIBER-сообщения Для канала VIBER формат и валидация объекта `content` описаны в разделе [Отправка VIBER ](/messages/viber-sending.md) ## Содержимое WHATSAPP-сообщения Для канала WHATSAPP формат и валидация объекта content описаны в разделе [Отправка WHATSAPP](/messages/whatsapp-sending.md) {% hint style="warning" %} Для канала WHATSAPP значение ttl следует устанавливать не менее 24 часов, так как сервис доставит сообщение абоненту даже спустя 24 часа неактивноси (например, выключенный телефон) {% endhint %} ## Содержимое WEASY-сообщения Для канала WEASY формат и валидация объекта content описаны в разделе [Отправка WEASY](/messages/weasy-sending.md) ## Содержимое TEXT\_TO\_SPEECH-сообщения Для канала TEXT\_TO\_SPEECH формат и валидация объекта content описаны в разделе [Отправка TEXT\_TO\_SPEECH](/messages/text-to-speech-sending.md) ## Содержимое FLASHCALL-сообщения Для канала FLASHCALL формат и валидация объекта content описаны в разделе [Отправка FLASHCALL-сообщения](/messages/flashcall-sending.md) ## Содержимое VOICECODE-сообщения Для канала VOICECODE формат и валидация объекта content, а также допустимое значение senderName описаны в разделе [Отправка VOICECODE](/messages/voicecode-sending.md) ## Содержимое TELEGRAM-сообщения Для канала TELEGRAM формат и валидация объекта content, а также допустимое значение senderName описаны в разделе [Отправка TELEGRAM](/messages/telegram-sending.md) ## Содержимое TELEGRAM GATEWAY-сообщения Для канала TELEGRAM GATEWAY формат и валидация объекта content, а также допустимое значение senderName описаны в разделе [Отправка TELEGRAM GATEWAY](/messages/otpravka-telegram-gateway.md) ## Пример запроса 1 Каскадная отправка по трем каналам следующего вида: 1. VK-сообщение отправляется первым в соответствии с переданными временны́ми параметрами 2. при отсутствии статуса "Прочитано" через 14400 секунд после отправки формируется VIBER-сообщение 3. VIBER-сообщение отправляется в соответствии с переданными временны́ми параметрами 4. при отсутствии статуса "Прочитано" через 10800 секунд после отправки формируется TELEGRAM-сообщение 5. при отсутствии статуса "Доставлено" через 600 секунд после отправки формируется SMS-сообщение 6. SMS-сообщение отправляется в соответствии с переданными временны́ми параметрами {% tabs %} {% tab title="JSON" %} ``` POST https://direct.i-dgtl.ru/api/v1/message/cascade Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/json [ { "destination": "79999999999", "localSendTime": "2021-01-01 18:00:00", "localCompletionTime": "2021-01-05 18:00:00", "useLocalTime": true, "hours": [ 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 ], "days": [ 6, 7 ], "shortUrl": true, "callbackUrl": "https://domain.com/callback", "callbackEvents": [ "delivered", "price", "click" ], "cascade": [ { "channelType": "VK", "senderName": "vk-sender", "content": { "text": "текст сообщения" }, "condition": "not_read", "ttl": 14400 }, { "channelType": "VIBER", "senderName": "viber-sender", "content": { "contentType": "text", "text": "текст сообщения" }, "condition": "not_read", "ttl": 10800 }, { "channelType": "TELEGRAM", "senderName": "i-digital_bot", "content": { "contentType": "text", "text": "текст сообщения" }, "condition": "not_delivered", "ttl": 600 }, { "channelType": "SMS", "senderName": "sms-sender", "content": { "text": "текст сообщения" } } ] } ] ``` {% endtab %} {% tab title="cURL" %} ``` curl -X POST 'https://direct.i-dgtl.ru/api/v1/message/cascade' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \ -d '[{"destination":"79999999999","localSendTime":"2021-01-01 18:00:00","localCompletionTime":"2021-01-05 18:00:00","useLocalTime":true,"hours":[10,11,12,13,14,15,16,17,18,19,20],"days":[6,7],"shortUrl":true,"callbackUrl":"https://domain.com/callback","callbackEvents":["delivered","price","click"],"cascade":[{"channelType":"VK","senderName":"vk-sender","content":{"text":"текст сообщения"},"condition":"not_read","ttl":14400},{"channelType":"VIBER","senderName":"viber-sender","content":{"contentType":"text","text":"текст сообщения"},"condition":"not_read","ttl":10800},{"channelType":"TELEGRAM","senderName":"i-digital_bot","content":{"contentType":"text","text":"текст сообщения"},"condition":"not_delivered","ttl":600},{"channelType":"SMS","senderName":"sms-sender","content":{"text":"текст сообщения"}}]}]' ``` {% endtab %} {% endtabs %} ## Пример запроса 2 Каскадная отправка кода подтверждения следующего вида: 1. TELEGRAM-сообщение отправляется моментально 2. При отсутствии статуса "Доставлено" через 60 секунд после отправки, либо при получении статуса "Не доставлено" формируется и отправляется SMS-сообщение {% tabs %} {% tab title="JSON" %} ``` POST https://direct.i-dgtl.ru/api/v1/message/cascade Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== Content-Type: application/json [ { "destination": "<номер абонента>", "cascade": [ { "channelType": "TELEGRAM", "senderName": "telegram_bot", "content": { "contentType": "text", "text": "Код авторизации от i-digital: 3 2 6 1" }, "condition": "not_delivered", "ttl": 60 }, { "channelType": "SMS", "senderName": "sms-sender", "content": { "text": "Ваш код для авторизации: 3261" } } ] } ] ``` {% endtab %} {% tab title="cURL" %} ``` curl -X POST 'https://direct.i-dgtl.ru/api/v1/message/cascade' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \ -d '[{"destination":"<номер абонента>","cascade":[{"channelType":"TELEGRAM","senderName":"telegram_bot","content":{"contentType":"text","text":"Ваш код: 3-2-6-1"},"condition":"not_delivered","ttl":60},{"channelType":"SMS","senderName":"sms-sender","content":{"text":"Ваш код для авторизации: 3261"}}]}]' ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api.docs.direct.i-dgtl.ru/messages/cascade-sending.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.