Skip to main content

Sending Push Notifications by Topic (API)

API for Sending Push Notifications by Topic​

The following artifacts are required for working with topics:

  • project_id (Project ID), ss_token (service token) — these values can be obtained in the developer console. Go to Push Notifications, open the Projects tab on the app page. For more details, see the Sending Push Notifications section.
  • push_token — the push token(s) of devices for subscribing to and unsubscribing from topic-based mailing.
  • topic — the topic in the project.

Sending a Push Notification to a Topic​

info

The Authorization header is required: Authorization: Bearer $ss_token.

Request Body​

ParameterTypeDescription
datamapAn object containing "key": value pairs.
notificationobject (message.notification)Basic notification template for use on all platforms.
androidobject (message.android)Android-specific parameters for messages.

Successful Response Body​

ParameterTypeDescription
messagetextSuccess message for push sending.

Error Response Body​

ParameterTypeDescription
codenumberError code.
statustextStatus.
messagetextDetailed error.

Subscribing to Push Notifications by Topic​

info

The Authorization header is required: Authorization: Bearer $ss_token.

Request Body​

ParameterTypeDescription
push_tokensarray (string)Push tokens to subscribe to the topic.

Successful Response Body​

ParameterTypeDescription
messagetextSuccess message or error report.
errorsobject array (token error body)Errors per token.

Token Error Body​

ParameterTypeDescription
push_tokentextPush token.
errorobject (error response body)Error details.

Error Response Body​

ParameterTypeDescription
codenumberError code.
statustextStatus.
messagetextDetailed error.

Unsubscribing from Push Notifications by Topic​

info

The Authorization header is required: Authorization: Bearer $ss_token.

Request Body​

ParameterTypeDescription
push_tokensstring arrayPush tokens to unsubscribe from the topic.

Successful Response Body​

ParameterTypeDescription
messagetextSuccess message or error report.
errorsobject array (token error body)Errors per token.

Token Error Body​

ParameterTypeDescription
push_tokentextPush token.
errorobject (error response body)Error details.

Error Response Body​

ParameterTypeDescription
codenumberError code.
statustextStatus.
messagetextDetailed error.

Examples of Sending Push Notifications by Topic​

Subscribing to the hello Topic​

Request​

POST  'https://vkpns-topics.rustore.ru/v1/projects/{project_id}/topics/{topic}/batch_subscribe' HTTP/2
Content-Type: application/json
Authorization: Bearer $ss_token
{
    "push_tokens" : [
        "kHrfTow3AjqdgUeCJLwbIHd7c0......",
        "9mbJVS0-2e0cCcIx7X5nxMIgp8......"
    ]
}

Successful Response​

HTTP/ 2 200
{
    "message" : "success"
}

Partially Successful Response​

HTTP/ 2 200
{
    "message" : "1 error(s)",
    "errors" : [
        {
            "push_token" : "9mbJVS0-2e0cCcIx7X5nxMIgp8......", 
            "error" : {
                "code" : 1001 ,
              "status" : "FORBIDDEN",
                "message" : "s2s token invalid"
            }
        }
    ]
}

Unsubscribing from the hello Topic​

Request​

POST  'https://vkpns-topics.rustore.ru/v1/projects/{project_id}/topics/{topic}/batch_unsubscribe' HTTP /2
Content-Type: application /json
Authorization: Bearer $ss_token
{
    "push_tokens" : [
        "kHrfTow3AjqdgUeCJLwbIHd7c0......",
        "9mbJVS0-2e0cCcIx7X5nxMIgp8......"
    ]
}

Successful Response​

HTTP/ 2 200
{
    "message" : "success"
}

Partially Successful Response​

HTTP/ 2 200
{
    "message" : "1 error(s)",
    "errors" : [
        {
            "push_token" : "9mbJVS0-2e0cCcIx7X5nxMIgp8......", 
            "error" : {
                "code" : 1001 ,
              "status" : "FORBIDDEN",
                "message" : "s2s token invalid"
            }
        }
    ]
}

Sending a Message to the hello Topic​

Request​

POST  'https://vkpns-topics.rustore.ru/v1/projects/Lpvk29a2Al2P6tWu-a-aN3PKwO6-qvXZ/topics/hello/publish' HTTP /2
Content-Type: application /json
Authorization: Bearer $ss_token
{
    "message" : {
        "notification" :{
            "body" : "This is a notification message!",
            "title" : "Message",
            "image" : "https://image-hosting.org/284239234.jpeg"
        }
    }
}

Successful Response​

HTTP/ 2 200
{
    "message" : "payload has been successfully published to topic hello"
}

Example of an error BAD_REQUEST​

HTTP/ 2 400
{
    "code" : 2000 ,
    "status" : "BAD_REQUEST",
    "message" : "failed to parse request: invalid character 's' after object key:value pair"
}

Example of an error FORBIDDEN​

HTTP/ 2 403
{
    "code" : 1001 ,
    "status" : "FORBIDDEN",
    "message" : "s2s token invalid"
}