Managing inbox notifications

Notifications that are configured as inbox are stored in the NET2GRID Insight and should be displayed inside the customer's solution. The CE API provides endpoints to fetch all inbox notifications, mark inbox notifications as read/ unread and delete inbox notifications. Each of these endpoints will be explained in greater detail below.

Fetching inbox notifications

The Get messages CE API endpoint allows developers to download all inbox notifications for the current user. These messages can then be displayed inside the customer's solution.

A pseudo-code request to the Get messages endpoint looks like this:

GET /v2/messages
Authorization: Bearer <access_token>

A successful request will return a response similar to the following:

{
  "status": "ok",
  "data": [
    {
      "object_id": 1,
      "message_code": "M019",
      "is_read": 0,
      "timestamp": "2022-05-30T06:06:30+02:00",
      "category": "report",
      "attributes": [
        {
          "attribute1_name": "attribute1_value"
        }
      ],
      "attachments": []
    }
  ]
}

As you'd probably expect the response contains the standard JSON structure containing the status field indicating if the response was successful or not and if successful the data field will contain a list of message objects. Each message consists of the following properties:

Field	Type	Description
object_id	Integer	Uniquely identifies each message. The `object_id` can be used to identify the message when marking a notification as read/ unread or when deleting a message.
message_code	String	The `message_code` identifies the notification. Using the `message_code` the integrating software solution can identify the notification and display the appropriate message. The message codes that can be returned are described in the Supported Notifications section.
is_read	Boolean	Indicates if the message has been marked as read by the end-user.
category	String	Indicates the category defined in configuration setup during customer onboarding for this notification. Can be `report` or `system`
timestamp	DateTime	The date and time the notification was triggered.
attributes	array	(Optional) Contains additional information that can be used to better describe the notification. The attributes relevant to each notification type are described in the Supported Notifications section.
attachments	array	(Optional) Contains link to attachments associated with this notifications. The attachments relevant to each notification type are described in the Supported Notifications section.

Marking messages as read

The Mark message as read CE API endpoint allows developers to mark a notification as read. This allows developers to add a visual marker to notifications allowing end-users to distinguish between new messages and messages already read.

The pseudo-code request to the Mark message as read endpoint looks lit this:

PUT /v2/messages/{inboxNotificationId}/read
Authorization: Bearer <access_token>

The inboxNotificationId path parameter should match the object_id of the notification that should be marked as read.

Marking messages as unread

To allow end-users to mark a message as unread, so they can comeback to it later, the CE API provides the Mark message as unread endpoint.

PUT /v2/messages/{inboxNotificationId}/unread
Authorization: Bearer <access_token>

The inboxNotificationId path parameter should match the object_id of the notification that should be marked as unread.

After marking a notification as unread the Get messages endpoint will return the value 0 for the is_read property for this message, indicating the message is marked as not read.

Deleting messages

The Delete message endpoints allows for deleting notifications. Deleted notification will no longer be returned by the Get messages endpoint for that end-user. To delete a message send a delete request as shown below:

DEL /v2/messages/{inboxNotificationId}/delete
Authorization: Bearer <access_token>

The inboxNotificationId path parameter should match the object_id of the notification that should be deleted.