You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
162 lines
6.0 KiB
162 lines
6.0 KiB
5 years ago
|
# Reading and deleting notifications as a Client v2
|
||
|
|
|
||
|
|
## New in APIv2
|
||
|
|
|
||
|
|
* :new: Support for icons was added with capability-entry `icons`
|
||
|
|
* :new: Support for [Rich Object Strings](https://github.com/nextcloud/server/issues/1706) was added with capability-entry `rich-strings`
|
||
|
|
* :new: ETag/If-None-Match are now evaluated and respond with `304 Not Modified` and empty body when unchanged.
|
||
|
|
|
||
|
|
## Checking the capabilities of the server
|
||
|
|
|
||
|
|
In order to find out if notifications is installed/enabled on the server you can run a request against the capabilities endpoint: `/ocs/v2.php/cloud/capabilities`
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"ocs": {
|
||
|
|
...
|
||
|
|
"data": {
|
||
|
|
...
|
||
|
|
"capabilities": {
|
||
|
|
...
|
||
|
|
"notifications": {
|
||
|
|
"ocs-endpoints": [
|
||
|
|
"list",
|
||
|
|
"get",
|
||
|
|
"delete",
|
||
|
|
"delete-all",
|
||
|
|
"icons",
|
||
|
|
"rich-strings",
|
||
|
|
"action-web"
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Getting the notifications of a user
|
||
|
|
|
||
|
|
The user needs to be identified/logged in by the server. Then you can just run a simple GET request against `/ocs/v2.php/apps/notifications/api/v2/notifications` to grab a list of notifications:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"ocs": {
|
||
|
|
"meta": {
|
||
|
|
"status": "ok",
|
||
|
|
"statuscode": 200,
|
||
|
|
"message": null
|
||
|
|
},
|
||
|
|
"data": [
|
||
|
|
{
|
||
|
|
"notification_id": 61,
|
||
|
|
"app": "files_sharing",
|
||
|
|
"user": "admin",
|
||
|
|
"datetime": "2004-02-12T15:19:21+00:00",
|
||
|
|
"object_type": "remote_share",
|
||
|
|
"object_id": "13",
|
||
|
|
"subject": "You received admin@localhost as a remote share from test",
|
||
|
|
"subjectRich": "You received {share} as a remote share from {user}",
|
||
|
|
"subjectRichParameters": {
|
||
|
|
"share": {
|
||
|
|
"type": "pending-federated-share",
|
||
|
|
"id": "1",
|
||
|
|
"name": "test"
|
||
|
|
},
|
||
|
|
"user": {
|
||
|
|
"type": "user",
|
||
|
|
"id": "test1",
|
||
|
|
"name": "User One",
|
||
|
|
"server": "http:\/\/nextcloud11.local"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"message": "",
|
||
|
|
"messageRich": "",
|
||
|
|
"messageRichParameters": [],
|
||
|
|
"link": "http://localhost/index.php/apps/files_sharing/pending",
|
||
|
|
"icon": "http://localhost/img/icon.svg",
|
||
|
|
"actions": [
|
||
|
|
{
|
||
|
|
"label": "Accept",
|
||
|
|
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
|
||
|
|
"type": "POST",
|
||
|
|
"primary": true
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"label": "Decline",
|
||
|
|
"link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
|
||
|
|
"type": "DELETE",
|
||
|
|
"primary": false
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Response codes
|
||
|
|
|
||
|
|
Status | Explanation
|
||
|
|
---|---
|
||
|
|
`204 No Content` | please slow down the polling to once per hour, since there are no apps that can generate notifications
|
||
|
|
`304 Not Modified` | The provided `If-None-Match` matches the ETag, response body is empty
|
||
|
|
|
||
|
|
### Specification
|
||
|
|
|
||
|
|
Optional elements are still set in the array, the value is just empty:
|
||
|
|
|
||
|
|
Type | Empty value
|
||
|
|
---- | -----------
|
||
|
|
string | `""`
|
||
|
|
array | `[]`
|
||
|
|
|
||
|
|
#### Notification Element
|
||
|
|
|
||
|
|
Field name | Type | Since | Value description
|
||
|
|
---------- | ---- | ----- | -----------------
|
||
|
|
notification_id | int | v1 | Unique identifier of the notification, can be used to dismiss a notification
|
||
|
|
app | string | v1 | Name of the app that triggered the notification
|
||
|
|
user | string | v1 | User id of the user that receives the notification
|
||
|
|
datetime | string | v1 | ISO 8601 date and time when the notification was published
|
||
|
|
object_type | string | v1 | Type of the object the notification is about, that can be used in php to mark a notification as resolved
|
||
|
|
object_id | string | v1 | ID of the object the notification is about, that can be used in php to mark a notification as resolved
|
||
|
|
subject | string | v1 | Translated short subject that should be presented to the user
|
||
|
|
subjectRich | string | v2 :new: | (Optional) Translated subject string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
|
||
|
|
subjectRichParameters | array | v2 :new: | (Optional) Subject parameters for `subjectRich` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
|
||
|
|
message | string | v1 | (Optional) Translated potentially longer message that should be presented to the user
|
||
|
|
messageRich | string | v2 :new: | (Optional) Translated message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
|
||
|
|
messageRichParameters | array | v2 :new: | (Optional) Message parameters for `messageRich` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
|
||
|
|
link | string | v1 | (Optional) A link that should be followed when the subject/message is clicked
|
||
|
|
icon | string | v2 :new: | (Optional) A link to an icon that should be shown next to the notification.
|
||
|
|
actions | array | v1 | (Optional) An array of action elements
|
||
|
|
|
||
|
|
|
||
|
|
#### Action Element
|
||
|
|
|
||
|
|
Field name | Type | Value description
|
||
|
|
---------- | ---- | -----------------
|
||
|
|
label | string | Translated short label of the action/button that should be presented to the user
|
||
|
|
link | string | A link that should be followed when the action is performed/clicked
|
||
|
|
type | string | HTTP method that should be used for the request against the link: GET, POST, DELETE, PUT or WEB. In case of WEB a redirect should happen instead.
|
||
|
|
primary | bool | If the action is the primary action for the notification or not
|
||
|
|
|
||
|
|
|
||
|
|
## Get a single notification for a user
|
||
|
|
|
||
|
|
In order to get a single notification, you can send a GET request against `/ocs/v2.php/apps/notifications/api/v2/notifications/{id}`
|
||
|
|
|
||
|
|
|
||
|
|
## Deleting a notification for a user
|
||
|
|
|
||
|
|
In order to delete a notification, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v2/notifications/{id}`
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Deleting all notifications for a user
|
||
|
|
|
||
|
|
In order to delete all notifications, you can send a DELETE request against `/ocs/v2.php/apps/notifications/api/v2/notifications`
|
||
|
|
|
||
|
|
**Note:** This endpoint was added for Nextcloud 14, so check for the `delete-all` capability first.
|