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.

GEThttps://beta.amity.services{basePath}/notifications/v3

Header parameters

Response

200

Notification Total Unread Count

Body

application/json

dataobject

Request

JavaScriptCurlPython

const response = await fetch('https://beta.amity.services{basePath}/notifications/v3', {
    method: 'GET',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

200

{
  "data": {
    "totalUnreadCount": 0
  }
}

Retrieve notification records of a user

GEThttps://beta.amity.services{basePath}/notifications/v3/history

Query parameters

Header parameters

Response

200

Notification history JSON

Body

application/json

totalPagesinteger

Show how many pages user have.

nextPageinteger

Show the next page timestamp.

dataarray of NotificationRecord (object)

Request

JavaScriptCurlPython

const response = await fetch('https://beta.amity.services{basePath}/notifications/v3/history', {
    method: 'GET',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

200

{
  "totalPages": 0,
  "nextPage": 0,
  "data": [
    {
      "v_tarid_uid": "text",
      "description": "text",
      "verb": "post",
      "imageUrl": "text",
      "avatarCustomUrl": "text",
      "targetType": "community",
      "targetName": "text",
      "hasRead": false,
      "lastUpdate": 0,
      "actors": {
        "name": "text"
      },
      "actorsCount": 0,
      "parentTargetId": "text",
      "targetId": "text",
      "lastActionId": "text",
      "lastActionSegmentNo": 0
    }
  ]
}

Update lastRead timestamp of the user

POSThttps://beta.amity.services{basePath}/notifications/v2/last-read

Header parameters

Response

200

Request has succeeded

Body

application/json

datastring

Request has succeeded.

Request

JavaScriptCurlPython

const response = await fetch('https://beta.amity.services{basePath}/notifications/v2/last-read', {
    method: 'POST',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

200

{
  "data": "text"
}

Mark a notification record as read

POSThttps://beta.amity.services{basePath}/notifications/v2/read

Header parameters

Body

application/json

verbNotificationVerb (enum)

postcommentreactionmentreply

targetIdstring

Response

200

Request has succeeded

Body

application/json

datastring

Request has succeeded.

Request

JavaScriptCurlPython

const response = await fetch('https://beta.amity.services{basePath}/notifications/v2/read', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "data": "text"
}

Mark all the records as read.

GEThttps://beta.amity.services{basePath}/notifications/v3/mark-all-as-read

Header parameters

Response

200

Marked all the records as read

Body

application/json

dataobject

Request

JavaScriptCurlPython

const response = await fetch('https://beta.amity.services{basePath}/notifications/v3/mark-all-as-read', {
    method: 'GET',
    headers: {
      "Authorization": "text"
    },
});
const data = await response.json();

Response

200

{
  "data": {
    "message": "text"
  }
}

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 }