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

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

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

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

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

{
  "dispatchId": 10000000125
}

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

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

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

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

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

Невалидные параметры в теле запроса; ниже приведены несколько примеров ответа.

{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal 2020-12-11T02:15:38Z"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than maximal 2020-12-18T14:17:52Z"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "No active sender name SENDER"
    }
}

{% hint style=»warning» %}

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

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

{% hint style=»info» %}

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

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

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

Параметр

Варианты

channelType

SMS, VIBER

rateTerm

Скорость рассылки

callbackEvents

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

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

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

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

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

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

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

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

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

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

Пример: #

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

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

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, обязательно должны быть переданы для каждого сообщения на следующем шаге.

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 -X POST 'https://direct.i-dgtl.ru/api/v1/dispatch' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '{"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"}}]}'