Skip to content

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

{
  "result": [
    {
      "index": 0,
      "pushToken": "IOvpeJ0ECENA3WrrRHG1ghopWkVgiFNLSWWZoqLAUgIllcDF3j19ay9-0-Nanfo-0VjrnA1G6CGSvE_TyRUaea7mXmDUapY3YA",
      "pushId": 3703545281276230700,
      "code": "ok"
    }
  ]
}
{
  "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-DD+hh:mm:ss.
dateTimeTo
(optional)
datetime End date of the notification search. Used in required combination with the other parameters. The format is YYYY-MM-DD+hh: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

curl -X GET https://api.devino.online/push-statistics/statistics/detail?dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
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": []
    }
  }
}