Skip to content

OMNI

Script creation

To send OMNI-notifications it is required to call POST /omni-task-api/tasks, sending message parameters in the body with authorization data in the heading.

Request parameters

Parameter Data type Description
taskName string Task name
type string Task type. Possible values: SIMPLE, API
channel string Channel. Possible values: SMS, EMAIL, VIBER, PUSH
addressBookSource string Address book parameters
addressBookSourceType string Address book type. Possible values: SIMPLE
byTimeZone boolean To consider local time of contact or not when sending
checkDuplicate boolean Send message to duplicate contacts or not
contactGroupIds array[integer] Contact group IDs array
period string Period type. Filled if type=PERIODIC. Possible values: ONCE, DAILY, WEEKLY, MONTHLY
segmentIds array[integer] Segment IDs array
smoothSendMinutes integer Smooth sending, set in minutes
stopContactGroupIds array[integer] Stop contact group IDs array
triggers string Trigger parameters
index integer Trigger ID
parentIndex integer Parent trigger ID
startTime string Trigger start date
endTime string Trigger end date
type string Trigger type. Possible values: ADDRESS_BOOK_SOURCE, EVENT_SOURCE, NO_EVENT_SOURCE, TRAN_API_SOURCE
channel string Trigger channel. Possible values: SMS, EMAIL, VIBER, PUSH
eventSources array[object] Array of events for a trigger

{
"channel": "SMS" //parent trigger channel,
"eventType": "STATE" //event type, it is possible to transfer only STATE
"eventValue": "string" //message status
}
template object Template for sending (detailed description in "Template Filling")

Note

eventSources.eventValue can take the following values:
SMS: delivered or expired
VIBER: delivered, expired, opened or clicked
EMAIL: delivered, opened, clicked, unsubscribed or subscribed

Template Filling

Parameter Data type Description
smsTemplate Sms-message template
from string Sender's name
text string Message text
validity integer Message life time
viberTemplate Viber-message template
action string Button link
caption string Button name
from string Sender's name
image string Image
text string Message text
validity integer Message life time
emailTemplate Email-message template
attachmentIds array[integer] Array of added files
htmlBody string Email html-text
plainText string Email text
sourceAddress string Sender's address
sourceName string Sender's name
subject string Email subject
pushTemplate Push-message template
android object Android specific settings
apns object iOs specific settings
badge integer Badge number
from integer Sender's name
options object Additional data like:
{
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
silentPush boolean Silent Push
text string Message text
title string Message title
validity integer Message life time

Request example

// POST /omni-task-api/tasks
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
// Content-Type: application/json
// Accept: application/json
{
  "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 have new shop!",
          "from": "TEST",
          "validity": 600
        }
      }
    }
  ]
}

Response example

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

Receiving a specific scenario

To receive a specific OMNI-notification it is required to call GET /omni-task-api/tasks/{taskId}, sending message parameters in the body with authorization data in the heading.

Request parameters

Parameter Data type Description
taskId integer Task ID

Request example

curl -X GET "/omni-task-api/tasks/7003" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

Response parameters

Parameter Data type Description
id integer Task ID
taskName integer Task name
userId integer User ID
companyId integer Company ID
officeId integer Representative office ID
creationDate string Task creation date
type string Task type. Possible values: SIMPLE, API
channel string Task channel. Possible values: SMS, EMAIL, VIBER, PUSH
state string Task status. Possible values: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED
triggersInfo array[object] Triggers parameters
triggerId integer Trigger ID
taskName integer Task name
userId integer User ID
companyId integer Company ID
officeId integer Representative office ID
startTime string Trigger start date
endTime string Trigger end date
type string Trigger type. Possible values: ADDRESS_BOOK_SOURCE, EVENT_SOURCE, NO_EVENT_SOURCE
channel string Trigger channel. Possible values: SMS, EMAIL, VIBER, PUSH
counters object Counters list
{
"totalCount": 1 //total messages,
"successCount": 0, //success messages
"errorCount": 0 //error messages
}
externalId string External ID

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

Receiving scenarios

To receive OMNI-notifications it is required to call GET /omni-task-api/tasks, sending message parameters in the body with authorization data in the heading.

Request parameters

Parameter Data type Description
ascending boolean Sorting order for the "orderBy" field:
true - ascending
false - descending
channel
(optional)		 string Task channel. Possible values: SMS, EMAIL, VIBER, PUSH
count integer Number of output lines
createdDateFrom
(optional)		 string Task create date search starting from this date, date view: yyyy-mm-dd hh:mm:ss
createdDateTo
(optional)		 string Task create date search ending with this date, date view: yyyy-mm-dd hh:mm:ss
endDateFrom
(optional)		 string Task end date search starting from this date, date view: yyyy-mm-dd hh:mm:ss
endDateTo
(optional)		 string Task end date search ending with this date, date view: yyyy-mm-dd hh:mm:ss
excludedStates
(optional)		 array[string] Array of excluded statuses. Possible values: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED, STOPPED_BALANCE_BLOCKED
includedStates
(optional)		 array[string] Array of included statuses. Possible values: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED, STOPPED_BALANCE_BLOCKED
name
(optional)		 string Task name
offset integer Line number to start displaying the result (offset)
orderBy string The field to sort by. Possible values: ID, NAME, STATE, CREATION_DATE
startDateFrom
(optional)		 string Task start date search starting from this date, date view: yyyy-mm-dd hh:mm:ss
startDateTo
(optional)		 string Task start date search ending with this date, date view: yyyy-mm-dd hh:mm:ss
types
(optional)		 array[string] Array of task types. Possible values: SIMPLE, API

Request example

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

Response parameters

Parameter Data type Description
channel string Task channel. Possible values: SMS, EMAIL, VIBER, PUSH
companyId integer Company ID
creationDate string Task creation date
id integer Task ID
officeId integer Representative office ID
state string Task status. Possible values: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED
taskName integer Task name
triggersInfo array[object] Triggers parameters
channel string Trigger channel. Possible values: SMS, EMAIL, VIBER, PUSH
companyId integer Company ID
counters object Counters list
{
"totalCount": 1 //total messages,
"successCount": 0, //success messages
"errorCount": 0 //error messages
}
endTime string Trigger end date
externalId string External ID
officeId integer Representative office ID
parentTriggerId integer Parent trigger ID
startTime string Trigger start date
state string Trigger status. Possible values: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED
taskId integer Task ID
triggerId integer Trigger ID
type string Trigger type. Possible values: ADDRESS_BOOK_SOURCE, EVENT_SOURCE, NO_EVENT_SOURCE
userId integer User ID
type string Task type. Possible values: SIMPLE, API
userId integer User ID

Response example

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

Sending transactional messages

Pre-create a message scenario with the method POST /omni-task-api/tasks, be sure to pass task.type=API and triggers.type=TRAN_API_SOURCE to it;

To send transactional messages you must call the method POST/omni-scheduler/api/messages with message contact information and scenario id in the body and with authorization data in the header.

To call the POST /omni-scheduler/api/messages method, you need to fill its parameters.

Request parameters

Parameter Data type Description
contactIds array[integer] Array of contacts ID from the address book
contacts array[object] Contacts data
contact object Contact data (view Contact data)
callbackUrl string URL the system will send notifications on the message status changes to (callback). Any valid HTTP or HTTPS URL
callbackData object Additional information like "key":"value"
taskId integer Transactional message ID
templates object Transactional message template data
trigger ID object Trigger ID from taskId
Detailed description in "Template Filling")
If you fill in the parameters described here, they will be higher priority than the similar parameters of the POST/omni-task-api/tasks method, which previously created the template!

Contact data

Parameter Data type Description
email string Contact email
fields array[object] Contact fields
Filled as follows:
"displayName": "string" // visible field name,
"name": "string", // field name
"type": 0, // field type
"value": {} // field value
phone string Contact phone
pushInfo array[object] Push data
Filled as follows:
"appId": "string", // application id
"os": 0, // operating system
"pushToken": "string" // token

Request example POST /omni-task-api/tasks (for transactional message)

// POST /omni-task-api/tasks
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
// Content-Type: application/json
// Accept: application/json

{
  "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": "<h1>We have new shop!</h1>",
          "plainText": "We have new shop!",
          "sourceAddress": "testadr@newshop.com",
          "sourceName": "TESTADR",
          "subject": "New shop"
        }
      }      
    },
    {
      "index": 1,
      "parentIndex": 0,
      "startTime": "2020-06-02 12:00:00",
      "endTime": "2020-06-02 13:00:00",
      "type": "NO_EVENT_SOURCE",
      "channel": "SMS",    
      "eventSources": [
        {
          "channel": "EMAIL",
          "eventType": "STATE",
          "eventValue": "delivered"
        }
      ],
      "template": {     
        "smsTemplate": {
          "text": "We have new shop!",
          "from": "TESTADR",
          "validity": 600
        }
      }
    }
  ]
}

Response example POST /omni-task-api/tasks

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

Request example POST /omni-scheduler/api/messages

// POST /omni-scheduler/api/messages
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
// Content-Type: application/json
// Accept: application/json
{
  "contacts": [
    {
      "contact": {
        "email": "ivan@yandex.ru",
        "phone": "79103398080"
      }
    }
  ],
  "taskId": 7004,
  "templates": {
    "63321": {    //email triggerId from task=7004
        "emailTemplate": {
            "htmlBody": "<html><h1>We have new shop!</h1><a id=\"unsubscribe-link\" href=\"${Unsubscribe}\" style=\"color: rgb(0, 122, 255); text-decoration: none;\">Отписаться от рассылки</a> | <a id=\"web-version-link\" href=\"${WebVersion}\" style=\"color: rgb(0, 122, 255); text-decoration: none;\">Web Версия</a></html>",
            "sourceAddress": "test@shop.org",
            "sourceName": "TEST",
            "subject": "New shop"
        }
    },
    "63322": { //sms triggerId from task=7004
        "smsTemplate": {
            "text": "We have new new shop!",
            "from": "TESTADR",
            "validity": 600
        }
    }
  }
}

Response example POST /omni-scheduler/api/messages

{
  "result": {
    "contactIds": [
      "3111e47182ca9c11-3111e4711103c800"
    ],
    "sendAnswers": [
      {
        "code": "OK",
        "mergeKey": "3111e47182ca9c11-3111e4711103c800",
        "result": "3606044956953218300"
      }
    ],
    "errorAnswers": [
      {
        "code": "REJECTED",
        "result": null,
        "description": "{\"email\":\"test@test.com\",\"fields\":null,\"phone\":\"0\",\"pushInfo\":[{\"appId\":\"3410\",\"os\":1,\"pushToken\":\"ctJ5VzCERSiFTwvIQ8zUUN:APA91bEmdapZ9iHEPsVH9vBwfA0tW9o5Xe1N52URL6-ZraiGLMdeAhkLncsGiV8ooTiDoNjP5HUcAVfGa5nMjYFLSHexqAGovnlRqrjBrQJieB6a1fvlXm6znCCRjq64lLGy5PcF6nzG\"}]} #invalid.phone.size; Invalid phone size"
      }
    ]
  }
}

Request parameters

Parameter Data type Description
contactIds array[string] Array of downloaded contacts
sendAnswers array[object] Array of successful messages (code=OK)
code string Points out the result of message processing.
1. OK - Processed successfully
2. REJECTED - An error has occurred while processing the request.
mergeKey string Downloaded contact ID
result string Message ID
errorAnswers array[object] Array of unsuccessful messages (code=REJECTED)
code string Points out the result of message processing.
1. OK - Processed successfully
2. REJECTED - An error has occurred while processing the request.
result string Message ID.
Message ID is null in this block
description string Error description

Getting status of transactional message

While creating the message status a POST request will be sent to the URL provided when sending the message in the callbackUrl parameter. 200 Ok is expected as the answer to the request.

In case the answer to the request is 500 Internal Error, there will be made 5 attempts to deliver the status with 1 minute interval.

Request example

[
  { 
   "messageId": "string",
   "ts": 0,
   "status": "string",
   "errorCode": 0,
   "ip": "string",
   "browser": "string",
   "os": "string",
   "callbackData": {"additionalProp": "string"},   
   "userAgent": "string",
   "contactId": "string", 
   "taskId": 0,
   "triggerId": 0,
   "email": "string",
   "url": "string",
   "geolocation": {"country":"string", "region":"string", "city":"string"},
   "pushToken": "string",
   "actionId": "string",
   "pushApplicationId": 0
  }
]

Request parameters

Parameter Data type Status Description
messageId
(optional)		 long any A unique message ID on the platform
ts
(optional)		 int any Points out the time for creating the ‘status’ object
status enum any Delivery status code for the Viber message
For more information see Possible statuses
errorCode
(optional)		 int rejected
undeliverable		 A code for the reason for non-delivery of the message
ip
(optional)		 string opened
clicked		 The contact’s IP
browser
(optional)		 string opened
clicked		 The contact’s browser
os
(optional)		 string opened
clicked		 The contact’s operating system
callbackData
(optional)		 object any Options
userAgent
(optional)		 string any Browser info (version, type)
contactId
(optional)		 string any Contact ID
taskId
(optional)		 long any Task ID
triggerId
(optional)		 long any Trigger ID
email
(optional)		 string any Email
url
(optional)		 string clicked Url the recipient clicked on
geolocation
(optional)		 string any Geolocation data (not added yet): country, region, city
pushToken
(optional)		 string any Device token
actionId
(optional)		 string any Clicked action
pushApplicationId
(optional)		 int any Application ID, field from in the send request

Possible statuses

Parameter Description
delivered The message has been delivered to the user
expired The lifetime of the message has expired
undeliverable Unable to deliver the message
bounced Email message cannot be delivered
opened The message has been opened
clicked There was a click on the link in the message
rejected The message has been rejected by the operator or Devino
deleted The message has been deleted from the queue for sending
subscribed Subscription via message
unsubscribed Unsubscription via message
complained Complaint via message
unknown An unknown error has occurred
canceled The push-message has been canceled

Receiving macros

To receive macros it is required to call GET /omni-task-api/macros, sending message parameters in the body with authorization data in the heading.

Request parameters

Parameter Data type Description
taskIds
(optional)		 array[integer] Array of task IDs
taskStates
(optional)		 array[string] Array of mailing statuses. Possible values:: DRAFT, NEW, STARTED, STOPPED, FINISHED, DELETED_FINISHED, DELETED_DRAFT, FAILED, STOPPED_BALANCE_BLOCKED, STOPPED_NOT_WORKING_TIME

Request example

curl -X GET "/omni-task-api/macros?taskStates=FINISHED \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=="

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": "SMS",
        "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": 1,
              "successCount": 1,
              "errorCount": 0
            },
            "externalId": "4A8F5B75-29ED-473B-7AA0-4FC4507A41280"
          }
        ]
      },
      "macros": [
        "Unsubscribe",
        "WebVersion"
      ]
    }
  ]
}