# 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 <a href="#design-and-implementation" id="design-and-implementation"></a>

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 <a href="#rest-api-endpoint-design" id="rest-api-endpoint-design"></a>

**`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](https://core.telegram.org/bots/api#formatting-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