Skip to content

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)		 string Trigger start date.
endTime
(optional)		 string Trigger end date.
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 Letter 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

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

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

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

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

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

Parameter Data type Description
taskId integer Campaign ID.
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)		 string The creation date of the campaign - the beginning of the range.
Format: YYYY-MM-DD HH:MM:SS.
createdDateTo
(optional)		 string The creation date of the campaign - the end of the range.
Format: YYYY-MM-DD HH:MM:SS.
startDateFrom
(optional)		 string The start date of the campaign - the beginning of the range.
Format: YYYY-MM-DD HH:MM:SS.
startDateTo
(optional)		 string The start date of the campaign - the end of the range.
Format: YYYY-MM-DD HH:MM:SS.
endDateFrom
(optional)		 string The campaign end date - the beginning of the range.
Format: YYYY-MM-DD HH:MM:SS.
endDateTo
(optional)		 string The campaign end date - the end of the range.
Format: 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

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"

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 string Trigger start date.
endTime string 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 2000.
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

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

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

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

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.

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}<!--#if-->!"
  • "Hello<#if contact.name??>, ${contact.name?capitalize}<!--#if-->!"
  • "Hello<#if contact.name?has_content>, ${contact.name?capitalize}<!--#if-->!"
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"
      ]
    }
  ]
}