Создание рассылок

Создание рассылки

POST https://direct.i-dgtl.ru/api/v1/dispatch

Метод позволяет создать как рассылку по одному каналу, так и каскадную рассылку.

Headers

Name	Type	Description
Authorization*	string	Basic {TOKEN_1}
Content-Type*	string	application/json

Request Body

Name	Type	Description
dispatchName*	string	Название рассылки
cascade	array	Массив каскадной отправки; описан ниже
channelType	string	Канал рассылки; обязателен при отсутствии массива cascade
content	object	Содержимое сообщения; обязателен при отсутствии массива cascade
localSendTime*	string	Нижняя граница допустимого времени начала рассылки (с учетом useLocalTime) Дата в формате YYYY-MM-DD hh:mm:ss в диапазоне от (текущее время в UTC - 12 часов) до (текущее время в UTC + 70 дней)
localCompletionTime	string	Верхняя граница допустимого времени завершения рассылки (с учетом useLocalTime) в диапазоне от localSendTime до (текущее время в UTC + 70 дней)
useLocalTime	boolean	Флаг, отвечающий за таймзону, в которой будут отправляться сообщения true- отправка в таймзоне абонента false- отправка по МСК По умолчанию true
hours*	array	Допустимые часы отправки (массив чисел). В массиве могут быть переданы целые числа от 0 до 23, каждое из которых соответствует разрешенному для отправки часовому интервалу с учетом useLocalTime; значения должны быть уникальны.
days*	array	Допустимые дни отправки (массив чисел). В массиве могут быть переданы целые числа от 1 (пн) до 7 (вс), каждое из которых соответствует разрешенному для отправки дню недели; значения должны быть уникальны.
tags	array	Теги рассылки (массив строк). Каждый тег должен соответствовать выражению ^\w+$ (допускаются буквы в любом регистре, цифры и нижнее подчеркивание "_")
senderName	string	Имя отправителя; обязателен при отсутствии массива cascade; допустимые значения зависят от канала: SMS: допускаются sms-отправители в статусе "Одобрено" с датой начала действия не позднее, чем время отправки запроса VIBER: допускаются viber-отправители в статусе "Одобрено" с датой начала действия не позднее, чем время отправки запроса
shortUrl	boolean	Флаг, отвечающий за сокращение ссылок в сообщении: true - ссылки в сообщении будут сокращены. По умолчанию false
rate	integer	Максимальное количество сообщений рассылки, которые можно отправить в единицу времени rateTerm: 'm': от 1 до 1000 'h': от 1 до 1000 * 60 'd': от 1 до 1000 * 60 * {количество элементов в массиве hours} Обязателен в запросе при наличии rateTerm
rateTerm	string	Единица времени для ограничения rate Обязателен в запросе при наличии rate
callbackUrl	string	Адрес для отправки callback
callbackEvents	array	События, по которым будут отправлены callback (массив строк). При наличии callbackUrl и отсутствии callbackEvents в запросе, будет отправлен callback по событию delivered

200

При успешном создании рассылки возвращается ее идентификатор.

{
  "dispatchId": 10000000125
}

401

403

422

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

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

• Имена отправителей можно создать в личном кабинете. Имена отправителей для канала SMS также можно создать при помощи API

• Параметры rate и rateTerm вместе образуют максимально допустимую скорость отправки, которую рассылка гарантированно не превысит

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

Параметр	Варианты
channelType	SMS, VIBER
rateTerm	Скорость рассылки
callbackEvents	События для отправки callback

Создание одноканальной рассылки

Для создания рассылки по одному каналу в объекте:

• передаются параметры channelType, senderName, content

• не передается массив cascade

Контент рассылки

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

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

При этом в тексте сообщения могут присутствовать переменные, которые будут заменены на строки для каждого отдельного сообщения при наполнении рассылки сообщениями.

Переменными являются все строки в двойных фигурных скобках, которые находятся в строке content.text

Пример:

"content": {
  "text": "Уважаемый {{A}}! Рады сообщить, что Вам одобрена кредитная карта на сумму {{B}}, можете забрать ее в ближайшем офисе по адресу {{C}}."
}

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

JSON

POST https://direct.i-dgtl.ru/api/v1/dispatch
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
    "dispatchName": "название рассылки",
    "localSendTime": "2021-10-01 00:00:00",
    "localCompletionTime": "2021-1-01 00:00:00",
    "useLocalTime": true,
    "hours": [10, 11, 12, 13, 14, 15],
    "days": [1, 2, 3, 4, 5, 6, 7],
    "tags": ["тег"],
    "senderName": "sender",
    "rate": 100,
    "rateTerm": "h",
    "shortUrl": true,
    "channelType": "VIBER",
    "callbackUrl": "https://domain.com/callback",
    "callbackEvents": ["delivered", "price"],
    "content": {
        "contentType": "text",
        "text": "Уважаемый {{A}}! Рады сообщить, что Вам одобрена кредитная карта на сумму {{B}}, можете забрать ее в ближайшем офисе по адресу {{C}}. Подробности: https://bank.ru"
    }
} 

Создание каскадной рассылки

Для создания каскадной рассылки в объекте:

• не передаются параметры channelType, senderName, content

• передается массив cascade

Описание массива cascade

"cascade": [
    {
      "channelType": "VIBER",
      "senderName": "viber-sender",
      "ttl": 10000,
      "condition": "not_read",
      "content": {
        "contentType": "text",
        "text": "текст VIBER сообщения {{A}}"
      }
    },
    {
      "channelType": "SMS",
      "senderName": "sms-sender",
      "ttl": 20000,
      "condition": "not_delivered",
      "content": {
        "contentType": "text",
        "text": "текст SMS сообщения {{A}}"
      }
    }
  ]

Параметр	Тип	Описание
cascade	array (objects) required	Массив объектов, описывающих каскад; отправка сообщений будет производиться в соответствии с порядком объектов в массиве (аналогично отправке одиночных каскадных сообщений)
cascade.channelType	string required	Канал отправки; одно из значений: SMS VIBER
cascade.content	object required	Контент для сообщений данного шага; объекты соответствуют объектам контента соответствующего канала для одноканальной рассылки; в тексте также допускаются подстановки
cascade.senderName	string required	Имя отправителя соответствующего канала в статусе "Одобрено" с датой начала действия не позднее момента отправки запроса
cascade.condition	string optional	Условие отправки следующего сообщения По умолчанию not_delivered
cascade.ttl	integer optional	Время жизни сообщения в секундах. По истечении ttl: сообщению данного шага каскада будет присвоен финальный статус, а также при выполнении cascade.condition будет создано следующее сообщение 60 ≤ ttl ≤ 86400 По умолчанию время жизни сообщения составляет 25 часов

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

В данной рассылке для каждого получателя рассылки будет отправлено VIBER-сообщение; если для VIBER-сообщения не будет получен статус "Прочитано" в течение 12 часов, то для получателя будет отправлено SMS-сообщение.

При этом сообщения отправляются с 10 до 16 часов со скоростью не более 100 сообщений в час.

Подстановки {{A}}, {{B}}, {{C}}, указанные в параметрах content.text, обязательно должны быть переданы для каждого сообщения на следующем шаге.

JSON

POST https://direct.i-dgtl.ru/api/v1/dispatch
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
  "dispatchName": "название рассылки",
  "localSendTime": "2021-10-01 00:00:00",
  "localCompletionTime": "2021-11-01 00:00:00",
  "useLocalTime": true,
  "hours": [10,11,12,13,14,15],
  "days": [1,2,3,4,5,6,7],
  "tags": ["тег"],
  "rate": 100,
  "rateTerm": "h",
  "shortUrl": true,
  "callbackUrl": "https://domain.com/callback",
  "callbackEvents": ["delivered","price"],
  "cascade": [
    {
      "channelType": "VIBER",
      "senderName": "viber-sender",
      "ttl": 43200,
      "condition": "not_read",
      "content": {
        "contentType": "button",
        "text": "Уважаемый {{A}}! Рады сообщить, что Вам одобрена кредитная карта на сумму {{B}}, можете забрать ее в ближайшем офисе по адресу {{C}}",
        "caption": "Подробнее",
        "action": "https://example.ru",
        "imageUrl": "https://example.ru/image.png"
      }
    },
    {
      "channelType": "SMS",
      "senderName": "sms-sender",
      "content": {
        "contentType": "text",
        "text": "Уважаемый {{A}}! Рады сообщить, что Вам одобрена кредитная карта на сумму {{B}}, можете забрать ее в ближайшем офисе по адресу {{C}}. Подробнее: https://bank.ru"
      }
    }
  ]
}

cURL