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") | |
noEventSourceSettings | object | stateWaitMaxTimeSec parameter - integer - the time to wait for the event (in seconds) defined in eventSources with the index specified in parentIndex . When the time expires, the message is re-sent. |
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 ID | |
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 | |
pushWalletTemplate | Push-message template | ||
from | string | Sender ID | |
to | string | Recipient MSISDN MSISDN validation and cut |
|
callbackUrl | string | Callback sender Url. Max is 1000 characters | |
callbackData | string | Callback data | |
scheduledTime | string | Message sending time in LocalDateTime format | |
mergeKey | string | (optional) Key to combine request and response | |
payload | PushPayload | Message content settings | |
vkTemplate | VK-message template | ||
templateId | string | Template ID in Devino Online | |
templateData (optional) |
object | Additional values for the template | |
routes | array[string] | Array of VK routes in order of use. Possible values: [ VK ][ OK ][ OK ,VK ][ VK ,OK ] |
|
deliveryPolicy | string | Delivery policy. Possible values: ANY , MOBILE_DEVICE_REQUIRED .Default ANY .If MOBILE_DEVICE_REQUIRED is specified, then delivery is made only if the user has a mobile application and has used it within the last 7 days. In this case, delivery is made to all available devices, not just mobile ones. |
|
validity (optional) |
integer | Indicated only in case of sending a message using a template. Minimum value - 15 (seconds). Miaximum value (day) - 86400 (seconds). | |
callbackData (optional) |
string | The data to be specified in the callback with the message status | |
callbackUrl (optional) |
string | URL, which the system will send notifications of changes in the message status Any valid URL with an http or https scheme |
Request example¶
// POST https://api.devino.online/omni-task-api/tasks
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2==
// 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 "https://api.devino.online/omni-task-api/tasks/7003" \
-H "Authorization: Key QWxhZGRpbjpvcGVuIHNlc2=="
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 "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 | |
---|---|---|---|
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 |
---|---|---|
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 https://api.devino.online/omni-task-api/tasks
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2==
// Content-Type: application/json
// Accept: application/json
{
"taskName": "PUSH -> EMAIL -> SMS",
"type": "API",
"channel": "OMNI",
"triggers": [
{
"index": 0,
"startTime": "2022-04-05 11:00:00",
"endTime": "2022-04-05 12:00:00",
"type": "TRAN_API_SOURCE",
"channel": "PUSH_WALLET",
"template": {
"pushWalletTemplate": {
"from": "hello",
"payload": {
"deeplink": {
"campaignId": "q123456",
"target": "campaign"
},
"message": "We have new shop",
"title": "New shop"
}
}
}
},
{
"index": 1,
"parentIndex": 0,
"startTime": "2022-04-04 12:00:00",
"endTime": "2022-04-04 13:00:00",
"type": "NO_EVENT_SOURCE",
"noEventSourceSettings": {
"stateWaitMaxTimeSec": 60
},
"EventSource": [
{
"channel": "PUSH_WALLET",
"eventType": "STATE",
"eventValue": "MSISDN_NOT_REGISTERED"
}
],
"channel": "EMAIL",
"template": {
"emailTemplate": {
"htmlBody": "We have new shop!${Unsubscribe}",
"plainText": "<h1>We have new shop!</h1>${Unsubscribe}",
"sourceAddress": "testadr@newshop.com",
"sourceName": "DEVINOTELE",
"subject": "New shop"
}
}
},
{
"index": 2,
"parentIndex": 1,
"startTime": "2022-04-04 13:00:00",
"endTime": "2022-04-04 14:00:00",
"type": "NO_EVENT_SOURCE",
"channel": "SMS",
"eventSources": [
{
"channel": "EMAIL",
"eventType": "STATE",
"eventValue": "delivered"
}
],
"template": {
"smsTemplate": {
"text": "We have new shop!",
"from": "smsSA",
"validity": 600
}
}
}
]
}
Response example POST /omni-task-api/tasks¶
{
"result": {
"code": "OK",
"result": "219459"
}
}
Request example POST /omni-scheduler/api/messages¶
// POST https://api.devino.online/omni-scheduler/api/messages
// Authorization: Key QWxhZGRpbjpvcGVuIHNlc2==
// Content-Type: application/json
// Accept: application/json
{
"contacts": [
{
"contact": {
"email": "James@jamesmail.com",
"phone": "79103398080"
}
}
],
"taskId": 7004,
"templates": {
"63321": {
"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": {
"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-3111e4711103c",
"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 via CallbackURL¶
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 | |
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 "https://api.devino.online/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"
]
}
]
}