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

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

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

Использование невалидного токена / отсутствие заголовка авторизации.

{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}

=============================================
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}

402

Недостаточно средств на балансе.

{
    "error": {
        "code": 402,
        "msg": "Insufficient funds"
    }
}

403

Использование неподходящего токена.

{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}

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

{% hint style=»warning» %} Рекомендуемое время ожидания ответа: 70 секунд.
Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки. {% endhint %}

{% hint style=»info» %} Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку {% endhint %}

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

Параметр

Варианты

callbackEvents

События для отправки callback

cascade.channelType

SMS
PUSH
VIBER
WHATSAPP
WEASY
VK
TELEGRAM
TELEGRAM GATEWAY
TEXT_TO_SPEECH
FLASHCALL
VOICECODE
MMS

cascade.condition

Условия формирования каскадных сообщений

{% hint style=»info» %} Параметры, переданные в корневом объекте, применяются к каждому сообщению каскада:

destination
tags
useLocalTime
localSendTime
localCompletionTime
hours
days
shortUrl
callbackUrl
callbackEvents {% endhint %}

{% hint style=»info» %} В объектах callback, отправляемых по каскадным сообщениям, присутствует идентификатор первого сообщения каскада и порядковый номер данного сообщения – cascade_message_uuid и cascade_step соответственно (описано в разделе Получение callback) {% endhint %}

Содержимое 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

{% hint style=»warning» %} Для канала WHATSAPP значение ttl следует устанавливать не менее 24 часов, так как сервис доставит сообщение абоненту даже спустя 24 часа неактивноси (например, выключенный телефон) {% endhint %}

Содержимое 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 #

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

VK-сообщение отправляется первым в соответствии с переданными временны́ми параметрами
при отсутствии статуса «Прочитано» через 14400 секунд после отправки формируется VIBER-сообщение
VIBER-сообщение отправляется в соответствии с переданными временны́ми параметрами
при отсутствии статуса «Прочитано» через 10800 секунд после отправки формируется TELEGRAM-сообщение
при отсутствии статуса «Доставлено» через 600 секунд после отправки формируется SMS-сообщение
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

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

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

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

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