API notification management

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Notification template management API

The API route is intended for service use by the Regulation Publication Pipeline to populate the template repository with data. Root is not accessible externally via Kong.

PUT /api/notifications/templates/{channel}:{name}

Parameter Type Part of the request Description

channel

Textual

Query parameter

Channel name [inbox, email, diia]

name

Textual

Query parameter

The unique name of the template within the channel
Example of request body
{
  "title": "{title}",
  "content": "{content}",
  "attributes": [
    {
      "name": "actionType",
      "value": "message"
    },
    {
      "name": "templateType",
      "value": "attention"
    },
    {
      "name": "shortText",
      "value": "{shortText}"
    }
  ]
}
An example of response
{
  "name": "{template_name}",
  "channel": "{channel}",
  "title": "{title}",
  "content": "{content}",
  "checksum": "{sha256-hash}",
  "attributes": [
    {
      "name": "actionType",
      "value": "message"
    },
    {
      "name": "templateType",
      "value": "attention"
    },
    {
      "name": "shortText",
      "value": "{shortText}"
    }
  ],
  "createdAt": "{timestamp}",
  "updatedAt": "{timestamp}",
  "externalTemplateId": "{external-id}",
  "externallyPublishedAt": "{timestamp}"
}
Table 1. Error codes
Code Description

200

OK with returning the data result of the modified template

201

Created with returning the result of the template data

400

Incorrectly formed request

401

Authentication error (missing access token)

500

Server error processing of the request

==API access to the inbox of user notifications

Obtaining access to the API is possible only within the framework of the execution of a request of an authenticated user in the system

1.1. Receiving a list of in-app notifications in the User portal

This API route is public and should be published for external access via a separate Kong Route for Citizen portal.

GET /api/notifications/inbox

Parameter Type Part of the request Description

X-Access-Token

JWT

HTTP header

User access token

limit

int

Query parameter

Number of notifications for one-time receiving (for pagination)

offset

int

Query parameter

Indent from the first notification (for pagination)
The user ID for message filtering is obtained from the access token (RECIPIENT_ID field). The resulting records should be ordered in reverse order by created_at (created_at DESC)
An example of response
[
  {
    "id": "id1",
    "subject": "SUBJECT",
    "message": "Some content",
    "isAcknowledged": true,
    "createdAt": "2022-07-29 11:08:16"
  },
  {
    "id": "id2",
    "subject": "SUBJECT2",
    "message": "Some different content",
    "isAcknowledged": false,
    "createdAt": "2022-07-27 16:04:17"
  }
]
Table 2. Response codes
Code Description

200

OK

400

Incorrectly formed request

401

Authentication error (missing access token)

500

Server error processing the request

1.2. Confirmation of viewing the in-app notification in the User portal

This API route is public and should be published for external access via a separate Kong Route for Citizen portal.

POST /api/notifications/inbox/{id}/ack

Parameter Type Part of the request Description

X-Access-Token

JWT

HTTP header

User access token

id

Text

Query parameter

Notification ID
Table 3. Response codes
Code Description

200

OK

400

Incorrectly formed request

401

Authentication error (missing access token)

403

Access denied (when trying to update someone else’s message)

500

Server error processing the request