# Создание рассылок ## Создание рассылки `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` | {% tabs %} {% tab title="200" %} При успешном создании рассылки возвращается ее идентификатор. ``` { "dispatchId": 10000000125 } ``` {% endtab %} {% tab title="401" %} Использование невалидного токена / отсутствие заголовка авторизации. {% tabs %} {% tab title="4012" %} ``` { "error": { "code": 4012, "msg": "Bad credentials" } } ``` {% endtab %} {% tab title="4010" %} ``` { "error": { "code": 4010, "msg": "Not Authenticated" } } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403" %} Использование неподходящего токена. ``` { "error": { "code": 4030, "msg": "Access Denied" } } ``` {% endtab %} {% tab title="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" } } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} * Рекомендуемое время ожидания ответа: 70 секунд.\ Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки. * Для настройки сокращения ссылок с использованием личного домена необходимо обратиться в поддержку {% endhint %} {% hint style="info" %} * Имена отправителей можно создать в личном кабинете. Имена отправителей для канала SMS также можно создать при помощи API * Параметры `rate` и `rateTerm` вместе образуют максимально допустимую скорость отправки, которую рассылка гарантированно не превысит {% endhint %} Возможные варианты перечислений: | Параметр | Варианты | | -------------- | --------------------------------------------------------------------- | | channelType | SMS, VIBER | | rateTerm | [Скорость рассылки](/extra/references.md#dispatch_velocity) | | callbackEvents | [События для отправки callback](/extra/references.md#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}}." } ``` ### Пример запроса {% tabs %} {% tab title="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" } } ``` {% endtab %} {% endtabs %} ## Создание каскадной рассылки Для создания каскадной рассылки в объекте: * не передаются параметры `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`, обязательно должны быть переданы для каждого сообщения на [следующем шаге](/dispatches/sending/add-messages.md). {% tabs %} {% tab title="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" } } ] } ``` {% endtab %} {% tab title="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"}}]}' ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api.docs.direct.i-dgtl.ru/dispatches/sending/create-dispatch.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.