Каскадная отправка

Каскадной отправкой называется технология переотправки сообщения по различным каналам. Последовательность каналов задается последовательностью объектов сообщений в массиве 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 часов

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
    }
  ]
}

401

402

403

422

Рекомендуемое время ожидания ответа: 70 секунд. Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки.

Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку

Возможные варианты перечислений:

Параметр	Варианты
callbackEvents	События для отправки callback
cascade.channelType	SMS PUSH VIBER WHATSAPP WEASY VK TELEGRAM TELEGRAM GATEWAY TEXT_TO_SPEECH FLASHCALL
cascade.condition	Условия формирования каскадных сообщений

Параметры, переданные в корневом объекте, применяются к каждому сообщению каскада:

• destination

• tags

• useLocalTime

• localSendTime

• localCompletionTime

• hours

• days

• shortUrl

• callbackUrl

• callbackEvents

В объектах callback, отправляемых по каскадным сообщениям, присутствует идентификатор первого сообщения каскада и порядковый номер данного сообщения – cascade_message_uuid и cascade_step соответственно (описано в разделе Получение callback)

Содержимое SMS и VK-сообщений

Для каналов SMS и VK передается объект content следующего вида:

"content": {
  "text": "текст сообщения"
}

Параметр	Тип	Описание
content.text	string required	Текст сообщения; строка в кодировке UTF-8 без Byte Order Mark SMS: строка от 1 до 5000 символов VK: строка от 1 до 2048 символов

Содержимое PUSH-сообщения

Для канала PUSH формат и валидация объекта content описаны в разделе Отправка PUSH

Содержимое VIBER-сообщения

Для канала VIBER формат и валидация объекта content описаны в разделе Отправка VIBER

Содержимое WHATSAPP-сообщения

Для канала WHATSAPP формат и валидация объекта content описаны в разделе Отправка WHATSAPP

Для канала WHATSAPP значение ttl следует устанавливать не менее 24 часов, так как сервис доставит сообщение абоненту даже спустя 24 часа неактивноси (например, выключенный телефон)

Содержимое WEASY-сообщения

Для канала WEASY формат и валидация объекта content описаны в разделе Отправка WEASY

Содержимое TEXT_TO_SPEECH-сообщения

Для канала TEXT_TO_SPEECH формат и валидация объекта content описаны в разделе Отправка TEXT_TO_SPEECH

Содержимое FLASHCALL-сообщения

Для канала FLASHCALL формат и валидация объекта content описаны в разделе Отправка FLASHCALL-сообщения

Содержимое VOICECODE-сообщения

Для канала VOICECODE формат и валидация объекта content, а также допустимое значение senderName описаны в разделе Отправка VOICECODE

Содержимое TELEGRAM-сообщения

Для канала TELEGRAM формат и валидация объекта content, а также допустимое значение senderName описаны в разделе Отправка TELEGRAM

Содержимое TELEGRAM GATEWAY-сообщения

Для канала TELEGRAM GATEWAY формат и валидация объекта content, а также допустимое значение senderName описаны в разделе Отправка TELEGRAM GATEWAY

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

Каскадная отправка по трем каналам следующего вида:

1. VK-сообщение отправляется первым в соответствии с переданными временны́ми параметрами

2. при отсутствии статуса "Прочитано" через 14400 секунд после отправки формируется VIBER-сообщение

3. VIBER-сообщение отправляется в соответствии с переданными временны́ми параметрами

4. при отсутствии статуса "Прочитано" через 10800 секунд после отправки формируется TELEGRAM-сообщение

5. при отсутствии статуса "Доставлено" через 600 секунд после отправки формируется SMS-сообщение

6. SMS-сообщение отправляется в соответствии с переданными временны́ми параметрами

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": "текст сообщения"
        }
      }
    ]
  }
]

cURL

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

Каскадная отправка кода подтверждения следующего вида:

1. TELEGRAM-сообщение отправляется моментально

2. При отсутствии статуса "Доставлено" через 60 секунд после отправки, либо при получении статуса "Не доставлено" формируется и отправляется SMS-сообщение

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"
        }
      }
    ]
  }
]

cURL