Skip to content

OMNI

Sending a scenario

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
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 text
plainText string Email html-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:
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
        }
      }
    }
  ]
}
curl -X POST "/omni-task-api/tasks" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
-H "Content-Type: application/json" \
-d "{\"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

GET /omni-task-api/tasks/{taskId}
Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
    "taskId": 7003
}
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
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
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

Request example

GET /omni-task-api/tasks
Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
    "ascending": true,
    "count": 10,
    "offset": 0,
    "orderBy": "ID"
}
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
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
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 message

To send a transactional message you must:

  • pre-create a message scenario (template) with the method POST /omni-task-api/tasks, be sure to pass task.type=API and triggers.type=TRAN_API_SOURCE to it,
  • call transactional message send method POST/omni-scheduler/api/messages with message contact information and template data 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 Callback url
options object Additional information like "key":"value"
taskId integer Transactional message ID
templates object Transactional message template data (detailed description in "Template Filling")
If you fill in the parameters described below, 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": "We have new shop!",
          "plainText": "<h1>We have new shop!</h1>",
          "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,
  "template": {
    "emailTemplate": {
      "htmlBody": "We have new shop111!",
      "plainText": "<h1>We have new shop111!</h1>",
      "sourceAddress": "test@shop.org",
      "sourceName": "TEST",
      "subject": "New shop"
    },
    "smsTemplate": {
      "text": "We have new new shop!",
      "from": "TESTADR",
      "validity": 600
    }
  }
}

Response example POST /omni-scheduler/api/messages

{
  "result": {
    "manualContactsAnswers": [
      {
        "code": "OK",
        "result": {
          "contactId": "3111e47182ca9c11-3111e4711103c800"
        }
      }
    ],
    "sendAnswers": [
      {
        "code": "REJECTED",
        "result": null,
        "description": "Invalid source address."
      }
    ]
  }
}

Request parameters

Parameter Data type Description
code string Points out the result of message processing.
1. OK - Processed successfully
2. REJECTED - An error has occurred while processing the request.
description
(optional)
string Error description.
To be given with code=REJECTED only
reasons
(optional)
Array[String, String] An array of the errors which occurred while processing the message.
To be given with code=REJECTED only
reasons.key string Error code.
reasons.ref
(optional)
string A reference to the parameter where the error occurred.
result
(optional)
string Message ID.
To be given with code=OK only

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

GET /omni-task-api/macros
Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
  "taskStates": "FINISHED"
}

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