Push#

Push Notifications Sending#

Text sending and additional parameters are available in push notifications.

Examples of additional parameters:

  • title;

  • images;

  • buttons;

  • HTML pages;

  • templates for sending sensitive data;

  • parameters for data enrichment;

  • data without preprocessing (in JSON format);

  • client data for statistics;

  • data for updating Live Activity;

  • primary application attribute;

  • mobile app subscriptions;

  • providers indication (APNS, FCM, HMS, RuStore) for sending data.

Request Examples#

Request examples to send push notifications.

To generate a test request with your parameters please Внешняя ссылка open the request generator.

Description of useTimeDiff ; destAddr parameters.

 1  {
 2     "login":"YOUR_LOGIN",
 3     "password":"YOUR_PASSWORD",
 4     "id":"8770630",
 5     "extraParam":"param1=value1,param2=value2",
 6     "registeredDelivery":"1",
 7     "notifyUrl":"URL_for_sending_statuses"
 8     "useTimeDiff":true,
 9     "scheduleInfo":{
10       "timeBegin":"10:00",
11       "timeEnd":"12:00",
12       "weekdaysSchedule":"123",
13       "deadline": "2029-12-31T16:29:30+0300"
14     },
15     "destAddr":"Subscriber's_Number",
16     "message":{
17       "type":"Push",
18       "data":{
19         "externalUserId": "subscriber's_ID",
20         "text":"Notification text",
21         "serviceNumber":"SENDER'S_NAME",
22         "ttl":10,
23         "ttlUnit": "SECONDS",
24       }
25     }
26  }

Request Parameters#

The mandatory parameters are highlighted in bold.

Parameter

Data type

Description

login

string

Partner’s name in the system.

password

string

Partner’s password in the system.

extraParam

string
Additional parameters passed as param1=value1,param2=value2, where

  • param1 and param2 – parameter names;

  • value1 and value2 – values.

The comma character cannot be included in the parameter name, but it can be included in its value – in this case it must be doubled.

Example: the string place=abzakovo,name=guest house-2,coordinates=53.8085896,, 58.6362112,from=23.02.09,to=05.03.09.

useTimeDiff

boolean
Taking into account the time zone when starting messaging.
If true, the message is sent to the subscriber according to the messaging schedule and his time zone.
If false, the message is sent according to the messaging initiator schedule UTC+3 regardless of the message recipient time zone.
Default value: false.

scheduleInfo

object
Messaging schedule. If it is not specified, it is sent immediately upon receipt of the request.

scheduleInfo/timeBegin

string

Start time, for example, «10:00».

scheduleInfo/timeEnd

string

End time, for example, «21:00».

scheduleInfo/weekdaysSchedule

string
Messaging days. Specified by numbers from 1 (Monday) to 7 (Sunday), for example, «12345».
If there are no restrictions on days of the week, this parameter can be empty or not delivered in the request.

scheduleInfo/deadline

string

The end date of the messaging, for example, 2024-09-10T16:29:30+0300.

id

string
Partner-side unique ID. This parameter is required to control re-sending and duplication (the control service is enabled separately).
The Partner may recall the Service Provider (the request to send a message) with the same ID several times. In this case the message will be sent to the subscriber only once (upon the first request).
In response to requests, the Service Provider will return the same message ID in the Service Provider’s system to the Partner (the same as for the first request).
The Service Provider optionally returns this ID to the Partner, if available in the message delivery report.

shortenLinks

boolean
The parameter enables automatic shortening of URL strings in the message.
Possible values are:

  • true — to shorten links (by default);

  • false — shortening link is not required.

If the parameter is not received in the request, but the service is available to the Partner, the links will be shortened by default.
For more details: Link Shortening Service.

Примечание

The ability to use this service is previously agreed with and configured by the Service Provider.

destAddr

string
Mandatory in case of push message if the message/data/externalUserId parameter is missing. Subscriber’s phone number. It contains the country code, operator code and phone number. For the Russian Federation, the code can be „8“, „7“ or „+7“.
Examples: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.

message

object

Parameters of a message being sent.

message/type

enum

Message type. The value of PUSH is is transmitted.

message/data

object

Parameters of the data being sent.

message/data/externalUserId

string

User ID to send push messages (login, email, UID).

message/data/ttl

integer
Message lifetime. Acceptable range in seconds: from 30 to 86400.
When ttl = 0 or the parameter is absent in the request, the value from the default settings is used, which is set during the integration setup separately for each client.
If ttl is not specified in these places the request will be rejected by the system and an error will be displayed.

message/data/ttlUnit

enum
Unit of measurement of the message delivery period. It is transmitted only with ttl.
Possible values are:

  • SECONDS;

  • MINUTES;

  • HOURS.

message/data/serviceNumber

string

Sender’s name from which the message is being sent.

message/data/text

string

Message text. Maximum length: no more than 1000.

Request with a header title

message/data/title

string

The header of the text message. Amount of characters is no more than: 80.

Request with the primary application attribute (primaryOn)

message/data/primaryOn

boolean

An indication of the primary application installed on the subscriber’s device. Possible values are:

  • true – sending only to the user’s primary device;

  • false – sending to all the user’s devices.

If the parameter is missing, it is also sent to all user devices.

registeredDelivery

integer
Requirement of delivery reports.
Possible values are:

  • 0 - statuses are not required;

  • 1 - statuses are required (by default);

  • 2 - only «Undelivered» status is required.

notifyUrl

string
Hostname of the incoming API to obtain the delivery report (see Delivery Status Service).
This parameter is optional in the request, but when sending you need to consider the following:

  • if the parameter is specified, it cannot be empty;

  • the notifyUrl string must be no more than 2048 characters long.

If any of the specified conditions are not met, an error will be generated and the request will not be executed.

Request specifying the category of content – images, HTML links and buttons (contentCategory)

message/data/content

object

Parameters for sending images, HTML links and buttons.

message/data/content/ contentCategory

enum
Content category by the contentUrl link.
Possible values are:

  • IMAGE – to send in the contentUrl link to the image;

  • HTML – to send in contentUrl link to go to. After opening push message the transmitted link will open in the webView.

message/data/content/contentUrl

string
URL of the image or HTML. Maximum link length: 512 characters.
Image requirements to contentCategory=IMAGE:

  • image formats: JPEG, PNG, GIF, BMP;

  • image size: no more than 1 Mb;

  • proportion: 2:1.

Request to display buttons (actions)

message/data/content/actions

array
An array containing buttons with the ability to:

  • open message;

  • follow the specified link.

The description of the button attributes is given below.

message/data/content/actions/ title

string

The inscription on the button. Amount of characters: no more than 64.

message/data/content/actions/ action

string
The text ID of the button in the mobile application. It defines the action to be performed when the button is clicked. The parameter is configured in the mobile application.
Amount of characters: no more than 64.
Possible values are:

  • open-app (open the application);

  • link (follow the specified link).

message/data/content/actions/ options

string
Additional button parameters. The set depends on the OS and is determined by the developer of the mobile application. The parameter is configured in the mobile application.
Number of characters: no more than 300.
In the case of a button with action=link the URL for the transition can be specified.

Request with subscriptions (deviceSubscriptions)

message/data/deviceSubscriptions

array

A transmitted array with a list of mobile app subscriptions.

Request with data for the application (customPayload)

message/data/customPayload

JSON Object

The data which are transmitted as is to the mobile application for further use in the mobile application.

Request with data for statistics (callbackData)

message/data/callbackData

string

Client data for statistics. They are saved in the transmitted form upon receipt, an output in statistical data is possible, if necessary.

Request with enriched data (extraOptions)

message/data/extraOptions

array

An array of additional data objects from the partner. It contains two mandatory parameters: param_name и param_value.

message/data/extraOptions/ param_name

string
The transmission of the message attribute.
Possible values are:

  • RICH – data for an alternative sending data with content for a mobile application;

  • LIVE_ACTIVITY – data for updating the Live Activity widget on iOS devices;

  • SECURE – parameters for transmitting sensitive data in a push notification;

  • SENDING_PLATFORMS – parameters for sending push notifications to certain types of platforms (APNS, FCM, HMS, RuStore).

message/data/extraOptions/ param_value

string

Depending on the attribute passed to param_name the data in param_value will be differ.

param_name=RICH

message/data/extraOptions/ param_value/title

string

The header of the message. If this parameter is received, the sent header is replaced or the header is set instead of an empty one.

message/data/extraOptions/ param_value/message

string

Message text. If it is sent in RICH, then the sent text is replaced.

message/data/extraOptions/ param_value/content-category

string

Content type. If it is sent, it is replaced along with the url. If the URL is empty, the content-category is ignored.

message/data/extraOptions/ param_value/content-url

string

The link for the content. If the content type is not specified, it is substituted as a url instead of the sent one. If the url is not sent and the content type has not been sent, it is ignored.

message/data/extraOptions/ param_value/custom-payload

string

User data. If they are sent, the previously sent data are replaced or new data are set if they were not sent earlier.

message/data/extraOptions/ param_value/actions

array

A list of buttons. If the data is not empty, then the previously sent content is replaced.

param_name=LIVE_ACTIVITY

message/data/extraOptions/ param_value/aps/stale_date

timestamp

timestamp in ISO 860 format — date and time when Live Activity is considered obsolete.

message/data/extraOptions/ param_value/aps/dismissal_date

timestamp

timestamp in ISO 8601 format — date and time when Live Activity closes on the lock screen. After the widget stops being active, it can remain on the lock screen for another 4 hours if it is not closed. To close it immediately and not wait, you can specify a date that has already passed.

message/data/extraOptions/ param_value/aps/timestamp

timestamp

timestamp in ISO 8601 format.

message/data/extraOptions/ param_value/aps/event

string

The event for updating the Live Activity can take the following values:

  • update;

  • end.

message/data/extraOptions/ param_value/aps/content_state

object
The data that will be displayed in the Live Activity widget.
The widget developer sends these parameters. This block is not validated.
The following data is realized in demo application:

  • deliveryStatus — status of the activity:

    • 1 — start of a new activity (the usual push notification will be sent in the request);

    • 2 — updating a started activity with event=update;

    • 3 — ending of the started activity with event=end;

  • deliveryTime — push notification delivery time;

  • alert — contains data to be displayed in the widget (implemented on the mobile application side).

param_name=SECURE

message/data/extraOptions/ param_value

string
Names of parameters with sensitive data (param_name=SECURE).
When sending via cloud providers, sensitive data transmitted in a push notification is masked using templates (substitutions in the text and in the title of the notification).
Requirements for naming parameters with data for substitution: * the text must be in Latin; * the use of special characters is unacceptable.
In the example above (a request with enriched SECURE data) the variables %name%, %card% and %data% are specified in the text and in the header of the message.
These values must be passed in param_value for further substitution.

param_name=SENDING_PLATFORMS

message/data/extraOptions/ param_value

string
The list of names of providers to which you need to send messages.
Possible values are:

  • Android;

  • Ios;

  • Huawei;

  • RuStore.

Response to the Request#

After sending a message the Service Provider returns a response synchronously. In case of successful sending the Service Provider returns HTTP-code 200 OK.

Successful Sending#

1  {
2     "mtNum": "7390612217"
3     "id": "8770599"
4  }

Sending Errors#

For results with errors, a response HTTP code will differ from 200 (see Error Codes).

1 {
2     "error": {
3        "code": 1,
4        "description": "Service is unavailable"
5     }
6 }

Error Codes#

Code

Description

HTTP code

1

Service is unavailable

503

2

Invalid IP-address

403

3

Too many connections

429

4

Invalid request

400

5

Invalid login

401

6

Invalid password

401

7

serviceNumber is not defined

400

8

destAddr is not correct

406

9

Message type is not correct

406

10

Prohibited sending duplicates

409

11

Invalid TTL

406

100

100

500

Push Notification Delivery Statuses#

To receive statuses of push notifications, you need to set up a Delivery Status Service.