Notification Tray

Notification Tray is currently in Private Beta. Please submit your request to Amity Help Center to enable this feature. It will take approximately 5 business days to process your request.

The notification tray service is designed to automatically create and group notification records in a notification tray separated by user. The main function of this service is to provide the notification history for each user.

Here's an example of a simple notification tray that we have customized with this service. As shown in the picture, the Notification Tray contains a history of notifications displayed as rows of notification records. Each notification record contains details about a particular notification, including a list of the actors who performed the action, the action performed (verb) and the target of the action (target).

Concept

• A notification record consists of actors, a verb and a target - for example:

  • John Doe and 3 others commented on Sarah Janes's Post

    • Actors: John Doe and 3 other users

    • Verb: comment

    • Target: Sarah Jane's Post

• Notification Tray automatically groups events with the same verb and target together and aggregate list of actors into the same Notification Record.

• By default, the notification tray displays up to 10 notification records per page, sorted from newest to oldest, using the date of the last update as a reference. All notification records are stored for 90 days from the last update.

• Each notification record displays up to 3 actor names, sorted by the date of record activity, except for mentions. They won't be grouped but shown individually.

• ImageUrl of a notification record is the profile image of the latest actor who acts on the target.

• The notification record expires 90 days after the timestamp of the lastUpdate and is then deleted from Notification Tray after expiring.

• When a user leaves a community, the user's notification records are not updated with the target associated with the community. When the user rejoins a community, the notification records are updated again, but events that happen during the time the user left the community are not retroactively reflected in the record.

Scenarios

The following table shows supported scenarios and Tray Message that is recorded into Notification Record

Target Type	Verb	Scenario	Tray Message	Notification Target
Post	post	A create post on community	{DisplayName A} posted in {CommunityName}	Community's members
		A,B create post on community	{DisplayName B} and {DisplayName A} created post in {CommunityName}	Community's members
		A,B,C,D create post on community	{DisplayName D}, {DisplayName C} and {2} others posted in {CommunityName}	Community's members
Comment	comment	B comment on A’s post	User Feed: {DisplayName B} commented on your post Community Feed: {DisplayName B} commented on your post in {CommunityName}	Post owner (User A)
		B,C comment on A’s post	User Feed: {DisplayName C} and {DisplayName B}commented on your post Community Feed: {DisplayName C} and {DisplayName B} commented on your post in {CommunityName}	Post owner (User A)
		B,C,D,E comment on A’s post	User Feed: {DisplayName E}, {DisplayName D} and {2}others commented on your post Community Feed: {DisplayName E}, {DisplayName D} and {2} others commented on your post in {CommunityName}	Post owner (User A)
Reply	mentreply	B reply on A’s comment	User Feed: {DisplayName B} has replied to your comment. Community Feed: {DisplayName B} has replied to your comment.	Comment owner (User A)
		B, C reply on A’s comment	User Feed: {DisplayName C} and {DisplayName B} have replied to your comment. Community Feed: {DisplayName C} and {DisplayName B} have replied to your comment.	Comment owner (User A)
		B, C, D, E reply on A’s comment	User Feed: {DisplayName E}, {DisplayName D} and 2 others have replied to your comment. Community Feed: {DisplayName E}, {DisplayName D} and 2 others have replied to your comment.	Comment owner (User A)
Reaction	reaction/mentreact	B react on A’s post/comment	User Feed: {DisplayName B} added a reaction to your post/comment Community Feed: {DisplayName B} added a reaction to your post/comment in {CommunityName}	Post/Comment owner (User A)
		B,C react on A’s post/comment	User Feed: {DisplayName C} and {DisplayName B} added reactions to your post/comment Community Feed: {DisplayName C} and {DisplayName B} added reactions to your post/comment in {CommunityName}	Post/Comment owner (User A)
		B,C,D,E react on A’s post/comment	User Feed: {DisplayName E}, {DisplayName D} and {2} others added reactions to your post/comment Community Feed:{DisplayName E}, {DisplayName D} and {2} others added reactions to your post/comment in {CommunityName}	Post/Comment owner (User A)
*Mention	mention	A mentioned B on A post/comment in a community	{DisplayName A} has mentioned you on a post/comment in {CommunityName}	User B
		A mentioned B on A post/comment in a user feed	{DisplayName A} has mentioned you on a post/comment in {DisplayName A} feed	User B

Last Read & Has Read

The notification tray supports 2 reading levels as follows:

1. Last Read: Update the last read timestamp of the user. This is used to update the total unread count of notification records.

2. Has Read: Flag on each individual notification record that shows whether the user has explicitly read or click the notification record. This is represented as hasRead value inside each notification record JSON and can be used to display 'unread dot' on each notification record on Notification Tray.

Get the total unread count of notifications in the user's notification tray.

get

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringRequired

Responses

200

Notification Total Unread Count

application/json

get

/notifications/v3

HTTPcURLJavaScriptPython

GET /notifications/v3 HTTP/1.1
Host: beta.amity.services{basePath}
Authorization: text
Accept: */*

200

Notification Total Unread Count

{
  "data": [
    {
      "totalUnreadCount": 999
    }
  ]
}

Retrieve notification records of a user

get

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

startAfterintegerOptional

timeStamp of last record of previous page.

Default: 1

Header parameters

AuthorizationstringRequired

Responses

200

Notification history JSON

application/json

get

/notifications/v3/history

HTTPcURLJavaScriptPython

GET /notifications/v3/history HTTP/1.1
Host: beta.amity.services{basePath}
Authorization: text
Accept: */*

200

Notification history JSON

{
  "totalPages": 2,
  "nextPage": 1692248943383,
  "data": [
    {
      "description": "John Doe, Sara Janes and 10 others posted in Summer Collection community",
      "verb": "post",
      "tarid": "634678647e482b00d99e9fe3",
      "targetType": "community",
      "imageUrl": "http://www.example.com/image.jpg",
      "hasRead": false,
      "lastUpdate": 1655708345606,
      "actors": [
        {
          "name": "John Doe"
        },
        {
          "name": "Sara Janes"
        }
      ]
    }
  ]
}

Update lastRead timestamp of the user

post

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringRequired

Responses

200

Request has succeeded

application/json

post

/notifications/v2/last-read

HTTPcURLJavaScriptPython

POST /notifications/v2/last-read HTTP/1.1
Host: beta.amity.services{basePath}
Authorization: text
Accept: */*

200

Request has succeeded

{
  "data": [
    {
      "message": "Request has succeeded."
    }
  ]
}

Mark a notification record as read

post

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringRequired

Body

application/json

verbstring · enumOptionalPossible values:

targetIdstringOptional

Responses

200

Request has succeeded

application/json

post

/notifications/v2/read

HTTPcURLJavaScriptPython

POST /notifications/v2/read HTTP/1.1
Host: beta.amity.services{basePath}
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "verb": "post",
  "targetId": "text"
}

200

Request has succeeded

{
  "data": [
    {
      "message": "Request has succeeded."
    }
  ]
}

Mark all the records as read.

get

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringRequired

Responses

200

Marked all the records as read

application/json

get

/notifications/v3/mark-all-as-read

HTTPcURLJavaScriptPython

GET /notifications/v3/mark-all-as-read HTTP/1.1
Host: beta.amity.services{basePath}
Authorization: text
Accept: */*

200

Marked all the records as read

{
  "data": [
    {
      "message": "Success"
    }
  ]
}

Limitations

• When a user changes their display name, the actor's name in Tray Message is not updated.

• Notification Tray currently does not support

  • Post on user feed

  • Grouping mention into one record

• Customization of description is not supported. If customization / localization of notification records is needed we recommend constructing the message at the frontend as notification records already contain all the information needed.

Are you still on version 2?

Don't worry, Version 2 can still be used, but it won't support the mention feature. So, we highly recommend migrating to v3, and here is the list of changes needed to use Version 3!

Breaking Change	Version 2	Version 3
Pagination	?page=1	?startAfter=1692248943383
Response data	{ "totalPages": 2, "data": [ . . . ] }	{ "totalPages": 2, "data": [ . . . ], "nextPage": 1692248943383 }