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.

extended requesttexttext and headerprimary application attributeimageimage and buttonsHTMLsubscriptionsdata for applicationdata for statisticsdata enrichment

Description of useTimeDiff ; destAddr parameters.

  {
     "login":"YOUR_LOGIN",
     "password":"YOUR_PASSWORD",
     "id":"8770630",
     "extraParam":"param1=value1,param2=value2",
     "registeredDelivery":"1",
     "notifyUrl":"URL_for_sending_statuses"
     "useTimeDiff":true,
     "scheduleInfo":{
       "timeBegin":"10:00",
       "timeEnd":"12:00",
       "weekdaysSchedule":"123",
       "deadline": "2029-12-31T16:29:30+0300"
     },
     "destAddr":"Subscriber's_Number",
     "message":{
       "type":"Push",
       "data":{
         "externalUserId": "subscriber's_ID",
         "text":"Notification text",
         "serviceNumber":"SENDER'S_NAME",
         "ttl":10,
         "ttlUnit": "SECONDS",
       }
     }
  }

Request Parameters

Parameter	Required	Data type	Description
login	yes	string	Partner’s name in the system.
password	yes	string	Partner’s password in the system.
extraParam	no	string	Additional parameters passed as param1=value1,param2=value2, where: param1 and param2 – parameter names; value1 and value2 – values. More details 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	no	boolean	Taking into account the time zone when starting messaging. More details 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	no	object	Messaging schedule. More details If it is not specified, it is sent immediately upon receipt of the request.
scheduleInfo/timeBegin	no	string	Start time. More details Example: 10:00.
scheduleInfo/timeEnd	no	string	End time. More details Example: 21:00.
scheduleInfo/ weekdaysSchedule	no	string	Messaging days. More details 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	no	string	End date of the messaging. More details Example: 2024-09-10T16:29:30+0300.
id	no	string	Partner-side unique ID. More details 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	no	boolean	Parameter enables automatic shortening of URL strings in the message. More details 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. Note The ability to use this service is previously agreed with and configured by the Service Provider.
destAddr	no	string	Subscriber’s phone number. More details Mandatory in case of push message if the message/data/externalUserId parameter is missing. It contains the country code, operator code and phone number. For the Russian Federation, the code 8, 7 or +7. Examples: 72101234567, +72101234567, 8-210-123-45-6, 82101234567.
message	yes	object	Parameters of a message being sent.
message/type	yes	enum	Message type. The value of PUSH is transmitted.
message/data	yes	object	Parameters of the data being sent.
message/data/ externalUserId	no	string	User ID to send push messages (login, email, UID).
message/data/ttl	no	integer	Message lifetime. Acceptable range in seconds: from 30 to 86400. More details Acceptable range in seconds: from 30 to 86400. Note 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	no	enum	Unit of measurement of the message delivery period. More details It is transmitted only with ttl. Possible values are: SECONDS; MINUTES; HOURS.
message/data/ serviceNumber	no	string	Sender’s name from which the message is being sent.
message/data/text	yes	string	Message text. More details Maximum length: 1000 characters.
Request with a header title
message/data/title	no	string	Header of the text message. More details Amount of characters is no more than: 80.
Request with the primary application attribute (primaryOn)
message/data/ primaryOn	no	boolean	Indication of the primary application installed on the subscriber’s device. More details 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	no	integer	Requirement of delivery reports. More details Possible values are: 0 — statuses are not required; 1 — statuses are required (by default); 2 — only "Undelivered" status is required.
notifyUrl	no	string	Hostname of the incoming API to obtain the delivery report (see Delivery Status Service). More details 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	no	object	Parameters for sending images, HTML links and buttons.
message/data/ content/ contentCategory	no	enum	Content category by the contentUrl link. More details 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	no	string	URL of the image or HTML. More details 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	no	array	Array containing buttons. The description of the button attributes is given in the tabLe below. More details The buttons allow to: open a message; follow the specified link.
message/data/ content/actions/ title	no	string	Inscription on the button. More details Amount of characters: no more than 64.
message/data/ content/actions/ action	no	string	Text ID of the button in the mobile application. More details 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	no	string	Additional button parameters. More details 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 case of a button with action = link the URL for the transition can be specified.
Request with subscriptions (deviceSubscriptions)
message/data/ deviceSubscriptions	no	array	Transmitted array with a list of mobile app subscriptions.
Request with data for the application (customPayload)
message/data/ customPayload	no	JSON Object	Data which are transmitted in its original form for further use in the mobile application.
Request with data for statistics (callbackData)
message/data/ callbackData	no	string	Client data for statistics. More details 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	no	array	Array of additional data objects from the partner. More details It contains two mandatory parameters: param_name and param_value.
message/data/ extraOptions/ param_name	yes	string	Transmission of the message attribute. More details 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	yes	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	no	string	Header of the message. More details 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	no	string	Message text. Подробнее If it is sent in RICH, then the sent text is replaced.
message/data/ extraOptions/ param_value/ content-category	no	string	Content type. More details 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	no	string	Link for the content. More details 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	no	string	User data. More details 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	no	array	List of buttons. More details 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	no	timestamp	timestamp in ISO 860 format — date and time when Live Activity is considered obsolete.
message/data/ extraOptions/ param_value/aps/ dismissal_date	no	timestamp	timestamp in ISO 8601 format — date and time when Live Activity closes on the lock screen. More details 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	yes	timestamp	timestamp in ISO 8601 format.
message/data/ extraOptions/ param_value/aps/ event	yes	string	Event for updating the Live Activity. More details This parameter can take the following values: update; end.
message/data/ extraOptions/ param_value/aps/ content_state	no	object	Data that will be displayed in the Live Activity widget. More details 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	no	string	Names of parameters with sensitive data (param_name = SECURE). More details 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	no	string	List of names of providers to which you need to send messages. More details Possible values are: Android; IOS; Huawei; RuStore; Pwa (for sending web push notifications).

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

Response exampleResponse parameters

  {
     "mtNum": "7390612217"
     "id": "8770599"
  }

Sending Errors

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

Response exampleResponse parameters

{
    "error": {
       "code": 1,
       "description": "Service is unavailable"
    }
}

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 the Delivery Status Service.

Delivery Error Codes

Delivery error codes for each message type are provided in the corresponding tab of the Description of Error Codes (parameter status=5) section.