Table of contents

Notifications

Cozy applications can send notifications to the user, in order to alert or notify for services message or state change that could be of interest to the user, in an asynchronous manner.

These notifications are part of a “Notification Center” where the user can configure the behavior of these notifications and the channel in which they are sent.

Declare application’s notifications

Each application have to declare in its manifest the notifications it needs to send. The notifications fields of the manifest can be used to define all these notifications, with the following properties:

In this documentation, we take the example of an application with the following notification:

{
    "notifications": {
        "account-balance": {
            "description": "Alert the user when its account balance is negative",
            "collapsible": true, // only interested in the last value of the notification
            "multiple": true, // require sub-categories for each account
            "stateful": true, // piece of state to distinguish notifications
            "default_priority": "high", // high priority for this notification
            "templates": {
                "mail": "file:./notifications/account-balance-mail.tpl"
            }
        }
    }
}

Creating a notification

POST /notifications

This endpoint can be used to push a new notification to the user.

Notifications fields are:

Request

POST /notifications HTTP/1.1
Host: alice.cozy.tools
Authorization: Bearer ...
Content-Type: application/vnd.api+json
{
    "data": {
        "attributes": {
            "category": "account-balance",
            "category_id": "my-bank",
            "title": "Your account balance is not OK",
            "message": "Warning: we have detected a negative balance in your my-bank",
            "priority": "high",
            "state": "-1",
            "preferred_channels": ["mobile"],
            "data": {
                "key1": "value1",
                "key2": "value2"
            }
        }
    }
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
    "data": {
        "type": "io.cozy.notifications",
        "id": "c57a548c-7602-11e7-933b-6f27603d27da",
        "meta": {
            "rev": "1-1f2903f9a867"
        },
        "attributes": {
            "source_id": "cozy/app/bank/account-balance/my-bank",
            "originator": "app",
            "slug": "bank",
            "category": "account-balance",
            "category_id": "my-bank",
            "title": "Your account balance is not OK",
            "message": "Warning: we have detected a negative balance in your my-bank",
            "priority": "high",
            "state": "-1",
            "data": {
                "key1": "value1",
                "key2": "value2"
            }
        }
    }
}