Sending push notifications (API)

API for sending push notifications

The API was designed to provide a drop-in replacement for Firebase.

To send a push notification, use the POST method: https://vkpns.rustore.ru/v1/projects/$project_id/messages:send.

Specify the Project ID and Service token to send a push notification. You can get these values in the RuStore Console. To do that, open your app page, go to Push notifications, and select Projects.

The service token must be passed in the Authorization header: Authorization: Bearer {service-token}.

Request body

Parameter	Type	Description
message	object (message)	Push notification structure.

message

Parameter	Type	Description
token	string	User push token obtained in the app.
data	map[string]string	An object containing "key": value pairs.
notification	object (message.notification)	Base notification template used across all platforms.
android	object (message.android)	Android-specific message parameters.

message.notification

Parameter	Type	Description
title	string	Notification title.
body	string	Notification body text.
image	string	URL of the image to be shown in the notification.

message.android

Parameter	Type	Description
ttl	string (duration format)	How long (in seconds) the message should be kept in storage. Example: 3.5s.
notification	object (message.android.notification)	Notification to be sent to Android devices.

message.android.notification

Parameter	Type	Description
title	string	Notification title.
body	string	Notification body text.
icon	string	Notification icon.
color	string	Icon color in #rrggbb format.
image	string	URL of the image to be shown in the notification.
channel_id	string	Notification channel ID.
click_action	string	Action associated with the user clicking the notification.
click_action_type	int	Optional field: type of click_action (default 0 — click_action is treated as an intent action; 1 — click_action is treated as a deep link).

caution

Note: for deep link to work correctly (click_action_type set to 1), the RuStore version must be 1.39.0 or higher.

caution

If the notification structure does not contain the title field, the SDK will not display the push notification.

info

At the moment, only the fields listed above are supported in the message structure.

Successful response body

Parameter	Type	Description
—	—	On success, the response contains an empty payload.

Error response body

Parameter	Type	Description
error	object (error)	Error object.

error

Parameter	Type	Description
code	number	Numeric error code (404, 400, 403, 401, ...).
message	string	Detailed error message.
status	string	Text error code (INVALID_ARGUMENT, UNREGISTERED, ...).

HTTP status matches the code field.

Possible errors when sending a message

• INVALID_ARGUMENT — request parameters are invalid.
• INTERNAL — internal service error.
• TOO_MANY_REQUESTS — too many attempts to send a message.
• PERMISSION_DENIED — service key is incorrect.
• NOT_FOUND — user push token is incorrect.

Message validation algorithm

• If message.data.payload is present and non-empty (there is at least one key-value pair), the message is valid. message.notification and message.android sections may be omitted.
• If message.data is absent, notification is required. In this case, the presence of either message.notification or message.android.notification is checked. At least one of these fields must be present; both may be present (if both are present, some fields are overwritten).

Limitations

• If the push does not contain the ttl field or it equals 0, the default value of 4 weeks is used. If the message.android section is missing, it is added with the ttl field.
• Maximum message size is 4096 bytes.

Examples of sending push notifications

Example of a successful request

POST https://vkpns.rustore.ru/v1/projects/myproject-b5ae1/messages:send HTTP/2
Content-Type: application/json
Authorization: Bearer $ss_token
{
   "message" :{
      "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..." ,
      "notification" :{
        "body" : "This is a notification message!" ,
        "title" : "Message" ,
        "image" : "https://image-hosting.org/284239234.jpeg"
      }
   }
}

Response to a successful request

HTTP/ 2 200
{}

Example request with an invalid push token

POST https://vkpns.rustore.ru/v1/projects/U95076bdd5KDJ3LjYkNp91o05Y6LkfQk/messages:send HTTP/2
Content-Type: application/json
Authorization: Bearer Fw9FgDx9FQtya6k-7UkSOnzpHYhDq0SQY4-8QKJ6wKZI9OUPiCCYyNmS-CV2-ZQ5
{
   "message" : {
      "token" :  "bad-push-token" ,
      "notification" : {
        "body" : "This is a notification message!" ,
        "title" : "Message" ,
        "image" : "https://image-hosting.org/284239234.jpeg"
      }
   }
}

Response to a request with an invalid push token

HTTP/ 2 400
{
    "error" : {
        "code" :  400 ,
        "message" :  "The registration token is not a valid FCM registration token" ,
        "status" :  "INVALID_ARGUMENT"
    }
}

Example request with a valid push token that has expired

POST https://vkpns.rustore.ru/v1/projects/U95076bdd5KDJ3LjYkNp91o05Y6LkfQk/messages:send HTTP/2
Content-Type: application/json
Authorization: Bearer Fw9FgDx9FQtya6k-7UkSOnzpHYhDq0SQY4-8QKJ6wKZI9OUPiCCYyNmS-CV2-ZQ5
{
   "message" : {
      "token" :  "eH4tgqKEfFKqH6cMJ2WLttVibgQO9hfn" ,
      "notification" : {
        "body" :  "This is a notification message!" ,
        "title" :  "Message" ,
        "image" :  "https://image-hosting.org/284239234.jpeg"
      }
   }
}

Response to a request with a valid push token that has expired

HTTP/ 2 404
{
    "error" : {
        "code" :  404 ,
        "message" :  "Requested entity was not found." ,
        "status" :  "NOT_FOUND"
    }
}

Example of a successful request using a deep link

POST https://vkpns.rustore.ru/v1/projects/myproject-b5ae1/messages:send HTTP/2
Content-Type: application/json
Authorization: Bearer $ss_token
{
   "message" :{
      "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..." ,
      "notification" :{
        "body" : "This is a notification message!" ,
        "title" : "Message" ,
        "image" : "https://image-hosting.org/284239234.jpeg"
      }
      "android": {
        "notification": {
            "body" : "This is a notification message!" ,
            "title" : "Message" ,
            "image" : "https://image-hosting.org/284239234.jpeg"
            "click_action": "https://sample.com/",
            "click_action_type": 1
        }
      }
   }
}

Response to a successful request using a deep link

HTTP/ 2 200
{}

Example of a successful request using an intent action

POST https://vkpns.rustore.ru/v1/projects/myproject-b5ae1/messages:send HTTP/2
Content-Type: application/json
Authorization: Bearer $ss_token
{
   "message" :{
      "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..." ,
      "notification" :{
        "body" : "This is a notification message!" ,
        "title" : "Message" ,
        "image" : "https://image-hosting.org/284239234.jpeg"
      }
      "android": {
        "notification": {
            "body" : "This is a notification message!" ,
            "title" : "Message" ,
            "image" : "https://image-hosting.org/284239234.jpeg"
            "click_action": "some_unique_intent_action",
            "click_action_type": 0
        }
      }
   }
}

Response to a successful request using an intent action

HTTP/ 2 200
{}