# Создание рассылок
## Создание рассылки
`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` |
::::::{tab-set}
:::::{tab-item} 200
При успешном создании рассылки возвращается ее идентификатор.
```
{
"dispatchId": 10000000125
}
```
:::::
:::::{tab-item} 401
Использование невалидного токена / отсутствие заголовка авторизации.
::::{tab-set}
:::{tab-item} 4012
```
{
"error": {
"code": 4012,
"msg": "Bad credentials"
}
}
```
:::
:::{tab-item} 4010
```
{
"error": {
"code": 4010,
"msg": "Not Authenticated"
}
}
```
:::
::::
:::::
:::::{tab-item} 403
Использование неподходящего токена.
```
{
"error": {
"code": 4030,
"msg": "Access Denied"
}
}
```
:::::
:::::{tab-item} 422
Невалидные параметры в теле запроса; ниже приведены несколько примеров ответа.
```
{
"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 | [Скорость рассылки](../../extra/references/#dispatch_velocity) |
| callbackEvents | [События для отправки callback](../../extra/references/#callback-events) |
## Создание одноканальной рассылки
Для создания рассылки по одному каналу в объекте:
* передаются параметры `channelType, senderName, content`
* не передается массив `cascade`
### Контент рассылки
Для канала VIBER формат и валидация объекта content описаны в разделе [Отправка VIBER](../../messages/viber-sending.md)
Для канала SMS формат и валидация объекта content описаны в разделе [Каскадная отправка](../../messages/cascade-sending.md#sms-and-vk-content)
При этом в тексте сообщения могут присутствовать переменные, которые будут заменены на строки для каждого отдельного сообщения при наполнении рассылки сообщениями.
Переменными являются все строки в двойных фигурных скобках, которые находятся в строке `content.text`
#### Пример:
```
"content": {
"text": "Уважаемый {{A}}! Рады сообщить, что Вам одобрена кредитная карта на сумму {{B}}, можете забрать ее в ближайшем офисе по адресу {{C}}."
}
```
### Пример запроса
::::::{tab-set}
:::::{tab-item} 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
| Канал отправки; одно из значений:
|
| 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`, обязательно должны быть переданы для каждого сообщения на [следующем шаге](add-messages.md).
::::::{tab-set}
:::::{tab-item} 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"
}
}
]
}
```
:::::
:::::{tab-item} cURL
```
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"}}]}'
```
:::::
::::::