Manage custom notifications

The Knox Configure v2 APIs provide functionalities to create and retrieve custom push notifications for profiles. Custom push notifications allow you to send personalized messages to devices during profile updates. This tutorial shows you how to create and retrieve custom push notifications.

Prerequisites

Ensure that you have the necessary permissions to manage profiles and obtain an authentication token. For more information, see Get started. Include your access token in the Authorization: Bearer <access_token> header of every request. Access tokens expire after 30 minutes.

Create a custom push notification

1. To create a custom push notification for a profile, make a POST request to the /kc/v2/profiles/{profileId}/customNotifications endpoint. This operation requires the kc.profile:manage scope.

2. In the request, specify the profileId as a path parameter. In the request body, you can use the following parameters:

   • version — The current version of the custom push message. Must be the same as the profile version. This is a required parameter.
   • message — The text of the custom push message. This is a required parameter.
   • hyperlink — The hyperlink included in the custom push message.

For example, the following request body creates a custom push notification for the profile with ID 1129471783, with the message My custom push message and a hyperlink:

POST /kc/v2/profiles/1129471783/customNotifications

{
  "version": "V1.0",
  "message": "My custom push message",
  "hyperlink": "https://my-custom-push-message.com"
}

You can adjust the message, version, and hyperlink based on the notification you want to send. For detailed response schema, see POST /kc/v2/profiles/{profileId}/customNotifications.

Retrieve custom push notifications

1. To retrieve all custom push notifications for a profile, make a GET request to the /kc/v2/profiles/{profileId}/customNotifications endpoint. This operation requires the kc.profile:view scope.

2. In the request, specify the profileId as a path parameter.

For example, the following request retrieves all custom push notifications for the profile with ID 1129471783:

GET /kc/v2/profiles/1129471783/customNotifications

The response includes a list of custom push messages, each containing details such as the message ID, version, message text, hyperlink, and whether it was the last message used for a push update. For detailed response schema, see GET /kc/v2/profiles/{profileId}/customNotifications.

Ensure that you check the code and message in the response for any errors and handle them appropriately for your app. See Error codes for the full list of Knox Configure error codes. For detailed specification, see Knox Configure API reference.