Перейти к содержанию

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 - одноразовая рассылка.

Значения, для которых возможно использование только канала EMAIL:
AB_TEST - для А/Б тестирования.
EVENT_FLOW - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK.
GEO - рассылка по геолокации контакта.

AddressBookSource

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

Тип адресной книги, используется для фильтрации.

Возможные значения:
AB_TEST - для А/Б тестирования. Используется в email-рассылках.
AB_TEST_WINNER - для выбранных контактом вариантов в А/Б тестировании.
BIRTHDAY - рассылка по дням рождения контактов.
PERIODIC - периодическая рассылка.
SIMPLE - одноразовая рассылка.

byOptimalSendTime
(optional)
boolean Персонализированное время отправки. При выборе этой опции контакты получат письма в рассчитанное персонализированное время. Рассылка может продлиться 24 часа с момента запуска.
byTimeZone
(optional)
boolean Учет местного времени контакта при отправке.
checkDuplicate
(optional)
boolean Проверка дубликатов контактов в адресной книге. Дубликатам сообщение отправляться не будет.
contactCountId
(optional)
integer ID количества контактов в адресной книге.
contactGroupIds array[integer] Массив ID групп контактов в адресной книге.
stopContactGroupIds
(optional)
array[integer] Массив ID стоп-листов контактов. Этим контактам рассылка производиться не будет.
period
(optional)
string Периодичность.
Используется при "type": "PERIODIC".

Возможные значения:
ONCE - один раз.
DAILY - ежедневно.
WEEKLY - еженедельно.
MONTHLY - ежемесячно.

segmentIds
(optional)
array[integer] Массив ID сегментов внутри групп контактов адресной книги, если группа контактов разделена на сегменты.
smoothSendMinutes
(optional)
integer Плавная отправка, задается в минутах.

Минимальное значение: 0
Максимальное значение: 1140, 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 - рассылка по истекшему времени ожидания события.

Значения, для которых возможно использование только канала EMAIL:
EVENT_COLLECTOR - повторяющаяся рассылка по событиям.
GEO_LOCATION - гео-рассылка.

index integer ID триггера.
parentIndex
(optional)
integer ID родительского триггера. С помощью данного параметра можно настраивать последовательность триггеров.
startTime
(optional)
string Дата старта триггера.
endTime
(optional)
string Дата окончания триггера.
eventSources
(optional)
array[EventSources] Массив событий для совершения рассылок.
eventCollectorSettings
(optional)
EventCollectorSettings Параметры повторяющихся рассылок по событиям. Данный вид событий может быть отменен только другими триггерами.
geoSettings
(optional)
GeoSettings Параметры гео-рассылок.
noEventSourceSettings
(optional)
NoEventSourceSettings

Содержит параметр: stateWaitMaxTimeSec (integer) - время ожидания события в секундах.

Событие задается в отдельном триггере, в объекте EventSources. Индекс этого триггера должен быть указан в parentIndex. Когда время ожидания проходит, сообщение отправляется по дочернему триггеру.

template
(optional)
Template Массив шаблонов сообщений.
EventSources
Параметр Тип данных Описание
channel
(optional)
string

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

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

eventType string

Тип события.

Возможные значения:
CONTACT_MOBILE_EVENT - событие для гео-рассылок. Используется только с каналом EMAIL.
CONTACT_WEB_EVENT - событие в веб-интерфейсе. Используется только с каналом EMAIL.
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 приложений, в которых будет проведена рассылка.

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

Совет

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

Параметр Тип данных Описание
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, то ссылка будет сокращена. По умолчанию 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
(optional)
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

Cписок возможных каналов доставки через запятую
(пример: [ 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.

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

{
  "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
        }
      }
    }
  ]
}

Отправляем сообщение в 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": "Тестовое сообщение"
        }
      }
    }
  ]
}

Если пользователь не успел заполнить анкету на сайте, после 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 Сообщение с описанием ошибки.

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

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

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

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

  1. GET /omni-task-api/tasks/{taskId}, чтобы получить один сценарий по его ID.
  2. 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)
string Дата создания рассылки - начало диапазона.
Формат: YYYY-MM-DD HH:MM:SS.
createdDateTo
(optional)
string Дата создания рассылки - конец диапазона.
Формат: YYYY-MM-DD HH:MM:SS.
startDateFrom
(optional)
string Дата начала рассылки - начало диапазона.
Формат: YYYY-MM-DD HH:MM:SS.
startDateTo
(optional)
string Дата начала рассылки - конец диапазона.
Формат: YYYY-MM-DD HH:MM:SS.
endDateFrom
(optional)
string Дата завершения рассылки - начало диапазона.
Формат: YYYY-MM-DD HH:MM:SS.
endDateTo
(optional)
string Дата завершения рассылки - конец диапазона.
Формат: 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 - одноразовая рассылка.

Значения, для которых возможно использование только канала EMAIL:
AB_TEST - для А/Б тестирования.
EVENT_FLOW - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK.
GEO - рассылка по геолокации контакта.

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

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 - одноразовая рассылка.

Значения, для которых возможно использование только канала EMAIL:
AB_TEST - для А/Б тестирования.
EVENT_FLOW - рассылка по триггерным событиям. Для данного типа рассылок должен быть настроен Web SDK.
GEO - рассылка по геолокации контакта.

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 string Дата старта триггера.
endTime string Дата окончания триггера.
type string

Тип триггера.

Возможные значения:
ADDRESS_BOOK_SOURCE - стандартная рассылка.
TRAN_API_SOURCE - отправка транзакционных сообщений по API.
EVENT_COLLECTOR - повторяющаяся рассылка по событиям.
EVENT_SOURCE - рассылка по событиям.

Значения, для которых возможно использование только канала EMAIL:
NO_EVENT_SOURCE - рассылка по истекшему времени ожидания события.
GEO_LOCATION - гео-рассылка.

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] Данные контактов. Максимальное количество контактов - 2000.
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 Ссылка на параметр, в котором произошла ошибка.

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

{
  "result": {
    "contactIds": [
      "33790c4716534800-33790c47226a5280"
    ],
    "sendAnswers": [
      {
        "code": "OK",
        "result": "3709009333448258816",
        "mergeKey": "33790c4716534800-33790c47226a5280"
      }
    ],
    "errorAnswers": []
  }
}
{
  "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 Получатель смахнул уведомление с экрана.

Contact

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

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

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

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

Совет

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

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

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

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

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

  • ${...}: будет заменено на значение или выражение, указанное внутри фигурных скобок.
  • <#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-->!"
  • "Привет<#if contact.name??>, ${contact.name?capitalize}<!--#if-->!"
  • "Привет<#if contact.name?has_content>, ${contact.name?capitalize}<!--#if-->!"
Вывод/сокрытие блока для подписчиков по условию

В письме магазина товаров для животных должно содержаться 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"
      ]
    }
  ]
}