OMNI¶

Создание сценария¶

Для создания сценария OMNI-рассылки необходимо вызвать POST /omni-task-api/tasks, передавая параметры сценария в теле запроса и данные авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
addressBookSource (optional)	AddressBookSource	Параметры адресных книг. Не используется для транзакционных сообщений, в них контакты задаются отдельно. Макросы (поля) из адресных книг можно использовать в текстах сообщений.
channel	string	Канал рассылки. Возможные значения: `EMAIL`, `OMNI`, `PUSH`, `SMS`, `VIBER`, `VK`, `WHATSAPP`. Канал `OMNI` используется для переотправки сообщений в другие каналы, триггерных рассылок, а также отправки транзакционных сообщений.
draftId (optional)	integer	ID черновика рассылки.
taskInfo (optional)	TaskInfo	Тип сценария, который активирует триггерную рассылку.
taskName	string	Название рассылки. От 1 до 100 символов.
triggers	Triggers	Параметры триггеров.
type	string	Тип рассылки. Возможные значения: ○ `API` - отправка транзакционных сообщений через API. Единственный тип рассылок, для которого нужно использовать дополнительные методы. ○ `BIRTHDAY` - рассылка по дням рождения контактов. ○ `PERIODIC` - периодическая рассылка. ○ `SIMPLE` - одноразовая рассылка. ○ `EVENT_FLOW` - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK. ○ `GEO` - рассылка по геолокации контакта. Только для канала `PUSH`.

AddressBookSource¶

Параметр	Тип данных	Описание
addressBookSourceType	string	Тип адресной книги, используется для фильтра. Возможные значения: ○ `BIRTHDAY` - рассылка по дням рождения контактов. ○ `PERIODIC` - периодическая рассылка. ○ `SIMPLE` - одноразовая рассылка.
byOptimalSendTime (optional)	boolean	Персонализированное время отправки. При выборе этой опции контакты получат письма в рассчитанное персонализированное время. Рассылка может продлиться 24 часа с момента запуска.
byTimeZone (optional)	boolean	Учет местного времени контакта при отправке.
checkDuplicate (optional)	boolean	Проверка дубликатов контактов в адресной книге. Дубликатам сообщение отправляться не будет.
contactCountId (optional)	integer	ID количества контактов в адресной книге.
contactGroupIds	array[integer]	Массив ID групп контактов в адресной книге. Не используется вместе с параметром segmentIds.
stopContactGroupIds (optional)	array[integer]	Массив ID стоп-листов контактов. Этим контактам рассылка производиться не будет.
period (optional)	string	Периодичность. Используется при `"type": "PERIODIC"`. Возможные значения: ○ `ONCE` - один раз. ○ `DAILY` - ежедневно. ○ `WEEKLY` - еженедельно. ○ `MONTHLY` - ежемесячно.
segmentIds (optional)	array[integer]	Массив ID сегментов внутри групп контактов адресной книги, если группа контактов разделена на сегменты. Не используется вместе с параметром contactGroupIds.
smoothSendMinutes (optional)	integer	Плавная отправка, задается в минутах. Минимальное значение: 0 Максимальное значение: 1440, 1 сутки

TaskInfo¶

Параметр	Тип данных	Описание
scenarioType (optional)	string	Тип сценария. Используется при `"type": "EVENT_FLOW"`. Сообщение отправляется, если пользователь бросил: ○ `abandonedCart` - просмотр корзины. ○ `abandonedProductView` - просмотр товара. ○ `abandonedCategoryView` - просмотр категории.

Triggers¶

Параметр	Тип данных	Описание
channel	string	Канал триггера. Возможные значения: `EMAIL`, `FLASHCALL`, `HLR`, `PUSH`, `PUSH_WALLET`, `SMS`, `VIBER`, `VK`, `VOICE`, `WHATSAPP`.
type	string	Тип триггера. Возможные значения: ○ `ADDRESS_BOOK_SOURCE` - стандартная рассылка. ○ `TRAN_API_SOURCE` - отправка транзакционных сообщений по API. ○ `EVENT_SOURCE` - рассылка по событиям. ○ `NO_EVENT_SOURCE` - рассылка по истекшему времени ожидания события. ○ `EVENT_COLLECTOR` - повторяющаяся рассылка по событиям. ○ `GEO_LOCATION` - гео-рассылка. Только для канала `PUSH`.
index	integer	ID триггера.
parentIndex (optional)	integer	ID родительского триггера. С помощью данного параметра можно настраивать последовательность триггеров.
startTime (optional)	datetime	Дата старта триггера. Формат - `YYYY-MM-DD hh:mm:ss`.
endTime (optional)	datetime	Дата окончания триггера. Формат - `YYYY-MM-DD hh:mm:ss`
eventSources (optional)	array[EventSources]	Массив событий для совершения рассылок.
eventCollectorSettings (optional)	EventCollectorSettings	Параметры повторяющихся рассылок по событиям. Данный вид событий может быть отменен только другими триггерами.
geoSettings (optional)	GeoSettings	Параметры гео-рассылок.
noEventSourceSettings (optional)	NoEventSourceSettings	Содержит параметр: `stateWaitMaxTimeSec` (integer) - время ожидания события в секундах. Событие задается в отдельном триггере, в объекте EventSources. Индекс этого триггера должен быть указан в `parentIndex`. Когда время ожидания проходит, сообщение отправляется по дочернему триггеру.
template	Template	Массив шаблонов сообщений.

EventSources¶

Параметр Тип данных Описание

channel
(optional)

string

Канал триггера.

Возможные значения: EMAIL, FLASHCALL, HLR, PUSH, PUSH_WALLET, SMS, VIBER, VK, VOICE, WHATSAPP.

eventType

string

Тип события.

Возможные значения:
○ CONTACT_MOBILE_EVENT - событие для гео-рассылок. Используется только с каналом PUSH.
○ CONTACT_WEB_EVENT - событие в веб-интерфейсе.
○ STATE - статус, который должно принять сообщение для совершения рассылки. Можно использовать с любыми каналами, в том числе, с каналом OMNI для переотправки сообщений в другие каналы, триггерных рассылок, а также отправки транзакционных сообщений.

eventValue
(optional)

string

События, при которых совершается рассылка.

○ При "eventType": "CONTACT_MOBILE_EVENT" может быть только значение GEO. Также в запросе должен быть указан объект GeoSettings.

○ При "eventType": "CONTACT_WEB_EVENT" используются события из Web SDK.

○ При "eventType": "STATE" используются статусы сообщений.

EventCollectorSettings¶

Параметр	Тип данных	Описание
maxNewRegisterSec (optional)	integer	Время после совершения события в секундах, в течение которого рассылка не будет повторяться.
onlyUpdateEventSources (optional)	array[EventSources]	Массив событий для совершения повторяющихся рассылок. После этих событий будет начинаться отсчет в параметре `maxNewRegisterSec`. Если событие повторится, отсчет начнется заново.

GeoSettings¶

Параметр	Тип данных	Описание
antiFraudMins (optional)	integer	Время в минутах для повторной отправки сообщения.
locationIds (optional)	array[integer]	Массив ID геолокаций.
pushApplicationIds (optional)	array[integer]	Массив ID приложений, в которых будет проведена рассылка.

Заполнение шаблонов¶

Совет

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

Параметр	Тип данных	Описание
smsTemplate (optional)	SmsTemplate	Шаблон SMS-сообщения.
viberTemplate (optional)	ViberTemplate	Шаблон Viber-сообщения.
emailTemplate (optional)	EmailTemplate	Шаблон Email-письма.
pushTemplate (optional)	PushTemplate	Шаблон push-уведомления.
pushWalletTemplate (optional)	PushWalletTemplate	Шаблон Push Wallet уведомления от приложения Кошелёк.
whatsAppTemplate (optional)	WhatsAppSendMessageRequest	Шаблон WhatsApp-сообщения.
vkTemplate (optional)	VkTemplate	Шаблон VK-сообщения.

SmsTemplate¶

Параметр	Тип данных	Описание
shortenUrl (optional)	boolean	При `true` сокращает длину ссылок в тексте сообщения. К примеру, если параметр активен, ссылка `https://www.example-url.com/my-example-param...` будет преобразована в ссылку вида `https://clickdo.integrationapi.net/link-hash`. По умолчанию `false`.
from	string	Согласованное имя отправителя.
text	string	Текст сообщения: ○ до 17085 символов включительно при использовании кириллицы. ○ до 34170 символов включительно при использовании латиницы.
validity	integer	Срок жизни сообщения в секундах. Минимальное значение: 0 Максимальное значение: 259200, 3 суток По умолчанию: 0

ViberTemplate¶

Параметр	Тип данных	Описание
from	string	Имя отправителя, которое используется при отправке сообщения. Можно использовать только те имена, которые доступны пользователю.
action (optional)	string	URL или deep link, на который перейдет пользователь после нажатия на кнопку. Кнопка может использоваться только в сочетании с другими параметрами.
caption (optional)	string	Текст кнопки, не более 30 символов в кодировке UTF-8.
image (optional)	string	URL изображения в форматах JPG, JPEG или PNG.
text (optional)	string	Текст сообщения в кодировке UTF-8. Стандартное число символов - не более 1000. Максимальное число символов - 2000. Если стандартное число символов в Viber-сообщении превышает 1000 символов, сообщение будет поделено на сегменты и доставлено последовательно, с сохранением смыслового содержания.
validity (optional)	integer	Срок жизни сообщения в секундах. Минимальное значение: 15 Максимальное значение: 1209600, 14 дней По умолчанию: 86400, 1 сутки

EmailTemplate¶

Параметр	Тип данных	Описание
sourceAddress	string	Email-адрес отправителя. Предварительно должен быть создан и согласован домен.
sourceName	string	Имя отправителя. Максимальная длина - 150 символов.
subject	string	Тема письма.
htmlBody	string	Тело письма в формате HTML.
plainText (optional)	string	Тело письма в формате Plaintext, все теги отображаются как обычный текст.
attachmentIds (optional)	array[integer]	Массив файлов, прикрепленных к письму.

PushTemplate¶

Параметр	Тип данных	Описание
from	integer	ID отправителя.
title	string	Заголовок уведомления. Максимальная длина - 200 символов.
text	string	Текст уведомления. Максимальная длина - 1024 символа.
badge (optional)	integer	Ключ, устанавливающий значение для бейджа приложения - значка с цифрой в верхнем углу иконки приложения. Цифра обозначает количество непрочитанных уведомлений в приложении. Можно задать любое целое число. Чтобы бейдж не отображался, нужно установить значение параметра `0` либо удалить данный параметр.
validity (optional)	integer	Срок жизни уведомления в секундах. Минимальное значение: 30 Максимальное значение: 86400, 1 сутки По умолчанию: 86400, 1 сутки
platform (optional)	string	Платформа или операционная система устройств, на которые будет прислано уведомление. Доступны значения: ○ `ANDROID` - устройства с ОС Android. ○ `IOS` - устройства с ОС iOS.
silentPush (optional)	boolean	Если `true`, уведомление не будет отображаться на устройстве получателя. По умолчанию `false`.
options (optional)	object	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
apns (optional)	object	Специфические настройки iOS.
android (optional)	object	Специфические настройки Android.

PushWalletTemplate¶

Параметр	Тип данных	Описание
from	string	Согласованный ID отправителя.
payload	PushPayload	Настройки контента сообщения.
callbackUrl (optional)	string	URL, на который система будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой `HTTP` или `HTTPS`.
callbackData (optional)	object	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
mergeKey (optional)	string	Ключ для объединения запроса и ответа.
validity (optional)	integer	Срок жизни уведомления в секундах.

VkTemplate¶

Параметр	Тип данных	Описание
routes	array	Список возможных каналов доставки через запятую (пример: `[ VK, OK ]`). ○ `VK` - доставка от имени официальной группы VK. ○ `OK` - доставка от имени официальной группы в Одноклассники. По умолчанию `VK`. Доставка производится до первого получения уведомления на физическое устройство. При указании нескольких каналов доставки в итоге использован и тарифицирован будет только один из каналов. Последовательность и логика выбора маршрутов из данного списка конфигурируется при подключении к системе. Если параметр не задан, по умолчанию используются все возможные способы доставки. Доставка будет происходить только в том случае, если в шаблоне будет указана группа в соответствующей социальной сети. Например в шаблоне может быть указана только группа VK, тогда доставка в Одноклассники по данному шаблону осуществляться не будет.
deliveryPolicy	string	Возможные значения: `any`, `mobile_device_required`, `verified_phone_number` По умолчанию `any`. Если указано `mobile_device_required`, то доставка производится только в случае наличия у пользователя мобильного приложения и его использования в течение последних 7 дней. Доставка при этом производится во все имеющиеся устройства, а не только мобильные. Если указано `verified_phone_number`, то доставка производится только тем пользователям, чей номер телефона дополнительно проверен на актуальность.
validity (optional)	integer	Срок жизни сообщения в секундах. Минимальное значение: 60 Максимальное значение: 86400, 1 день По умолчанию: 86400 Если сообщение не было доставлено за время `ttl`, оно не будет доставлено и тарифицировано.
templateId	string	ID шаблона сообщения в Devino.
templateData (optional)	object	JSON-объект, где ключи - имена переменных в шаблоне. Например, для шаблона: Вам доставлена посылка по адресу `{ address }`. Код получения - `{ code }`, - параметр `tmpl_data` будет: `{ "address": "ул. Ленина, д. 6", "code": "485372" }`.
callbackData (optional)	string	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
callbackUrl (optional)	string	URL, на который система будет отправлять коллбэки при изменении статуса сообщения. Любой валидный URL со схемой `HTTP` или `HTTPS`.

Примеры запросов¶

ADDRESS_BOOK_SOURCE

{
  "taskName": "NEW_SMS",
  "type": "SIMPLE", 
  "channel": "SMS",
  "addressBookSource": {
    "contactGroupIds": [111],
    "addressBookSourceType": "SIMPLE",
    "period": "ONCE"
  },
  "triggers": [
    {
      "index": 321,
      "startTime": "2020-06-02 11:00:00",
      "endTime": "2020-06-02 12:00:00",
      "type": "ADDRESS_BOOK_SOURCE",
      "channel": "SMS",
      "eventSources": [
        {
          "channel": "SMS",
          "eventType": "STATE",
          "eventValue": "delivered"
        }
      ],
      "template": {
        "smsTemplate": {
          "text": "У нас новый магазин!",
          "from": "TEST",
          "validity": 600
        }
      }
    }
  ]
}

NO_EVENT_SOURCE

Отправляем сообщение в SMS. Если оно доставлено, рассылка заканчивается. Если не доставлено, отправляем Email.

{
  "taskName": "Повторение рассылки",
  "type": "SIMPLE", 
  "channel": "EMAIL",
  "addressBookSource": {
    "contactGroupIds": [111],
    "addressBookSourceType": "SIMPLE",
    "period": "ONCE"
  },
  "triggers": [
    {
      "index": 11,
      "startTime": "2019-11-29T09:33:57.595Z",
      "endTime": "2019-11-29T19:33:57.595Z",
      "type": "ADDRESS_BOOK_SOURCE",
      "channel": "SMS",
      "template": {
        "smsTemplate": {
          "text": "Первое сообщение",
          "from": "TEST",
          "validity": 600
        }
      }
    },
    {
      "index": 12,
      "parentIndex": 11,
      "startTime": "2019-11-29T19:33:57.595Z",
      "endTime": "2019-11-29T23:33:57.595Z",
      "type": "NO_EVENT_SOURCE",
      "channel": "EMAIL",
      "eventSources": [
        {
          "channel": "SMS",
          "eventType": "STATE",
          "eventValue": "delivered"
      ],
      "noEventSourceSettings": {
        "stateWaitMaxTimeSec": 6000
      },
      "template": {
        "emailTemplate": {
          "htmlBody": "Второе сообщение, если не доставлено первое",
          "sourceAddress": "test@test",
          "sourceName": "TEST",
          "subject": "Тестовое сообщение"
        }
      }
    }
  ]
}

EVENT_COLLECTOR

Если пользователь не успел заполнить анкету на сайте, после 100 секунд ожидания отправляем Email.

Если пользователь не завершил заполнение анкеты через сутки, отправляем еще один Email. Если пользователь заполнил анкету, завершаем событие и ничего не отправляем.

{
  "taskName": "Предложение заполнить заявку до конца",
  "type": "EVENT_FLOW",
  "channel": "EMAIL",
  "triggers": [
    {
      "index": "0",
      "type": "EVENT_COLLECTOR",
      "channel": "EMAIL",
      "eventCollectorSettings": {
        "maxNewRegisterSec": 86400,
        "onlyUpdateEventSources": [
          {
            "eventType": "CONTACT_WEB_EVENT"
          }
        ]
      },
      "eventSources": [
        {
          "eventType": "CONTACT_WEB_EVENT",
          "eventValue": "RequestToCompleteApplication"
        }
      ]
    },
    {
      "index": "1",
      "parentIndex": "0",
      "type": "EVENT_COLLECTOR",
      "channel": "EMAIL",
      "eventSources": [
        {
          "eventType": "CONTACT_WEB_EVENT",
          "eventValue": "CompletedApplication"
        }
      ]
    },
    {
      "index": "2",
      "parentIndex": "0",
      "type": "NO_EVENT_SOURCE",
      "channel": "EMAIL",
      "noEventSourceSettings": {
        "stateWaitMaxTimeSec": 100
      },
      "template": {
        "emailTemplate": {
          "htmlBody": "Заполните анкету до конца",
          "sourceAddress": "test@test",
          "sourceName": "TEST",
          "subject": "Тестовое сообщение"
        }
      }
    }
  ]
}

Параметры ответа¶

Параметр	Тип данных	Описание
result	array	Массив с данными сценария. Указывается только при `"code": "OK"`.
result.code	string	Указывает на результат обработки сценария.
result.result	string	ID созданного сценария.
reasons	array	Массив ошибок, произошедших во время обработки сценария.
reasons.key	string	Код ошибки.
description	string	Сообщение с описанием ошибки.

Примеры ответов¶

OK

{
  "result": {
    "code": "OK",
    "result": "7003"
  }
}

REJECTED

{
  "result": null,
  "reasons": [
    {
      "key": "contactGroupIds.or.segmentIds.absent"
    }
  ],
  "description": "Ошибка валидации: contactGroupIds or segments absent"
}

Получение сценариев¶

Для получения сценариев OMNI-рассылок можно воспользоваться двумя методами:

GET /omni-task-api/tasks/{taskId}, чтобы получить один сценарий по его ID.
GET /omni-task-api/tasks, чтобы получить список сценариев, отсортированных по фильтрам.

В заголовках обоих методов необходимо передать данные авторизации.

Параметры запросов¶

Получение одного сценария

Параметр	Тип данных	Описание
taskId	integer	ID сценария рассылки.

Получение нескольких сценариев

Параметр	Тип данных	Описание
ascending	boolean	Порядок сортировки параметра `orderBy`: ○ `true` - по возрастанию. ○ `false` - по убыванию.
channel (optional)	string	Канал рассылки. Возможные значения: `EMAIL`, `OMNI`, `PUSH`, `SMS`, `VIBER`, `VK`, `WHATSAPP`. Канал `OMNI` используется для переотправки сообщений в другие каналы, триггерных рассылок, а также отправки транзакционных сообщений.
count	integer	Количество выводимых строк.
createdDateFrom (optional)	datetime	Дата создания рассылки - начало диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
createdDateTo (optional)	datetime	Дата создания рассылки - конец диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
startDateFrom (optional)	datetime	Дата начала рассылки - начало диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
startDateTo (optional)	datetime	Дата начала рассылки - конец диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
endDateFrom (optional)	datetime	Дата завершения рассылки - начало диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
endDateTo (optional)	datetime	Дата завершения рассылки - конец диапазона. Формат: `YYYY-MM-DD hh:mm:ss`.
includedStates (optional)	array[string]	Статусы рассылок, включенных в поиск. Возможные значения: ○ `DRAFT` - черновик. ○ `DELETED_DRAFT` - черновик удален. ○ `NEW` - новая. ○ `STARTED` - в процессе. ○ `STOPPED` - остановлена. ○ `FAILED` - произошла ошибка. ○ `STOPPED_BALANCE_BLOCKED` - остановлена, нехватка средств. ○ `STOPPED_NOT_WORKING_TIME` - остановлена, превышено время отправки. ○ `FINISHED` - завершена. ○ `DELETED_FINISHED` - завершенная рассылка удалена.
excludedStates (optional)	array[string]	Статусы рассылок, исключенных из поиска. Возможные значения: ○ `DRAFT` - черновик. ○ `DELETED_DRAFT` - черновик удален. ○ `NEW` - новая. ○ `STARTED` - в процессе. ○ `STOPPED` - остановлена. ○ `FAILED` - произошла ошибка. ○ `STOPPED_BALANCE_BLOCKED` - остановлена, нехватка средств. ○ `STOPPED_NOT_WORKING_TIME` - остановлена, превышено время отправки. ○ `FINISHED` - завершена. ○ `DELETED_FINISHED` - завершенная рассылка удалена.
name (optional)	string	Название рассылки.
offset	integer	Номер строки, с которой будет выводиться результат (смещение).
orderBy	string	Поле, по которому будут отсортированы результаты поиска. Возможные значения: ○ `ID` - ID рассылки. ○ `NAME` - название рассылки. ○ `STATE` - статус рассылки. ○ `CREATION_DATE` - дата создания рассылки.
types (optional)	array[string]	Типы рассылок. Возможные значения: ○ `API` - отправка транзакционных сообщений через API. Единственный тип рассылок, для которого нужно использовать дополнительные методы. ○ `BIRTHDAY` - рассылка по дням рождения контактов. ○ `PERIODIC` - периодическая рассылка. ○ `SIMPLE` - одноразовая рассылка. ○ `EVENT_FLOW` - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK. ○ `GEO` - рассылка по геолокации контакта. Только для канала `PUSH`.

Примеры запросов¶

Получение одного сценария

curl -X GET "https://api.devino.online/omni-task-api/tasks/7003" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2"

Получение нескольких сценариев

curl -X GET "https://api.devino.online/omni-task-api/tasks?ascending=true&count=10&offset=0&orderBy=ID" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2"

Параметры ответа¶

Параметр	Тип данных	Описание
id	integer	ID рассылки.
taskName	integer	Название рассылки.
userId	integer	ID пользователя.
companyId	integer	ID компании.
officeId	integer	ID представительства.
creationDate	string	Дата и время создания рассылки.
type	string	Тип рассылки. Возможные значения: ○ `API` - отправка транзакционных сообщений через API. Единственный тип рассылок, для которого нужно использовать дополнительные методы. ○ `BIRTHDAY` - рассылка по дням рождения контактов. ○ `PERIODIC` - периодическая рассылка. ○ `SIMPLE` - одноразовая рассылка. ○ `EVENT_FLOW` - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK. ○ `GEO` - рассылка по геолокации контакта. Только для канала `PUSH`.
channel	string	Канал рассылки. Возможные значения: `EMAIL`, `OMNI`, `PUSH`, `SMS`, `VIBER`, `VK`, `WHATSAPP`. Канал `OMNI` используется для переотправки сообщений в другие каналы, триггерных рассылок, а также отправки транзакционных сообщений.
taskInfo	TaskInfo	Тип сценария, который активирует триггерную рассылку.
locationCount	integer	Количество локаций. Используется для гео-рассылок.
state	string	Статус рассылки. Возможные значения: ○ `DRAFT` - черновик. ○ `DELETED_DRAFT` - черновик удален. ○ `NEW` - новая. ○ `STARTED` - в процессе. ○ `STOPPED` - остановлена. ○ `FAILED` - произошла ошибка. ○ `STOPPED_BALANCE_BLOCKED` - остановлена, нехватка средств. ○ `STOPPED_NOT_WORKING_TIME` - остановлена, превышено время отправки. ○ `FINISHED` - завершена. ○ `DELETED_FINISHED` - завершенная рассылка удалена.
triggersInfo	array[TriggersInfo]	Параметры триггеров.

TriggersInfo¶

Параметр	Тип данных	Описание
triggerId	integer	ID триггера.
parentTriggerId (optional)	integer	ID родительского триггера.
taskId	integer	ID рассылки.
channel	string	Канал триггера. Возможные значения: `EMAIL`, `FLASHCALL`, `HLR`, `PUSH`, `PUSH_WALLET`, `SMS`, `VIBER`, `VK`, `VOICE`, `WHATSAPP`.
state	string	Статус триггера. Возможные значения: ○ `NEW` - новая. ○ `STARTED` - в процессе. ○ `STOPPED` - остановлена. ○ `FAILED` - произошла ошибка. ○ `FINISHED` - завершена.
userId	integer	ID пользователя.
externalId	string	Внешний ID пользователя, назначенный поставщиком.
companyId	integer	ID компании.
officeId	integer	ID представительства.
startTime	datetime	Дата старта триггера.
endTime	datetime	Дата окончания триггера.
type	string	Тип триггера. Возможные значения: ○ `ADDRESS_BOOK_SOURCE` - стандартная рассылка. ○ `TRAN_API_SOURCE` - отправка транзакционных сообщений по API. ○ `EVENT_COLLECTOR` - повторяющаяся рассылка по событиям. ○ `EVENT_SOURCE` - рассылка по событиям. ○ `NO_EVENT_SOURCE` - рассылка по истекшему времени ожидания события. ○ `GEO_LOCATION` - гео-рассылка. Только для канала `PUSH`.
counters	TriggerCounters	Список счетчиков.

TriggerCounters¶

Параметр	Тип данных	Описание
totalCount	integer	Количество контактов на момент начала рассылки.
successCount	integer	Количество принятых транспортом контактов.
processedWithoutSendCount	integer	Количество обработанных сообщений, в том числе неотправленных.
errorCount	integer	Количество отклоненных транспортом контактов.
exportTotalCount	integer	Количество обработанных контактов на момент окончания рассылки.

Пример ответа¶

{
  "result": {
    "id": "7003",
    "taskName": "NEW_SMS",
    "userId": 22,
    "companyId": 50,
    "officeId": 1,
    "creationDate": "2020-06-02 07:59:08",
    "type": "SIMPLE",
    "channel": "SMS",
    "state": "NEW",
    "triggersInfo": [
      {
        "triggerId": "511",
        "taskId": "7003",
        "userId": 22,
        "companyId": 50,
        "officeId": 1,
        "startTime": "2020-06-02 11:00:00",
        "endTime": "2020-06-02 12:00:00",
        "state": "NEW",
        "type": "ADDRESS_BOOK_SOURCE",
        "channel": "SMS",
        "counters": {
          "totalCount": 1,
          "successCount": 0,
          "errorCount": 0
        },
        "externalId": "CAEF899C-C583-4DA4-B06D-8D364E6E14DE"
      }
    ]
  }
}

Отправка транзакционных сообщений¶

Для отправки транзакционных сообщений предварительно нужно создать сценарий рассылки. Обязательно нужно передать параметры "task.type": "API" и "triggers.type": "TRAN_API_SOURCE".

Затем необходимо вызывать метод POST /omni-scheduler/api/messages, передавая данные контакта, сообщения и сценария в теле запроса и данные авторизации в заголовке.

Примечание

Отправка push-сообщений возможна не только с использованием pushToken, но и с использованием номера телефона. Для этого у контакта должен быть номер телефона, чтобы система могла найти соответствующие ему токены.

Параметры запроса¶

Важно

Вместе с параметром taskId необходимо использовать либо contactIds, либо contacts.

Параметр	Тип данных	Описание
taskId	integer	ID сценария рассылки, на базе которого будет отправляться сообщение.
contactIds (optional)	array[string]	ID контактов из адресных книг, которым будет отправлено сообщение.
contacts (optional)	array[Contacts]	Данные контактов. Максимальное количество контактов - 1000.
templates (optional)	object	Данные шаблонов транзакционного сообщения. Название объекта - это ID триггера из параметра `triggers.index`. Шаблоны в данном параметре будут более приоритетны, чем шаблоны изначального сценария.

Contacts¶

Параметр Тип данных Описание

contact object Данные контакта.

callbackUrl
(optional)

string

URL, на который система будет отправлять уведомления об изменениях статуса сообщения.

Любой валидный URL со схемой HTTP или HTTPS.

callbackData
(optional)

object

Данные, которые будут указаны в коллбэке со статусом сообщения.

Любой массив вида "key":
{ "key1": "value1", "key2": "value2" }

Данные контакта¶

Параметр	Тип данных	Описание
email (optional)	string	Email-адрес контакта.
phone (optional)	string	Номер телефона контакта в международном формате, согласно стандарту E.164.
pushInfo (optional)	array[PushInfo]	Данные push-уведомления.
fields (optional)	array[Fields]	Параметры макросов (полей) контактов в списке, в том числе и основных полей контакта.

PushInfo¶

Параметр Тип данных Описание

appId string ID приложения.

os

integer

Операционная система.

Возможные значения:
○ 0 - iOS.
○ 1 - Android.

pushToken string Токен устройства.

Fields¶

Параметр	Тип данных	Описание
name	string	Название поля.
displayName (optional)	string	Название поля в личном кабинете.
type (optional)	string	Тип поля. Возможные значения: ○ `0` - дата/время ○ `1` - `TRUE`/`FALSE` ○ `2` - число ○ `3` - текст ○ `5` - объект ○ `8` - дата
value	array[string]	Значение поля.

Примеры запросов¶

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

Для создания сценария для транзакционных сообщений необходимо воспользоваться соответствующим методом.

{
  "taskName": "TRANSACTIONAL_CASCADE",
  "type": "API",
  "channel": "OMNI",
  "addressBookSource": {
    "contactGroupIds": [111],
    "addressBookSourceType": "SIMPLE",
    "period": "ONCE"
  },
  "triggers": [
    {
      "index": 0,
      "startTime": "2020-06-02 11:00:00",
      "endTime": "2020-06-02 12:00:00",
      "type": "TRAN_API_SOURCE",
      "channel": "EMAIL",
      "template": {
        "emailTemplate": {
          "htmlBody": "We have a new shop!",
          "sourceAddress": "testadr@newshop",
          "sourceName": "TESTADR",
          "subject": "New shop"
        }
      }     
    },
    {
      "index": 1,
      "parentIndex": 0,
      "startTime": "2020-06-02 12:00:00",
      "endTime": "2020-06-02 13:00:00",
      "type": "NO_EVENT_SOURCE",
      "channel": "SMS",   
      "eventSources": [
        {
          "channel": "EMAIL",
          "eventType": "STATE",
          "eventValue": "delivered"
        }
      ],
      "template": {    
        "smsTemplate": {
          "text": "We have new shop!",
          "from": "TESTADR",
          "validity": 600
        }
      }
    }
  ]
}

Отправка транзакционного сообщения

{
  "contacts": [
    {
      "contact": {
        "email": "ivan@yandex.ru",
        "phone": "79103398080"
      }
    }
  ],
  "taskId": 7004,
  "templates": {
    "0": {   
        "emailTemplate": {
            "htmlBody": "<html><h1>У нас новый магазин!</h1><a id=\"unsubscribe-link\" href=\"${Unsubscribe}\" style=\"color: rgb(0, 122, 255); text-decoration: none;\">Отписаться от рассылки</a> | <a id=\"web-version-link\" href=\"${WebVersion}\" style=\"color: rgb(0, 122, 255); text-decoration: none;\">Web Версия</a></html>",
            "sourceAddress": "test@shop.org",
            "sourceName": "TEST",
            "subject": "Новый магазин"
        }
    },
    "1": { 
        "smsTemplate": {
            "text": "У нас новый магазин!",
            "from": "TESTADR",
            "validity": 600
        }
    }
  }
}

Параметры ответа¶

Параметр	Тип данных	Описание
contactIds	array[string]	Массив ID загруженных контактов.
sendAnswers	array[SendAnswers]	Массив успешно отправленных сообщений.
errorAnswers	array[ErrorAnswers]	Массив неуспешно отправленных сообщений.

SendAnswers¶

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки сообщения. 1. `OK` - успешно обработано. 2. `REJECTED` - произошла ошибка во время обработки запроса.
mergeKey	string	ID загруженного контакта.
result	string	ID отправленного сообщения.
reasons	array	Массив ошибок, произошедших во время обработки сообщения. Указывается только при `"code": "REJECTED"`.
reasons.key	string	Код ошибки.
reasons.ref	string	Ссылка на параметр, в котором произошла ошибка.

ErrorAnswers¶

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки сообщения. 1. `OK` - успешно обработано. 2. `REJECTED` - произошла ошибка во время обработки запроса.
result	string	ID отправленного сообщения.
description	string	Описание ошибки.
reasons	array	Массив ошибок, произошедших во время обработки сообщения. Указывается только при `"code": "REJECTED"`.
reasons.key	string	Код ошибки.
reasons.ref	string	Ссылка на параметр, в котором произошла ошибка.

Пример ответа¶

OK

{
  "result": {
    "contactIds": [
      "33790c4716534800-33790c47226a5280"
    ],
    "sendAnswers": [
      {
        "code": "OK",
        "result": "3709009333448258816",
        "mergeKey": "33790c4716534800-33790c47226a5280"
      }
    ],
    "errorAnswers": []
  }
}

REJECTED

{
  "result": {
    "contactIds": [
      "33790bea91534800-33790bea9e8a5280"
    ],
    "sendAnswers": [
      {
        "code": "REJECTED",
        "result": null,
        "reasons": [
          {
            "key": "not.available",
            "ref": "from"
          }
        ],
        "description": "Error: Source address in not available. Source address: TEST",
        "mergeKey": "33790bea91534800-33790bea9e8a5280"
      }
    ],
    "errorAnswers": []
  }
}

Коллбэки для транзакционных сообщений¶

Как подключить

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

Возможные статусы¶

Статус	Канал	Описание
delivered	SMS, Viber, Email, Push, WhatsApp, VK	Сообщение доставлено получателю.
seen	Viber, WhatsApp	Сообщение было прочитано.
undeliverable	SMS, Viber	Сообщение невозможно доставить.
unknown	SMS, Viber	Неизвестная ошибка.
rejected	SMS, Viber, Email, Push, WhatsApp, VK	Сообщение было отклонено оператором или Devino.Online.
expired	SMS, Viber, Push, WhatsApp, VK	Истек срок жизни сообщения.
deleted	SMS, Viber	Сообщение было удалено.
send_error	SMS, Viber, Email, Push, WhatsApp, VK	Ошибка отправки сообщения.
bounced	Email	Не удалось доставить сообщение.
canceled	Push	Получатель смахнул уведомление с экрана.

Статистика по рассылкам¶

Для получения статистики по рассылкам необходимо вызвать GET /statistics/sales/by-task, передавая параметры статистики и данные авторизации в заголовке.

Информация

Статистика формируется на основе данных, переданных в событии DevinoOrderEvent.

Параметры запроса¶

Параметр	Тип данных	Описание
taskIds	array[integer]	ID рассылок.
dateTimeFrom (optional)	datetime	Дата начала поиска. Формат - `YYYY-MM-DD%hh:mm:ss`.
dateTimeTo (optional)	datetime	Дата окончания поиска. Формат - `YYYY-MM-DD%hh:mm:ss`.
zoneOffset (optional)	integer	Смещение времени для контакта от `UTC+0` в минутах.
cartId (optional)	string	ID корзины.
contactId (optional)	string	ID контакта.
contactGroup (optional)	string	Список, к которому принадлежит контакт.
contactPhone (optional)	string	Номер телефона контакта.
contactEmail (optional)	string	Email контакта.
userId (optional)	string	ID пользователя.
utmSource (optional)	string	Данные метки `utmSource`.
webSdkSettingsId (optional)	string	ID параметров Web SDK.

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

curl -X GET "https://api.devino.online/statistics/sales/by-event-time?dateTimeFrom=2021-02-01%20:00:00&dateTimeTo=2021-02-05%20:00:00" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
-H "Content-Type: application/json"

Параметры ответа¶

Параметр	Тип данных	Описание
taskId	integer	ID рассылки.
totalCount	integer	Количество заказов.
totalSum	number	Общая выручка.
averageCheck	number	Средний чек по заказам.

Пример ответа¶

{
  "result": [
    {
      "taskId": 384,
      "totalCount": 10,
      "totalSum": 33576.971,
      "averageCheck": 3357.6971
    },
    {
      "taskId": 385,
      "totalCount": 8,
      "totalSum": 12581.54,
      "averageCheck": 1572.6925
    }
  ]
}

Contact¶

Объект contact содержит персональные данные пользователя. Атрибуты контакта используются как переменные (макросы) в текстах транзакционных сообщений.

Доступ к атрибутам контакта можно получить через язык разметки Freemarker.

Базовые атрибуты контакта¶

Параметр	Описание
name	Имя.
surname	Фамилия.
phone	Номер телефона.
email	Email.
gender	Пол с возможными значениями `gender.male` и `gender.female`.
country	Страна.
city	Город.
birthdate	Дата рождения.
creationDate	Дата создания контакта.
lastUpdate	Дата последнего изменения контакта.
timezone	Часовой пояс контакта.
pushInfo	Данные, необходимые для получения push-уведомлений.

Совет

Можно использовать не только базовые, но и пользовательские атрибуты. Их можно задать в личном кабинете или при создании списка контактов.

Если сообщение отправляется по событию с вашего сайта, то у объекта Contact появляется атрибут EventInfoList - список передаваемых с сайта объектов.

Динамический контент¶

В текстах транзакционных сообщений можно использовать FreeMarker — механизм шаблонизации. С Freemarker можно управлять динамическим контентом.

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

${...}: будет заменено на значение или выражение, указанное внутри фигурных скобок.
<#tag> - теги: похожи на HTML, но начинаются с #.
<#-- ... --> - комментарии: не попадут в конечное письмо, в отличии от комментариев HTML.

Вывод значений и выражений¶

Для вывода значений используется разметка ${...}. В данном примере мы использовали атрибуты name и email объекта Contact.

<html lang="en">
<body>
    <h1>Hi, ${contact.name}</h1> 
    <p>Thanks for registration!</p>
    <p>If you need help visit <a href="https://example.com/help?email=${contact.email}">Help</a> page</p>
</body>
</html>

Для пользователя John Doe с адресом электронной почты john@customer.net HTML-письмо примет следующий вид:

<html lang="en">
<body>
    <h1>Hi, John Doe</h1>
    <p>Thanks for registration!</p>
    <p>If you need help visit <a href="https://example.com/help?email=john@customer.net">Help</a> page</p>
</body>
</html>

Для проведения расчётов можно использовать выражения прямо внутри ${}:

<html lang="en">
<body>
    <h1>${contact.name?capitalize}, special offer!</h1>
    <p>Buy goods in the category "Everything for home"
        with a ${(1 + contact.loyalty_discount_rate)*20}% discount!</p>
</body>
</html>

В данном примере loyalty_discount_rate – пользовательский атрибут контакта, в котором указывается коэффициент повышения процента скидки для каждого контакта. Чтобы рассчитать конечную скидку, мы умножаем её на базовую скидку 20%.

Поддерживаемые выражения¶

Ниже мы указали самые популярные выражения. Подробнее в документации Freemarker.

Переменные. Вывод значения переменной - основной вид использования динамического контента в сообщениях и письмах. Помимо contact, можно создавать свои переменные.
Списки.
- EventInfoList[0] - доступ к любому элемента из списка.
- ?first, ?last - первый и последний элементы списка.
- ?join(sep) - объединение всех элементов списка:
```
my list: ${list?join(",")}}

// Output
my list: 0,1,2,3
```
- ?min, ?max - наименьший и наибольший объект списка.
- ?size - число элементов в списке.
Строки.
- ?upper_case, ?lower_case, ?capitalize - все слова в строке будут приведены к верхнему или нижнему регистру или будут начинаться с прописной буквы.
- ?length - длина строки.
- ?truncate - обрезка текста до указанной длины:
  - ${"Women Shoes"?truncate(10)} -> "Women[...]", потому что данная функция после обрезания строки прибавляет [...].
  - ${product.name?truncate(5, '---')} -> "Wo---", потому что данная функция позволяет задать символы, которые будут добавлены в конце строки.
Числа.
- ?round - округление до ближайшего целого числа. Если оно заканчивается на 0.5, оно округляется в большую сторону.
- ?floor - округление в меньшую сторону.
- ?ceiling - округление в большую сторону.
- ?string - перевод числа в строку и форматирование чисел.

Определение переменных¶

Создание произвольной переменной и присвоение ей значения:

<#assign positionSum = 4200000> - создает числовую переменную.
<#assign subscriberTitle = "Attention"> - создает строковую переменную.

Математические операции¶

Могут быть использованы чтобы:

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

Примеры:

${positionSum * 0.50}
${positionSum * 0.25 / 100}%
<p class="sale">${(product.oldPrice-product.price)/product.oldPrice*100}%</p>

Форматирование чисел¶

Преобразование вывода и округление. Это нужно, если требуется выводить размер скидки с одним разрядом после запятой, чтобы не получить значение 12.23472100012%.

Для примера берем price = 12.234721
- ${price?string["0"]} - выведет 12
- ${price?string["0.#"]} - выведет 12.2
- ${price?string["0.##"]} - выведет 12.23
- ${price?string["0.###"]} - выведет 12.235
- ${price?string["0.####"]} - выведет 12.2347

Логические условия¶

Допустимы следующие логические конструкции:

<#if condition>
  ...
<#elseif condition2>
  ...
<#elseif condition3>
  ...
<#else>
  ...
</#if>

Примеры¶

Имя подписчика не заполнено¶

Например, если нужно вывести имя подписчика, можно вывести его так: "Привет, ${contact.name}!"

Если у подписчика нет имени, он увидит текст с лишними запятой и пробелом: "Привет, !"

Подходящие варианты:

"Привет<#if (contact.name?length>1)>, ${contact.name?capitalize}!"
"Привет<#if contact.name??>, ${contact.name?capitalize}!"
"Привет<#if contact.name?has_content>, ${contact.name?capitalize}!"

Вывод/сокрытие блока для подписчиков по условию¶

В письме магазина товаров для животных должно содержаться 3 баннера. Владельцу собаки не нужно показывать баннер, который подойдет владельцу кошки или попугая.

Без условия:

<a href="#"><img src="/banner-dog.png"></a><br />
<a href="#"><img src="/banner-cat.png"></a><br />
<a href="#"><img src="/banner-bird.png"></a>

С условием:

<#if ${contact.pet}="собака">
    <a href="#"><img src="/banner-dog.png"></a>
<#else>
    <a href="#"><img src="/banner-cat.png"></a>
    <a href="#"><img src="/banner-bird.png"></a>
</#if>

Циклы¶

Примеры¶

Вывод массива товаров для триггеров¶

Верстальщик оформляет код одной карточки товаров, который с помощью цикла можно размножить по количеству указанных в письме товаров.

<#list contact.EventInfoList as event>
    <div class="product">
        <a href="${event.productURL}"><img src="${event.productImg}" /></a>
        <p class="product-title"><a href="${event.productURL}">${event.productName}</a></p>
        <p class="product-price"><a href="${event.productURL}">Цена ${event.productPrice} руб.</a></p>
    </div>
</#list>

Фильтр в цикле¶

Клиент решает не показывать подписчикам товары дешевле 1500 рублей.

<#list contact.EventInfoList as event>
    <#if ${event.productPrice}<1500><#continue></#if>
    <div class="product"><a href="${event.productURL}"><img src="${event.productImg}" /></a>
    <p class="product-title"><a href="${event.productURL}">${event.productName}</a></p>
    <p class="product-price"><a href="${event.productURL}">Цена ${event.productPrice}} руб.</a></p>
</#list>

Проверка на наличие значений в цикле¶

Если цикл пустой, нужно вывести сообщение о том, что товаров нет.

<#list contact.EventInfoList as event>
    <div class="product"><a href="${event.productURL}"><img src="${event.productImg}" /></a>
    <p class="product-title"><a href="${event.productURL}">${event.productName}</a></p>
    <p class="product-price"><a href="${event.productURL}">Цена ${event.productPrice}} руб.</a></p>
    <#else>
    No products
</#list>

Добавление разделителя между элементами цикла¶

Для добавления разделителя между элементами цикла можно использовать директиву <#sep>, которая добавляет код после каждого элемента цикла, кроме последнего.

<#list contact.EventInfoList as event>
    <p class="categoryTitle"><a href="${event.categoryUrl}">${event.categoryTitle}</a></p>
    <#sep>, </#sep>
</#list>

Отмена отправки сообщения¶

В некоторых ситуациях, особенно при обработке событию с вашего сайта, может понадобиться отмена отправки.

Для этого используйте функцию cancelMessage(reason) в комбинации с проверкой по условию <#if>:

<html lang="en">
<body>
    <#if ${contact.loyalty_level} == 0>
        <#return cancelMessage("Низкий loyalty_level") />
    <#/if>
    <h1>${contact.name?capitalize}, special offer!</h1>
    <p>Buy goods in the category "Everything for home"
        with a ${(1 + contact.loyalty_discount_rate)*20}% discount!</p>
</body>
</html>

Получение макросов¶

Для получения макросов (полей) рассылок необходимо вызвать метод GET /omni-task-api/macros, передавая параметры ID и статусы рассылок в заголовке с указанием данных авторизации.

Параметры запроса¶

Параметр Тип данных Описание

taskIds
(optional) array[integer] ID рассылок, из которых нужно получить макросы.

taskStates
(optional)

array[string]

Статусы рассылок, включенных в поиск.

Возможные значения:
○ DRAFT - черновик.
○ DELETED_DRAFT - черновик удален.
○ NEW - новая.
○ STARTED - в процессе.
○ STOPPED - остановлена.
○ FAILED - произошла ошибка.
○ STOPPED_BALANCE_BLOCKED - остановлена, нехватка средств.
○ STOPPED_NOT_WORKING_TIME - остановлена, превышено время отправки.
○ FINISHED - завершена.
○ DELETED_FINISHED - завершенная рассылка удалена.

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

curl -X GET "https://api.devino.online/omni-task-api/macros?taskIds=2435235&taskIds=34423&taskStates=FINISHED \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Параметры ответа¶

Параметр	Тип данных	Описание
task	Task	Параметры сценария рассылки.
macros	array[string]	Список всех используемых макросов, в том числе, и макросов контакта.
contact	array[string]	Список макросов контакта.

Пример ответа¶

{
  "result": [
    {
      "task": {
        "id": "7004",
        "taskName": "TRANSACTIONAL_CASCADE",
        "userId": 22,
        "companyId": 50,
        "officeId": 1,
        "creationDate": "2020-06-02 11:00:00",
        "type": "SIMPLE",
        "channel": "OMNI",
        "state": "FINISHED",
        "triggersInfo": [
          {
            "triggerId": "321",
            "taskId": "7004",
            "userId": 22,
            "companyId": 50,
            "officeId": 1,
            "startTime": "2020-06-02 11:00:00",
            "endTime": "2020-06-02 12:00:00",
            "state": "FINISHED",
            "type": "ADDRESS_BOOK_SOURCE",
            "channel": "SMS",
            "counters": {
              "totalCount": 79834,
              "successCount": 0,
              "errorCount": 43674,
              "exportTotalCount": 79834,
              "processedWithoutSendCount": 0
            },
            "externalId": "4A8F5B75-29ED-473B-7AA0-4FC4507A41280"
          }
        ]
      },
      "macros": [
        "Unsubscribe", 
        "WebVersion",
        "city",
        "timezone",
        "name"
      ],
      "contact": [
        "city",
        "timezone",
        "name"
      ]
    }
  ]
}