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 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. Values used only for `EMAIL` channel: ○ `AB_TEST` - for A/B testing. ○ `EVENT_FLOW` - sending by trigger events. For this type of campaigns, Web SDK must be configured. ○ `GEO` - contact's geolocation campaign.

AddressBookSource¶

Parameter	Data type	Description
addressBookSourceType	string	Address book type, used for filters. Possible values: ○ `AB_TEST` - for A/B testing. Used in email mailings. ○ `AB_TEST_WINNER` - for options selected by the contact in A/B testing. ○ `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.
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.
smoothSendMinutes (optional)	integer	Smooth sending, set in minutes. Minimum value: 0 Maximum value: 1140, 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. Values used only for `EMAIL` channel: ○ `EVENT_COLLECTOR` - repeated campaign. ○ `GEO_LOCATION` - geo-campaign.
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 (optional)	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 EMAIL channel.
○ CONTACT_WEB_EVENT - an event in the web interface. Only used with the EMAIL channel.
○ 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 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 (optional)	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:

GET /omni-task-api/tasks/{taskId} to receive one scenario with its ID.
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¶

Get one scenario

Parameter	Data type	Description
taskId	integer	Campaign ID.

Get multiple scenarios

Parameter	Data type	Description
ascending	boolean	The sorting order of the `orderBy` parameter: ○ `true` - ascending. ○ `false` - descending.
channel (optional)	string	Campaign channel. Possible values: `EMAIL`, `OMNI`, `PUSH`, `SMS`, `VIBER`, `VK`, `WHATSAPP`. The `OMNI` channel is used for sending transactional messages.
count	integer	The number of output lines.
createdDateFrom (optional)	datetime	The creation date of the campaign - the beginning of the range. The format is `YYYY-MM-DD hh:mm:ss`.
createdDateTo (optional)	datetime	The creation date of the campaign - the end of the range. The format is `YYYY-MM-DD hh:mm:ss`.
startDateFrom (optional)	datetime	The start date of the campaign - the beginning of the range. The format is `YYYY-MM-DD hh:mm:ss`.
startDateTo (optional)	datetime	The start date of the campaign - the end of the range. The format is `YYYY-MM-DD hh:mm:ss`.
endDateFrom (optional)	datetime	The campaign end date - the beginning of the range. The format is `YYYY-MM-DD hh:mm:ss`.
endDateTo (optional)	datetime	The campaign end date - the end of the range. The format is `YYYY-MM-DD hh:mm:ss`.
includedStates (optional)	array[string]	The campaign statuses included in the search. Possible values: ○ `DRAFT` - draft. ○ `DELETED_DRAFT` - draft deleted. ○ `NEW` - new. ○ `STARTED` - in progress. ○ `STOPPED` - stopped. ○ `FAILED` - an error occurred. ○ `STOPPED_BALANCE_BLOCKED` - stopped due to lack of funds. ○ `STOPPED_NOT_WORKING_TIME` - stopped, sending time exceeded. ○ `FINISHED` - completed. ○ `DELETED_FINISHED` - completed campaign was deleted.
excludedStates (optional)	array[string]	The campaign statuses excluded from the search. Possible values: ○ `DRAFT` - draft. ○ `DELETED_DRAFT` - draft deleted. ○ `NEW` - new. ○ `STARTED` - in progress. ○ `STOPPED` - stopped. ○ `FAILED` - an error occurred. ○ `STOPPED_BALANCE_BLOCKED` - stopped due to lack of funds. ○ `STOPPED_NOT_WORKING_TIME` - stopped, sending time exceeded. ○ `FINISHED` - completed. ○ `DELETED_FINISHED` - completed campaign was deleted.
name (optional)	string	Campaign name.
offset	integer	Line number from which the result will be displayed (offset).
orderBy	string	Field by which the search results will be sorted. Possible values: ○ `ID` - ID of the campaign. ○ `NAME` - campaign name. ○ `STATE` - campaign status. ○ `CREATION_DATE` - campaign creation date.
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. Values used only for `EMAIL` channel: ○ `AB_TEST` - for A/B testing. ○ `EVENT_FLOW` - sending by trigger events. For this type of campaigns, Web SDK must be configured. ○ `GEO` - contact's geolocation campaign.

Request examples¶

Get one scenario

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

Get multiple scenarios

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

Response parameters¶

Parameter	Data type	Description
id	integer	Campaign ID.
taskName	integer	Campaign name.
userId	integer	User ID.
companyId	integer	Company ID.
officeId	integer	Office ID.
creationDate	string	The date and time the campaign was created.
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. Values used only for `EMAIL` channel: ○ `AB_TEST` - for A/B testing. ○ `EVENT_FLOW` - sending by trigger events. For this type of campaigns, Web SDK must be configured. ○ `GEO` - contact's geolocation campaign.
channel	string	Campaign channel. Possible values: `EMAIL`, `OMNI`, `PUSH`, `SMS`, `VIBER`, `VK`, `WHATSAPP`. The `OMNI` channel is used for sending transactional messages.
taskInfo	TaskInfo	Scenario type, which activates the triggered mailing.
locationCount	integer	The number of locations. Used for geo-campaigns.
state	string	The campaign statuses excluded from the search. Possible values: ○ `DRAFT` - draft. ○ `DELETED_DRAFT` - draft deleted. ○ `NEW` - new. ○ `STARTED` - in progress. ○ `STOPPED` - stopped. ○ `FAILED` - an error occurred. ○ `STOPPED_BALANCE_BLOCKED` - stopped due to lack of funds. ○ `STOPPED_NOT_WORKING_TIME` - stopped, sending time exceeded. ○ `FINISHED` - completed. ○ `DELETED_FINISHED` - completed campaign was deleted.
triggersInfo	array[TriggersInfo]	Trigger options.

TriggersInfo¶

Parameter	Data type	Description
triggerId	integer	Trigger ID.
parentTriggerId (optional)	integer	Parent trigger ID.
taskId	integer	Campaign ID.
channel	string	Trigger channel. Possible values: `EMAIL`, `FLASHCALL`, `HLR`, `PUSH`, `PUSH_WALLET`, `SMS`, `VIBER`, `VK`, `VOICE`, `WHATSAPP`.
state	string	Trigger status. Possible values: ○ `NEW` - new. ○ `STARTED` - in progress. ○ `STOPPED` - stopped. ○ `FAILED` - an error has occurred. ○ `FINISHED` - completed.
userId	integer	User ID.
externalId	string	The external user ID assigned by the provider.
companyId	integer	Company ID.
officeId	integer	Office ID.
startTime	datetime	Trigger start date.
endTime	datetime	Trigger end date.
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. Values used only for `EMAIL` channel: ○ `EVENT_COLLECTOR` - repeated campaign. ○ `GEO_LOCATION` - geo-campaign.
counters	TriggerCounters	Counters list.

TriggerCounters¶

Parameter	Data type	Description
totalCount	integer	The number of contacts during the campaign start.
successCount	integer	The number of contacts accepted by the transport.
processedWithoutSendCount	integer	The number of messages processed, including unsent messages.
errorCount	integer	The number of contacts rejected by the transport.
exportTotalCount	integer	The number of contacts during the campaign end.

Response example¶

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

Sending transactional messages¶

To send the transactional message you need to create campaign scenario. It is required to specify the parameters "task.type": "API" and "triggers.type": "TRAN_API_SOURCE".

Then you need to call the method POST /omni-scheduler/api/messages, sending contact, message and scenario information in the request body and authorization data in the header.

Note

Push-messages sending is possible not only with the use of pushToken but with the use of the phone number. To do this, the contact should have the phone number so that the system could find the corresponding tokens.

Request parameters¶

Important

It is required to use contactIds or contacts with taskId parameter.

Parameter	Data type	Description
taskId	integer	Campaign scenario ID that the message will be based on.
contactIds (optional)	array[string]	Address book contacts IDs that the message will be sent to.
contacts (optional)	array[Contacts]	Contact data. The maximum number of contacts is 1000.
templates (optional)	object	The template data of the transactional message. The name of the object is the trigger ID from the `triggers.index` parameter. Templates in this parameter will be prioritized over templates in the original script.

Contacts¶

Parameter Data type Description

contact object Contact data.

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

Contact data¶

Parameter	Data type	Description
email (optional)	string	Contact email address.
phone (optional)	string	The contact's phone number in international format, according to E.164 standard.
pushInfo (optional)	array[PushInfo]	Push notification data.
fields (optional)	array[Fields]	Parameters of macros (fields) of contacts in the list, including main contact fields.

PushInfo¶

Parameter Data type Description

appId string Application ID.

os

integer

Operating system.

Possible values:
○ 0 - iOS.
○ 1 - Android.

pushToken string Device token.

Fields¶

Parameter	Data type	Description
name	string	Field name.
displayName (optional)	string	Field name in personal account.
type (optional)	string	Field type. Possible values: ○ `0` - date/time ○ `1` - `TRUE`/`FALSE` ○ `2` - number ○ `3` - text ○ `5` - object ○ `8` - date
value	array[string]	Field value.

Request examples¶

Create campaign scenario

To create a scenario for transactional messages, you need to use the corresponding method.

{
  "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 store"
        }
      }
    },
    {
      "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 a new shop!",
          "from": "TESTADR",
          "validity": 600
        }
      }
    }
  ]
}

Sending a transactional message

{
  "contacts": [
    {
      "contact": {
        "email": "ivan@yandex.ru",
        "phone": "79103398080"
      }
    }
  ],
  "taskId": 7004
  "templates": {
    "0": {
        "emailTemplate": {
            "htmlBody": "<html><h1>We have a new store!</h1><a id=\"unsubscribe-link\" href=\"${Unsubscribe}\" style=\"color: rgb(0 , 122, 255); text-decoration: none;\">Unsubscribe</a> | <a id=\"web-version-link\" href=\"${WebVersion}\" style=\"color: rgb(0, 122, 255); text-decoration: none;\">Web Version</a></html>",
            "sourceAddress": "test@shop.org",
            "sourceName": "TEST",
            "subject": "New store"
        }
    },
    "one": {
        "smsTemplate": {
            "text": "We have a new store!",
            "from": "TESTADR",
            "validity": 600
        }
    }
  }
}

Response parameters¶

Parameter	Data type	Description
contactIds	array[string]	An array of uploaded contact IDs.
sendAnswers	array[SendAnswers]	An array of successfully sent messages.
errorAnswers	array[ErrorAnswers]	An array of unsuccessfully sent messages.

Send Answers¶

Parameter	Data type	Description
code	string	Shows the result of message processing. 1. `OK` - processed successfully. 2. `REJECTED` - an error has occurred while processing the request.
mergekey	string	Uploaded contact ID.
result	string	Sent message ID.
reasons	array	An array of the errors that occurred while processing the message. To be given with `"code": "REJECTED"` only.
reasons.key	string	Error code.
reasons.ref	string	Reference to the parameter where the error has occurred.

ErrorAnswers¶

Parameter	Data type	Description
code	string	Shows the result of message processing. 1. `OK` - processed successfully. 2. `REJECTED` - an error has occurred while processing the request.
result	string	Sent message ID.
description	string	Description of the error.
reasons	array	An array of the errors that occurred while processing the message. To be given with `"code": "REJECTED"` only.
reasons.key	string	Error code.
reasons.ref	string	Reference to the parameter where the error has occurred.

Response examples¶

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": []
  }
}

Transactional messages callbacks¶

How to enable

To set up callbacks with transactional message statuses, please contact your account manager or technical support.

Possible statuses¶

Status	Channel	Description
delivered	SMS, Viber, Email, Push, WhatsApp, VK	The message was delivered to the user.
seen	viber, whatsapp	The message was read.
undeliverable	SMS, Viber	The message could not be delivered.
unknown	SMS, Viber	Unknown error.
rejected	SMS, Viber, Email, Push, WhatsApp, VK	The message was rejected by the operator or Devino.Online.
expired	SMS, Viber, Push, WhatsApp, VK	The message was expired.
deleted	SMS, Viber	The message was deleted.
send_error	SMS, Viber, Email, Push, WhatsApp, VK	Sending message error.
bounced	Email	Failed to deliver the message.
canceled	push	The user has swiped the notification away.

Campaigns statistics¶

To get messaging statistics in terms of the campaigns it is required to call GET /statistics/sales/by-task, sending statistics parameters and authorization data in the header.

Info

Statistics are based on a data transferred from the DevinoOrderEvent.

Request parameters¶

Parameter	Data type	Description
taskIds	array[integer]	Campaign IDs.
dateTimeFrom (optional)	datetime	Search start date. The format is `YYYY-MM-DD%hh:mm:ss`.
dateTimeTo (optional)	datetime	Search end date. The format is `YYYY-MM-DD%hh:mm:ss`.
zoneOffset (optional)	integer	Time offset for the contact from `UTC+0` in minutes.
cartId (optional)	string	Cart ID.
contactId (optional)	string	Contact ID.
contactGroup (optional)	string	Contact list.
contactPhone (optional)	string	Contact's phone number.
contactEmail (optional)	string	Contact's email.
userId (optional)	string	User ID.
utmSource (optional)	string	`utmSource` data.
webSdkSettingsId (optional)	string	Web SDK settings ID.

Request example¶

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

Response parameters¶

Parameter	Data type	Description
taskId	integer	Campaign ID.
totalCount	integer	The number of orders.
totalSum	number	Revenue.
averageCheck	number	Average check for the orders.

Response example¶

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

Contact¶

The Contact object contains the user's personal data. Contact attributes are used as variables (macros) in transactional messages texts.

Contact attributes can be accessed through the Freemarker markup language.

Basic contact attributes¶

Parameter	Description
name	First name.
surname	Last name.
phone	Phone number.
email	Email address.
gender	Gender with possible values `gender.male` and `gender.female`.
country	Country.
city	City.
birthdate	Date of birth.
CreationDate	Date the contact was created.
LastUpdate	The last time the contact was changed.
timezone	Contact timezone.
pushInfo	Data, for push notifications.

Tip

You can use not only basic, but also custom attributes. They can be set up in personal account or when creating the contact list.

If the message is sent by the event from your website, then the attribute EventInfolist becomes available for Contact object. This attribute is a list of objects transmitted from the website.

Dynamic content¶

In the texts of transactional messages, you can use FreeMarker - a template mechanism. With Freemarker you can manage dynamic content.

Three types of formatting are available:

${...}: will be replaced with the value or the expressions specified inside the curly brackets.
<#tag> - tags: similar to HTML but start with #.
<#-- ... --> - comments: will not end up in the final email, unlike HTML comments.

Values and expressions output¶

Formatting ${...} is used for values output. In this example we used attributes name and email of the Contact object.

<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>

For the John Doe user with the john@customer.net email, the HTML email will take the following form:

<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>

To perform calculations, you can use expressions right inside the ${}:

<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>

In this example, loyalty_discount_rate is a custom attribute of a contact that specifies the discount percentage increase coefficient for each contact. To calculate the final discount, we multiply it by the base discount of 20%.

Supported expressions¶

Below we have listed the most popular expressions. For more information, see the Freemarker documentation.

Variables. Variable value output is the main use of dynamic content in messages and emails. In addition to the contact, you can create your own variables.
Lists.
- EventInfoList[0] - access to any item from the list.
- ?first, ?last - first and last items of the list.
- ?join(sep) - joining of all list items:
```
my list: ${list?join(",")}}

// Output
my list: 0,1,2,3
```
- ?min, ?max - the smallest and the largest object in the list.
- ?size - the number of items in the list.
Strings.
- ?upper_case, ?lower_case, ?capitalize - all items of the string will be uppercase or lowercase, or will start with a capital letter.
- ?length - length of the string.
- ?truncate - string truncation to the specified length:
  - ${"Women Shoes"?truncate(10)} -> "Women[...]", because this function adds [...] after the string truncation.
  - ${product.name?truncate(5, '---')} -> "Wo---", because this function allows you to set characters that will be added at the end of the line.
Integers.
- ?round - rounding to the nearest integer. If it ends with 0.5, it is rounded up.
- ?floor - rounding down.
- ?ceiling - rounding up.
- ?string - converting an integer to a string and number formatting.

Setting variables¶

Creating a variable and assigning a value to it:

<#assign positionSum = 4200000> - creates a numeric variable.
<#assign subscriberTitle = "Attention"> - creates a string variable.

Mathematical operations¶

Can be used to:

calculate the discount in rubles or as a percentage.
calculate how many points a subscriber needs to accumulate for moving to the next step of the loyalty program.
recalculate prices taking into account the personal discounts.

Examples:

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

Number formatting¶

Output conversion and rounding. It is useful, if you want to display the discount with one decimal place in order not to get the value 12.23472100012%.

For example, let's take price = 12.234721
- ${price?string["0"]} - will show 12
- ${price?string["0.#"]} - will show 12.2
- ${price?string["0.##"]} - will show 12.23
- ${price?string["0.###"]} - will show 12.235
- ${price?string["0.####"]} - will show 12.2347

Logical conditions¶

The following logical constructions are allowed:

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

Examples¶

Blank subscriber name¶

For example, if you need to display the subscriber's name, you can display it like this: "Hello, ${contact.name}!"

If the subscriber doesn't have a name, he will see the text with extra commas and space: "Hello, !"

Suitable options:

"Hello<#if (contact.name?length>1)>, ${contact.name?capitalize}!"
"Hello<#if contact.name??>, ${contact.name?capitalize}!"
"Hello<#if contact.name?has_content>, ${contact.name?capitalize}!"

Displaying/hiding a block for subscribers by condition¶

The letter of the pet supply store must contain 3 banners. The dog owner doesn't need to be shown the same banner as the cat or the parrot owner.

Without the condition:

<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>

With the condition:

<#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>

Cycles¶

Examples¶

Displaying a products array for triggers¶

The layout designer draws up the code of one product card, which can be multiplied using a cycle by the number of products selected for display in the letter.

<#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}”>Price ${event.productPrice} euro</a></p>
    </div>
</#list>

Filter in a cycle¶

The client decides not to show the products cheaper than 20 euro to the subscribers.

<#list contact.EventInfoList as event>
    <#if ${event.productPrice}<20><#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}”>Price ${event.productPrice}} euro</a></p>
</#list>

Checking for the presence of values in a cycle¶

If the cycle is empty, you need to display a message that there are no products.

<#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}”>Price ${event.productPrice}} euro</a></p>
    <#else>
    No products
</#list>

Adding a separator between cycle elements¶

To add a separator between the cycle elements, you can use the <#sep> directive that will add code after the each cycle element, except the last.

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

Message sending cancel¶

In some situations, especially when processing event from your website, you may need to cancel sending.

To do this, use the cancelMessage(reason) function in combination with the <#if> condition check:

<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>

Receiving macros¶

To get mailing macros (fields), call the GET /omni-task-api/macros method, passing ID parameters and mailing statuses in the header, indicating authorization data.

Request parameters¶

Parameter Data type Description

taskIds
(optional) array[integer] Campaign IDs from which you need to get the macros.

taskStates
(optional)

array[string]

The campaign statuses.

Possible values:
○ DRAFT - draft.
○ DELETED_DRAFT - draft deleted.
○ NEW - new.
○ STARTED - in progress.
○ STOPPED - stopped.
○ FAILED - an error occurred.
○ STOPPED_BALANCE_BLOCKED - stopped due to lack of funds.
○ STOPPED_NOT_WORKING_TIME - stopped, sending time exceeded.
○ FINISHED - completed.
○ DELETED_FINISHED - completed campaign was deleted.

Request example¶

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

Response parameters¶

Parameter	Data type	Description
task	Task	Campaign scenario options.
macros	array[string]	List of all used macros, including contact macros.
contact	array[string]	List of contact macros.

Response example¶

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