OMNI

Scenario creation

To create OMNI-campaign scenario it is required to call POST /omni-task-api/tasks, sending scenario parameters in the request body with authorization data in the header.

Request parameters

Parameter	Data type	Description
addressBookSource (optional)	AddressBookSource	Address book settings. Can not be used for transactional messages, where contacts are specified separately. Macros (fields) from address books can be used in message texts.
channel	string	Campaign channel. Possible values: EMAIL, OMNI, PUSH, SMS, VIBER, VK, WHATSAPP. The OMNI channel is used for resending messages to other channels, trigger campaigns and sending transactional messages.
draftId (optional)	integer	Email draft ID.
taskInfo (optional)	TaskInfo	Scenario type, which activates the triggered mailing.
taskName	string	The campaign name. From 1 to 100 characters.
triggers	Triggers	Trigger options.
type	string	Campaign type. Possible values: ○ API - sending transactional messages via API. It is the only campaign type for which you need to use additional methods. ○ BIRTHDAY - contacts' birthdays campaign. ○ PERIODIC - periodic campaign. ○ SIMPLE - one-time campaign. ○ EVENT_FLOW - sending by trigger events. For this type of campaigns, Web SDK must be configured. ○ GEO - contact's geolocation campaign. Only for PUSH channel.

AddressBookSource

Parameter	Data type	Description
addressBookSourceType	string	Address book type, used for filters. Possible values: ○ BIRTHDAY - contacts' birthdays campaign. ○ PERIODIC - periodic campaign. ○ SIMPLE - one-time mailing.
byOptimalSendTime (optional)	boolean	Personalized sending time. When you select this option, contacts will receive emails at the calculated personalized time. The campaign can last about 24 hours from the moment of launch.
byTimeZone (optional)	boolean	Taking into account local contact time when sending.
checkDuplicate (optional)	boolean	Check for duplicate contacts in the address book. The messages will not be sent to the duplicates.
contactCountId (optional)	integer	Contact number ID in the address book.
contactGroupIds	array[integer]	Contact group IDs array in the address book. Is not used with the segmentIds parameter.
stopContactGroupIds (optional)	array[integer]	Contact stoplist IDs array. The messages will not be sent to these contacts.
period (optional)	string	Campaign frequency. Used when "type": "PERIODIC". Possible values: ○ ONCE - once. ○ DAILY - daily. ○ WEEKLY - weekly. ○ MONTHLY - monthly.
segmentIds (optional)	array[integer]	Segment IDs array within contact groups of the address book if the contact group is segmented. Is not used with the contactGroupIds parameter.
smoothSendMinutes (optional)	integer	Smooth sending, set in minutes. Minimum value: 0 Maximum value: 1440, 1 day

TaskInfo

Parameter	Data type	Description
scenarioType (optional)	string	Scenario type. Used with "type": "EVENT_FLOW". Message will be sent if user abandoned: ○ abandonedCart - cart view. ○ abandonedProductView - product view. ○ abandonedCategoryView - category view.

Triggers

Parameter	Data type	Description
channel	string	Trigger channel. Possible values: EMAIL, FLASHCALL, HLR, PUSH, PUSH_WALLET, SMS, VIBER, VK, VOICE, WHATSAPP.
type	string	Trigger type. Possible values: ○ ADDRESS_BOOK_SOURCE - standard campaign. ○ TRAN_API_SOURCE - sending transactional messages via API . ○ EVENT_SOURCE - event campaign. ○ NO_EVENT_SOURCE - elapsed event campaign. ○ EVENT_COLLECTOR - repeated campaign. ○ GEO_LOCATION - geo-campaign. Only for PUSH channel.
index	integer	Trigger ID.
parentIndex (optional)	integer	Parent trigger ID. You can configure the trigger sequence with this parameter.
startTime (optional)	datetime	Trigger start date. The format is YYYY-MM-DD hh:mm:ss.
endTime (optional)	datetime	Trigger end date. The format is YYYY-MM-DD hh:mm:ss.
eventSources (optional)	array[EventSources]	Events array for sending campaigns.
eventCollectorSettings (optional)	EventCollectorSettings	Repeated event campaign parameters. This type of events can be canceled only by other triggers.
geoSettings (optional)	GeoSettings	Geo-campaigns parameters.
noEventSourceSettings (optional)	NoEventSourceSettings	Contains the parameter: stateWaitMaxTimeSec (integer) - event waiting time in seconds. The event is set in a separate trigger, in the EventSources object. The index of this trigger must be specified in parentIndex. After the time-out the message is sent through the child trigger.
template	Template	Message templates array.

EventSources

Parameter	Data type	Description
channel (optional)	string	Trigger channel. Possible values: EMAIL, FLASHCALL, HLR, PUSH, PUSH_WALLET, SMS, VIBER, VK, VOICE, WHATSAPP.
eventType	string	Event type. Possible values: ○ CONTACT_MOBILE_EVENT - event for geo-campaigns. Used only with the PUSH channel. ○ CONTACT_WEB_EVENT - an event in the web interface. ○ STATE - the status that the message must take in order to send it out. Can be used with any channel, including the OMNI channel for resending messages to other channels, trigger campaigns and sending transactional messages.
eventValue (optional)	string	Events that trigger the campaign. ○ "eventType": "CONTACT_MOBILE_EVENT" can only be used with GEO. The GeoSettings object must also be specified in the request. ○ "eventType": "CONTACT_WEB_EVENT" can only be used with Web SDK events. ○ "eventType": "STATE" can only be used with message statuses.

EventCollectorSettings

Parameter	Data type	Description
maxNewRegisterSec (optional)	integer	Time after the event in seconds. During that time the campaign will not be repeated.
onlyUpdateEventSources (optional)	array[EventSources]	The events array for repeated campaigns. After these events, the countdown will start in the maxNewRegisterSec parameter. If the event repeats, the countdown will start again.

GeoSettings

Parameter	Data type	Description
antiFraudMins (optional)	integer	The time in minutes to resend the message.
locationIds (optional)	array[integer]	Location IDs array.
pushApplicationIds (optional)	array[integer]	Application IDs array which will provide the campaign.

Template Filling

Tip

In message texts, you can use the Freemarker markup language to use the contact attributes and create dynamic content.

Template	Description
smsTemplate (optional)	SmsTemplate
viberTemplate (optional)	ViberTemplate
emailTemplate (optional)	EmailTemplate
pushTemplate (optional)	PushTemplate
pushWalletTemplate (optional)	PushWalletTemplate
whatsAppTemplate (optional)	WhatsAppSendMessageRequest
vkTemplate (optional)	VkTemplate

SmsTemplate

Parameter	Data type	Description
shortenUrl (optional)	boolean	If true, the system converts URLs in the message into shorter links. For example, if the parameter is enabled, the link https://www.example-url.com/my-example-param... will be converted to https://clickdo.integrationapi.net/link-hash. False by default.
from	string	Approved sender’s name.
text	string	Message text: ○ up to 17085 characters using Cyrillic. ○ up to 34170 characters using Latin.
validity	integer	Lifetime of the message in seconds. Minimal value: 0 Maximal value: 259200, 3 days Default value: 0

ViberTemplate

Parameter	Data type	Description
from	string	Sender's name used when sending the message. Only the senders' names which are available for using by the user can be used.
action (optional)	string	URL or deep link to which the user will go after clicking the button. The parameter is also used to specify the URL of the attached video or file. Button can only be used in a combination with other parameters.
caption (optional)	string	Button text, no more than 30 characters in UTF-8 encoding.
image (optional)	string	URL for the image in JPG, JPEG or PNG formats.
text (optional)	string	The message text, UTF-8 characters. The standard number of characters is no more than 1000. The maximum number of characters is 2000. If the standard number of characters in a Viber message exceeds 1000 characters, the message will be split into segments, which will be delivered successively, preserving the semantic content.
validity (optional)	integer	Lifetime of the message in seconds. Minimal value: 15 Maximal value: 1209600, 14 days Default value: 86400, 1 day

EmailTemplate

Parameter	Data type	Description
sourceAddress	string	Sender's email address. The domain must first be created and approved.
sourceName	string	Sender's name. Up to 150 characters.
subject	string	Email subject.
htmlBody	string	Email body in HTML format.
plainText (optional)	string	Email body in Plaintext format, all tags are displayed as plain text.
AttachmentsIds (optional)	array[string]	Files array attached to the letter.

PushTemplate

Parameter	Data type	Description
from	integer	Approved sender's ID.
title	string	Notification heading. The maximum length is 200 characters.
text	string	Notification text. The maximum length is 1024 characters.
badge (optional)	integer	The key that sets the value for the application badge - the icon with a number in the upper corner of the application icon. The number indicates unread notifications in the application. You can set any integer. To prevent the badge from being displayed, set the value of the parameter to 0 or delete this parameter.
validity (optional)	integer	Lifetime of the notification in seconds. Minimum value: 30 Maximum value: 86400, 1 day Default value: 86400, 1 day
platform (optional)	string	Platform or operating system of devices to which the notification will be sent. Available values: ○ ANDROID - Android devices. ○ IOS - iOS devices.
silentPush (optional)	boolean	If true, the notification will not be displayed on the recipient's device. False by default.
options (optional)	object	An object with the data which will be specified in the callback with the message status. Any "key" array: { "key1": "value1", "key2": "value2" }
apns (optional)	object	Fields, which are specific for iOS device.
android (optional)	object	Fields, which are specific for Android device.

PushWalletTemplate

Parameter	Data type	Description
from	string	Approved sender's ID.
payload	PushPayload	Message content settings.
callbackUrl (optional)	string	The URL to which the system will send notifications about message status changes. Any valid URL with the HTTP or HTTPS scheme.
callbackData (optional)	object	An object with the data which will be specified in the callback with the message status. Any "key" array: { "key1": "value1", "key2": "value2" }
mergeKey (optional)	string	Key to combine request and response.
validity (optional)	integer	Notification lifetime in seconds.

VkTemplate

Parameter	Data type	Description
routes	array	List of possible transport channels separated by comma (example: [ VK, OK ]). ○ VK - delivery on behalf of the official VK group. ○ OK - delivery on behalf of the official Odnoklassniki group. VK by default. Delivery is made before the physical device firstly gets the notification. When specifying several transport channels, only one of the channels will be eventually used. The sequence and logic of the selected routes is configured when connecting to the system. If the parameter is not specified, all possible delivery methods are used by default. The delivery will occur only if a certain group in the corresponding social network is specified in the template. For example, if only the VK group is specified in the template, then delivery to Odnoklassniki group using this template will not occur.
delivery_policy	string	Possible values: any, mobile_device_required, verified_phone_number By default any. If mobile_device_required is specified, then the message will be delivered only if the user has a mobile app and has used it within the last 7 days. In this case, message will be delivered to all available devices, not just the mobile ones. If verified_phone_number is specified, then the message will be delivered only to those users whose phone number is additionally checked for relevance.
validity (optional)	integer	Lifetime of the message in seconds. Minimal value: 60 Maximal value: 86400, 1 day Default value: 86400 If the message is not delivered within the ttl time, it will not be delivered and charged.
templateId (optional)	integer	Message template ID in Devino.
templateData	object	JSON-object, where keys are the variable names in the template. For example, for the template: You have received a package at { address }. Confirmation code - { code }, - the parameter tmpl_data will imply: { "address": "Downing st, 6", "code": "485372" }.
callbackData (optional)	object	An object with the data which will be specified in the callback with the message status. Any "key" array: { "key1": "value1", "key2": "value2" }
callbackUrl (optional)	string	The URL to which the system will send callbacks when the message status changes. Any valid URL with the HTTP or HTTPS scheme.

Request examples

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": "We opened a new shop!",
          "from": "TEST",
          "validity": 600
        }
      }
    }
  ]
}

NO_EVENT_SOURCE

We send a message through SMS. If it is delivered, the campaign ends. If it is not delivered, we send an Email.

{
  "taskName": "Campaign repeat",
  "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": "First message",
          "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": "Second message if first was not delivered",
          "sourceAddress": "test@test",
          "sourceName": "TEST",
          "subject": "Test message"
        }
      }
    }
  ]
}

EVENT_COLLECTOR

If the user did not have time to fill the application on the site, after 100 seconds of waiting, we send an Email.

If the user has not completed filling out the application in a day, we send another Email. If the user has completed the application filling, we complete the event and do not send anything.

{
  "taskName": "Suggestion to complete the application filling",
  "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": "Complete the application filling",
          "sourceAddress": "test@test",
          "sourceName": "TEST",
          "subject": "Test message"
        }
      }
    }
  ]
}

Response parameters

Parameter	Data type	Description
result	string	Scenario data array. To be given with "code": "OK" only.
result.code	string	Shows the result of scenario processing.
result.result	string	Created scenario ID.
reasons	array	An array of the errors which have occurred while processing the scenario.
reasons.key	string	Error code.
description	string	Message with error description.

Response example

OK

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

REJECTED

{
  "result": null,
  "reasons": [
    {
      "key": "contactGroupIds.or.segmentIds.absent"
    }
  ],
  "description": "Validation error: contactGroupIds or segments absent"
}

Receiving scenarios

To receive OMNI scenarios you can use two methods:

1. GET /omni-task-api/tasks/{taskId} to receive one scenario with its ID.
2. GET /omni-task-api/tasks to receive scenarios sorted by filters.

In both methods headers it is required to specify the authorization data.

Request parameters