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
{}

API for sending push notifications​

Request body​

message​

message.notification​

message.android​

message.android.notification​

Successful response body​

Error response body​

error​

Possible errors when sending a message​

Message validation algorithm​

Limitations​

Examples of sending push notifications​

Example of a successful request​

Response to a successful request​

Example request with an invalid push token​

Response to a request with an invalid push token​

Example request with a valid push token that has expired​

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

Example of a successful request using a deep link​

Response to a successful request using a deep link​

Example of a successful request using an intent action​

Response to a successful request using an intent action​