PUSH¶

Sending¶

To send push-notifications it is required to:

Receive sender's ID and enable Push API access. To do this, you need to contact the technical support.
Call POST /push/messages, sending notification parameters in the request body with the authorization data in the header.

Note

You can also use Web SDK to send push notifications automatically.

Request parameters¶

Parameter	Data type	Description
from	integer	Approved sender's ID.
to	string	Recipient's device token.
title	string	Notification title. The maximum length is 200 characters.
text	string	Notification text. The maximum length is 1024 characters.
priority	string	Notification priority level. `LOW` and `MEDIUM` - low and medium priority levels that are used for promotional notifications. `HIGH` - high priority that is used for service traffic. `REALTIME` - maximum possible priority that is used for transactional traffic. If any other value is used, the notification will be rejected.
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: ○ `IOS` - iOS devices. ○ `ANDROID` - Android devices. ○ `HUAWEI` - Huawei 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 notification status. Any `"key"` array: `{ "key1": "value1", "key2": "value2" }`
apns (optional)	Apns	Fields, which are specific for Apple device.
android (optional)	Android	Fields, which are specific for Android and Huawei device.

Attention

To send a notification one of the objects is required: Apns or Android.

Apns¶

Notification parameters for iOS devices.

Parameter	Data type	Description
sound (optional)	string	Push notification sound on iOS. Supports `default` value or file name. The sound file must be included in the main application package or in the `Library`/`Sounds` folder in the application container. Supported formats: AIF, AIFF, WAV, MP3, MP4 Maximum size: 5 MB
buttons (optional)	array[ActionButtons]	Includes a maximum of 3 button objects.
linkToMedia (optional)	string	URL to the file attached to the notification. Supported formats: Audio: AIFF, WAV, MP3, MPEG-4. 5 MB Video: MPEG, MPEG-2, AVI. 50 MB Image: JPEG. PNG, GIF. Resolution: 1024x1024 or 1:1 aspect ratio, 10 MB
image (optional)	string	The filename of the image in the application bundle, with or without a filename extension. The image is displayed directly in the notification. If the parameter is not specified, the system uses the image with the key `UILaunchImageFile` in the `Info.plist` file in the application, or `Default.png`. Supported formats: JPEG, GIF, PNG Sizes: ○ Minimum 512x256 ○ Optimal 1440x720 ○ Maximum 2880x1440 Resolution: 1440x720 or 2:1 aspect ratio
action (optional)	string	The URL/deep link to open when the notification is clicked.

Android¶

Notification parameters for Android and Huawei devices.

Parameter	Data type	Description
smallIcon (optional)	string	Link to the notification icon. The icon will be displayed as a preview in the notification bar. The link must point to an icon in the main application package.
iconColor (optional)	string	Notification icon color in `#RRGGBB` format.
sound (optional)	string	Android push notification sound. Supports a `default` value or filename of a sound resource included with the application. Sound files must be in `/res/raw/`. Supported formats: AIF/AIFF, WAV, MP3, MP4 Maximum size: 5 MB
buttons (optional)	array[ActionButtons]	Includes a maximum of 3 button objects.
image (optional)	string	The filename of the image in the application bundle, with or without a filename extension. The image is displayed directly in the notification. If the parameter is not specified, the system uses the image identified by the `UILaunchImageFile` key in the application's `Info.plist` file, or `Default.png`. Supported formats: JPEG, GIF, PNG Sizes: ○ Minimum 512x256 ○ Optimal 1440x720 ○ Maximum 2880x1440 Resolution: 1440x720 or 2:1 aspect ratio
androidChannelId (optional)	string	Notification channel ID.
tag (optional)	string	ID for selecting users. Used for tagging subscribers in customer databases in FireBase.
collapseKey (optional)	string	When receiving notifications with the same `collapseKey`, Firebase Cloud Messaging (FCM) replaces the older notification with the new one.
action (optional)	string	The URL/deep link to open when the notification is clicked.

ActionButtons¶

Parameter

Data type

Description

icon
(optional)

string

Notification icon URL. Used only for Android.

Supported icon formats: 24x24, 36x36, 48x48, 72x72, 96x96

caption
(optional)

string

Button name. The maximum length is 30 characters.

action
(optional)

string

URL/deep link to go when clicking on the button in the notification.

Request example¶

[
  {
    "from":400,
    "to":"r0Fo0EjfqKjTeZZpPW4s63PpMEYpgKIj55DT",
    "title":"title",
    "text":"Hello",
    "badge":1,
    "validity":86400,
    "priority":"MEDIUM",
    "options":{
       "name":"James",
       "phone":"79169492211"
    },
    "apns":{
       "linkToMedia":"Default.png",
       "sound":"hi.mp3",
       "action":"https://test.com/apple-app-site-association"
    },
    "android":{
       "iconColor": "#2F2F2F",
       "sound":"hi.mp3",
       "action":"https://test.com/android-app-site-association"
    }
  }
]

Response parameters¶

Parameter	Data type	Description
index	integer	Sequence number of the recipient from the notification array.
pushToken	string	The recipient's device token.
pushId	integer	Notification ID. To be given with `"code": "ok"` only.
code	string	Shows the result of notification processing. 1. `ok` - processed successfully. 2. `validation_error` - notification validation error.
description	array	An array of the errors that occurred while processing the notification. To be given with `"code": "validation_error"` only.
description.errorMessage	string	Message with error description.

Response examples¶

OK

{
  "result": [
    {
      "index": 0,
      "pushToken": "IOvpeJ0ECENA3WrrRHG1ghopWkVgiFNLSWWZoqLAUgIllcDF3j19ay9-0-Nanfo-0VjrnA1G6CGSvE_TyRUaea7mXmDUapY3YA",
      "pushId": 3703545281276230700,
      "code": "ok"
    }
  ]
}

VALIDATION ERROR

{
  "result": [
    {
      "index": 0,
      "pushToken": "IOvpeJ0ECENA3WrrRHG1ghopWkVgiFNLSWWZoqLAUgIllcDF3j19ay9-0-Nanfo-0VjrnA1G6CGSvE_TyRUaea7mXmDUapY3YA",
      "code": "validation_error",
      "description": [
        {
          "errorMessage": "Unknown from"
        }
      ]
    }
  ]
}

Callbacks¶

How to enable

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

Possible statuses¶

Status	Description
accepted	The notification has been accepted for delivery.
send	Sent to device notification service.
delivered	The notification has been delivered.
opened	The notification or link from it was opened.
rejected	The notification has been rejected.
canceled	The user has swiped the notification away.
expired	The notification was not delivered during the allotted time.
unsubscribed	The user has disabled notifications.

Callback example¶

[
    {
        "messageId": 1,
        "ts": 1636976602504,
        "status": "delivered",
        "errorCode": 0,
        "options": "string"
    }
]

Details¶

To get the sent notifications detailed information, you need to call GET /push-statistics/statistics/detail, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
limit	integer	The number of notifications in the search results.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of notifications will be displayed only from the 5 in the pull.
taskId (optional)	integer	Notification campaign ID for which you want to get the details. Used in required combination with the other parameters.
triggerId (optional)	integer	Notification campaign trigger ID. Used in required combination with the other parameters.
dateTimeFrom (optional)	datetime	Start date of the notification search. Used in required combination with the other parameters. The format is `YYYY-MM-DDThh:mm:ss`.
dateTimeTo (optional)	datetime	End date of the notification search. Used in required combination with the other parameters. The format is `YYYY-MM-DDThh:mm:ss`.
messageIds (optional)	array[integer]	Notification IDs for which you want to get the details. Used in required combination with the other parameters.
applicationId (optional)	integer	Devino.Online app ID the push notifications are sent from.
order (optional)	string	How to display the request results. Possible values: ○ `ASC` - in ascending order. ○ `DESC` - in descending order.
selectionField (optional)	string	Field by which to sort the request results.
outFields (optional)	array[string]	Fields to be shown in request results. Fields that are not specified in this parameter will be excluded.
recipient (optional)	string	Recipient's phone number.
status (optional)	string	The notification status in the request results. Possible values: ○ `DELIVERED` - the notification has been delivered to the user. ○ `IN_PROGRESS` - the notification is in the process of being sent. ○ `READ` - The notification has been read. ○ `CANCELED` - the user has swiped the notification away. ○ `REJECTED` - the notification has been rejected by the operator or Devino.Online. ○ `UNDELIVERED` - unable to deliver the notification.
timeOffset (optional)	integer	Recipient's time zone.
userId (optional)	integer	Campaign sender user ID.

Parameters combinations¶

To get the correct request results, you should use one of these parameters combinations in accordance with the list:

Notification campaign ID: taskId
Notification campaign ID and trigger ID: taskId, triggerId
Start and end dates for the notification search: dateTimeFrom, dateTimeTo
Notification campaign ID, trigger ID; start and end dates for the notification search: taskId, triggerId, dateTimeFrom, dateTimeTo
Notification IDs: messageIds

Fields for `selectionField` and `outFields` parameters¶

Used in the selectionField parameter to sort the search results and in the outFields parameter to filter fields.

Field name	Description
APPLICATION_ID	ID of the app from which the push notifications are sent (from Devino.Online).
APPLICATION_NAME	App name.
BODY	Push notification text.
BUTTONS	Push notification button information (ActionButtons object).
COMPANY_ID	Company ID.
COMPANY_NAME	Company name.
CUSTOM_DATA	The `options` parameter value when sending the notification.
DEEP_LINK	URL/deep link to which the user went after clicking the notification.
EVENT_DATE_TIME	Date and time the status of the message was last updated.
MEDIA_FILE	Image link attached to the notification. In the response will be indicated as an `image` parameter.
MESSAGE_ID	Notification ID.
PRICE	Notification price.
RECIPIENT	Recipient's push token.
SEND_ROUTE	Route the notification has been sent.
SENT_DATE_TIME	Date and time the notification has been sent.
STATUS	Notification status from the Devino.Online personal account.
STATUS_DETAILS	Notification status from the database.
TASK_ID	Campaign ID.
TASK_NAME	Campaign name.
TASK_TYPE	Campaign type.
TITLE	Push notification title.
TRIGGER_CONTACT_GROUP	The name of the contact list to which the campaign was sent. In the response will be indicated as a `list` parameter.
TRIGGER_SEGMENT	The name of the contact list segment to which the campaign was sent. In the response will be indicated as a `segment` parameter.
TRIGGER_ID	Campaign trigger ID.
USER_ID	Sender's user ID.
USER_LOGIN	Sender's user login.

Request examples¶

With dates

curl -X GET https://api.devino.online/push-statistics/statistics/detail?dateTimeFrom=2023-02-12T00:00:00&dateTimeTo=2023-02-24T00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

With task ID and trigger ID

curl -X GET https://api.devino.online/push-statistics/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
data	array[object]	An array of objects with detailed information on each notification. The parameters are defined by the fields that were set in the original request. Additional parameters also appear.
size	integer	Number of items per page and notifications in search results. Set by `limit` parameter.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of notifications will be displayed only from the 5 in the pull.
number	integer	The number of the received page. Defined by the `offset` parameter. ○ If the `offset` parameter value is `0` with any `limit` parameter value, then the page number will be `1`. ○ If the `offset` will be greater than `0` but less than the `limit` parameter value, the page number will be `2`. For example, with `"offset": 5` and `"limit": 10` the `number` parameter value will be `2`. ○ If the `offset` will be greater than `limit`, the page number will be determined by integer division of `offset` by `limit` plus 1 (`offset` / `limit` + 1). For example, with `"offset": 1000` and `"limit": 50`, the `number` parameter value will be `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Whether the displayed page exists.
total	integer	The total number of notifications for which the details can be received.
pages	integer	The total number of pages for which the details can be received. Determined by integer division of the `total` parameter by `limit` (`total` / `limit`).
more	boolean	Indicator: whether there are pages after the current one specified in the `number` parameter.

Data¶

Parameter Data type Description

recipientPlatform

string

Platform or operating system of devices to which the notification will be sent.

Available values:
○ APNS - iOS devices.
○ FIREBASE - Android devices.
○ HUAWEI - Huawei devices.

isListDeleted boolean Whether the contact list from which the message was sent has been deleted.

isSegmentDeleted boolean Whether the contact list, the contact from which the message was sent, has been deleted.

Response example¶

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "applicationId": 111,
        "applicationName": "App",
        "taskId": "11111",
        "taskName": "task",
        "taskType": "SIMPLE",
        "triggerId": "11111111",
        "list": "Contact_list",
        "isListDeleted": false,
        "segment": "Segment",
        "isSegmentDeleted": false,
        "recipient": "71110000999:APA91bFdDBjCi_6sePNogM3eJ...",
        "sentDateTime": "2022-12-14 05:55:32",
        "status": "UNDELIVERED",
        "statusDetails": "REJECTED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "price": "1.0000",
        "body": "Notification text",
        "title": "Notification title",
        "recipientPlatform": "FIREBASE",
        "image": "https://devinotele.com/media.jpg",
        "deepLink": "http://devinotele.com",
        "actionButtons": [
          {
            "buttonName": "PUSH ME 1",
            "buttonUrl": "1"
          },
          {
            "buttonName": "PUSH ME 2",
            "buttonUrl": "2"
          },
          {
            "buttonName": "PUSH ME 3",
            "buttonUrl": "3"
          }
        ],
        "customData": {
          "OMNI": {
            "contactId": "21dfswarfsg3423ede2",
            "triggerId": 11111111,
            "taskId": 11111
          }
        }
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Notification statistics¶

To get the general statistics on notification statuses, you need to call GET /push-statistics/statistics/of-group, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
groupBy	string	Results grouping: ○ `NONE` - no grouping ○ `YEAR` - by year ○ `MONTH` - by month ○ `WEEK` - by week ○ `DAY` - by day ○ `HOUR` - by hour
startDate	datetime	Start of the date range. The format is `YYYY-MM-DDThh%3Amm%3Ass`.
endDate	datetime	End of the date range. The format is `YYYY-MM-DDThh%3Amm%3Ass`.
taskId (optional)	integer	Campaign ID for which the statistics is needed.
triggerId (optional)	integer	Campaign trigger ID for which the statistics is needed.
timeOffset (optional)	integer	Recipient's time zone. The format is offset in minutes, for example, `180` for Moscow (GMT+3).

Request example¶

curl -X GET https://api.devino.online/push-statitics/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
messages	array[MessageStatusObject]	The number of notifications for the selected period, grouped by status.

MessageStatusObject¶

The object contains information about the number of notifications with statuses:

Code	Description
accepted	The notification has been accepted for delivery.
send	Sent to device notification service.
delivered	The notification has been delivered.
opened	The notification link was opened.
rejected	The notification has been rejected.
canceled	The user has swiped the notification away.
expired	The notification was not delivered during the allotted time.
unsubscribed	The user has disabled notifications.

Each status includes the parameters:

Parameter	Data type	Description
date	string	Statistics collection date depending on the value of the `groupBy` parameter.
amount	integer	The number of notifications.

Response example¶

{
  "result": {
    "messages": {
      "accepted": [],
      "send": [
        {
          "date": "2022-09-01 00:00:00",
          "amount": 11
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 24
        },
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        }
      ],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        }
      ],
      "opened": [
        {
          "date": "2022-10-01 00:00:00",
          "amount": 49
        },
        {
          "date": "2022-09-01 00:00:00",
          "amount": 23
        },
        {
          "date": "2022-11-01 00:00:00",
          "amount": 1
        }
      ],
      "rejected": [],
      "canceled": [],
      "expired": [],
      "unsubscribed": []
    }
  }
}

PUSH¶

Sending¶

Request parameters¶

Apns¶

Android¶

ActionButtons¶

Request example¶

Response parameters¶

Response examples¶

Callbacks¶

Possible statuses¶

Callback example¶

Details¶

Request parameters¶

Parameters combinations¶

Fields for selectionField and outFields parameters¶

Request examples¶

Response parameters¶

Data¶

Response example¶

Notification statistics¶

Request parameters¶

Request example¶

Response parameters¶

MessageStatusObject¶

Response example¶

Fields for `selectionField` and `outFields` parameters¶