Send notifications via our API

Owners of decentralized apps (dApps) want to send notifications to their users, to be displayed in the FE of their respective dApps.

CNS will be used as a platform for dApps to send notifications and CNS will be responsible for streaming these notifications to the FE of their dApps.

A REST API endpoint will be exposed by CNS for dApps to send notifications to our platform.

Design & Implementation

We would have separate endpoints for different media platforms, for example, POST /channel/{channelId}/message for in-app notifications and POST /channel/{channelId}/message/telegram for telegram notifications. Most of the fields in the request body are identical for both endpoints, except platform-specific fields, such as parse_mode for telegram notifications.

REST API endpoint design

POST /channel/{channelId}/message - Send in-app notification

Request Component	Name	Type	Description	isRequired
Request Headers	CNS-Api-Key	String	API Key required to call the API	Yes
Path Variable	channelId	String	Channel ID associated with the dApp	Yes
Request Body	delivery_type	String	BROADCAST - send to all users, UNICAST - send to selected user	Yes
	receiver_address	String	Can be omitted if delivery_type is BROADCAST, else wallet address of recipient	No/Yes
	title	String	Title of the notification (max 1024 chars), no restrictions on the format	Yes
	body	String	Body of the notification (max 4096 chars), no restrictions on the format	Yes
	type	String	Type the notification (max 50 chars)	Yes
	chain_id	Int	Chain ID of the notification to send	Yes
	event_timestamp	Timestamp	Timestamp when the notification is triggered on DApp, if not set it'll be the time when CNS got the request	No

Note:

Infra setup will be in place to restrict API access to selected dApps using the API (Kaching would be our first dApp partner). API Authentication using mechanisms like API keys might be considered in the future but not supported in MVP.

Example Request:

Copy

POST /channel/0xb9cb77b5d2f63ee09708f9f3419d6c1613cc53c99ef529385e7dd8c8c7001912/message
CNS-Api-Key: xxx
{
  "delivery_type": "BROADCAST",
  "title": "New feature",
  "body": "New feature xx is out, go and check it out at https://www.yyy.com",
  "type": "SYSTEM",
  "chain_id": 25,
  "event_timestamp": "2022-01-01T00:00:00Z"
}

Copy

POST /channel/0xb9cb77b5d2f63ee09708f9f3419d6c1613cc53c99ef529385e7dd8c8c7001912/message
CNS-Api-Key: xxx
{
  "delivery_type": "UNICAST",
  "receiver_address": "0xd6e1125158e3d83fa0e795b3a957ba5b2ca52d02",
  "title": "Pending rewards",
  "body": "You have some pending rewards, go and claim it before it is too late",
  "type": "REWARDS",
  "chain_id": 25,
  "event_timestamp": "2022-01-01T00:00:00Z"
}

Response Body:

• No JSON response body needed to be returned

• Successful response will return status code 204

POST /channel/{channelId}/message/telegram - Send telegram notification

Request Component	Name	Type	Description	isRequired
Request Headers	CNS-Api-Key	String	API Key required to call the API	Yes
Path Variable	channelId	String	Channel ID associated with the dApp	Yes
Request Body	delivery_type	String	BROADCAST - send to all users, UNICAST - send to selected user	Yes
	receiver_address	String	Can be omitted if delivery_type is BROADCAST, else wallet address of recipient	No/Yes
	body	String	Body of the notification (max 4096 chars), no restriction on the format	Yes
	type	String	Type the notification (max 50 chars)	Yes
	parse_mode	String	Content format options of Telegram, available options are: MarkdownV2, HTML, Markdown, by default there'll be no format	No

Example Request:

Copy

POST /channel/0xb9cb77b5d2f63ee09708f9f3419d6c1613cc53c99ef529385e7dd8c8c7001912/message/telegram
CNS-Api-Key: xxx
{
  "delivery_type": "BROADCAST",
  "body": "<strong>New feature xx is out</strong>. Go and check it out at https://www.yyy.com",
  "type": "SYSTEM",
  "parse_mode": "HTML"
}

Copy

POST /channel/0xb9cb77b5d2f63ee09708f9f3419d6c1613cc53c99ef529385e7dd8c8c7001912/message/telegram
CNS-Api-Key: xxx
{
  "delivery_type": "UNICAST",
  "receiver_address": "0xd6e1125158e3d83fa0e795b3a957ba5b2ca52d02",
  "body": "You have some pending rewards, go and claim it before it is too late",
  "type": "REWARDS"
}

Response Body:

• No JSON response body needed to be returned

• A successful response will return status code 204