Notification Tray

Notification Tray service is designed to automatically create and group Notification Records into Notification Tray that is separated by user. The main function of this service is to serve notification history for each user.

Here's an example of a simple notification tray that we customized using this service:

Here's an example of a simple notification tray that we customized:

As can be seen from the picture, a Notification Tray contains Notification History that is represented in rows of Notification Record. A Notification Record contains detail of the notification - mainly list of people (actors) who performed the action, the action (verb) and the target of the action (target).

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.

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, Notification Tray shows up to 10 Notification Records per page sorted from the latest one to the oldest one by using the last updated date as the reference. All Notification Records are stored for 90 days from last time the records are updated.
Each Notification Record will show up to 3 actors' names sorted by the date of activity on the record.
Each Notification Record cuts off every 10 days from its creation time. If a new event happens after 10 days from the matching Notification Record's creation date, the record won’t be updated and a new record is created instead. If there is a removal event such as comment deletion relating to the old record, the record is also not updated.
Avatar image of a Notification Record is the profile image of the latest actor who acts on the target.
Notification Record expires after 90 days from its lastUpdate timestamp and is deleted from Notification Tray after expiring.
If a user leaves a community, Notification Records of the user with target related to the community won’t be updated. If the user rejoin a community, Notification Records will starts updating again, however events that happens during the time user left the community is not retrospectively updated into the record.

Event Types

The following table shows event that is supported by Notification Tray:

Event Type	Detail
Create Post	Occurs when someone adds a new post on a community. Only people in the community can get this event.
Delete Post	Occurs when someone deletes a post on an community. Only people in the community can get this event.
Create Comment	Occurs when someone adds comment on a post. Only the post owner can get this event.
Delete Comment	Occurs when someone deletes comment on a a post. Only the post owner can get this event.
Add Reaction to a Post	Occurs when someone do a like on a post. Only the post owner can get this event.
Remove Reaction from a Post	Occurs when someone undo a like on a post. Only the post owner can get this event.

Event Type

Detail

Create Post

Occurs when someone adds a new post on a community. Only people in the community can get this event.

Delete Post

Occurs when someone deletes a post on an community. Only people in the community can get this event.

Create Comment

Occurs when someone adds comment on a post. Only the post owner can get this event.

Delete Comment

Occurs when someone deletes comment on a a post. Only the post owner can get this event.

Add Reaction to a Post

Occurs when someone do a like on a post. Only the post owner can get this event.

Remove Reaction from a Post

Occurs when someone undo a like on a post. Only the post owner can get this event.

Scenarios

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

Target Type	Scenario	Tray Message	Notification Target
Post	User A create post on community	{DisplayName A} posted in {CommunityName}	Community's members
	User A,B create post on community	{DisplayName B} and {DisplayName A} created post in {CommunityName}	Community's members
	User A,B,C create post on community	{DisplayName C}, {DisplayName B} and {DisplayName A} posted in {CommunityName}	Community's members
	User A,B,C,D create post on community	{DisplayName D}, {DisplayName C} and {2} others posted in {CommunityName}	Community's members
Comment	User 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 comment on A’s post	User Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} commented on your post Community Feed: {DisplayName D}, {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)
Reaction (like only)	B react on A’s post	User Feed: {DisplayName B} likes your post Community Feed: {DisplayName B} likes your post in {CommunityName}	Post owner (User A)
	B,C react on A’s post	User Feed: {DisplayName C} and {DisplayName B} like your post Community Feed: {DisplayName C} and {DisplayName B} like your post in {CommunityName}	Post owner (User A)
	B,C,D react on A’s post	User Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} like your post Community Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} like your post in {CommunityName}	Post owner (User A)
	B,C,D,E react on A’s post	User Feed: {DisplayName E}, {DisplayName D} and {2} others like your post Community Feed:{DisplayName E}, {DisplayName D} and {2} others like your post in {CommunityName}	Post owner (User A)

Target Type

Scenario

Tray Message

Notification Target

Post

User A create post on community

{DisplayName A} posted in {CommunityName}

Community's members

User A,B create post on community

{DisplayName B} and {DisplayName A} created post in {CommunityName}

Community's members

User A,B,C create post on community

{DisplayName C}, {DisplayName B} and {DisplayName A} posted in {CommunityName}

Community's members

User A,B,C,D create post on community

{DisplayName D}, {DisplayName C} and {2} others posted in {CommunityName}

Community's members

Comment

User 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 comment on A’s post

User Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} commented on your post Community Feed: {DisplayName D}, {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)

Reaction (like only)

B react on A’s post

User Feed: {DisplayName B} likes your post Community Feed: {DisplayName B} likes your post in {CommunityName}

Post owner (User A)

B,C react on A’s post

User Feed: {DisplayName C} and {DisplayName B} like your post Community Feed: {DisplayName C} and {DisplayName B} like your post in {CommunityName}

Post owner (User A)

B,C,D react on A’s post

User Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} like your post Community Feed: {DisplayName D}, {DisplayName C} and {DisplayName B} like your post in {CommunityName}

Post owner (User A)

B,C,D,E react on A’s post

User Feed: {DisplayName E}, {DisplayName D} and {2} others like your post Community Feed:{DisplayName E}, {DisplayName D} and {2} others like your post in {CommunityName}

Post owner (User A)

Last Read & Has Read

Notification Tray supports 2 level of reading as followed:

Last Read: Update last read timestamp of the user. This is useful if you want to check whether there's any new notification record that's created or updated after the user has read. This is represented as lastRead value inside API response and can be used to display as red dot on notification icon or to provide highlight on new items
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.

API Reference

Retrieve Notification History of a user

GET https://beta.amity.services/notifications/history

Rate Limit: 5 requests / second

Query Parameters

Name Type Description

Name	Type	Description
searchAfter	Integer	Timestamp to search records from. If presented, records returned from the request is guaranteed to have `lastUpdated` timestamp less than the value. For pagination you can pass in `lastRecordDate` value from previous request.

searchAfter

Integer

Timestamp to search records from. If presented, records returned from the request is guaranteed to have lastUpdated timestamp less than the value.

For pagination you can pass in lastRecordDate value from previous request.

Headers

Name	Type	Description
Authorization*	String	Bearer {accessToken} accessToken is retrieved from Amity SDK

Name

Type

Description

Authorization*

String

Bearer {accessToken}

accessToken is retrieved from Amity SDK

{
  // Array object containing all notification records sort by 'lastUpdate' date in descending order
  "data": [
    {
      // Tray Message of the record.
      "description": "John Doe, Sara Janes and 10 others posted in Summer Collection community",
      // Network ID of the record
      "networkId": "629678647d472b00d99e9fe3",
      // Public ID of the owner of the record
      "userId": "userA",
      // Verb of the notification record: [post, comment, like]
      "verb": "post",
      // ID of the target
      "targetId": "634678647e482b00d99e9fe3",
      // Unique group ID of the notification record
      "targetGroup": "1660634491595",
      // Type of the target: [community, post]
      "targetType": "community",
      // Avatar image of the record, which is the profile image of the latest actor who performed action on this record.
      // If the latest actor doesn't have any profile picture
      "imageUrl": "http://www.example.com/image.jpg",
      // Flag indicating whether the user has read the record
      "hasRead": false,
      // Timestamp of when the record is last updated
      "lastUpdate": 1655708345606,
      // Latest actors (up to 3 actors) who performed the verb on the target.
      "actors": [
        {
          "name": "John Doe", // Name of the user
          "id": "user_john_doe" // Public ID of the user
        },
        {
          "name": "Sara Janes",
          "id": "user_sara_janes"
        }
      ]
    }
  ],
  // Timestamp that can be used in searchAfter query parameter to search for next page
  // lastRecordDate will be null if the response is the last page of the notification records.
  "lastRecordDate": 1655708345606,
  "lastRead": {
    "ch_uid": "629678647d472b00d99e9fe3_71189", // unique ID of the notification tray
    "lastReadDate": 1654071194890 // Timestamp when the user has last mark the tray as read.
  }
}

Update Last Read Timestamp of a user

POST https://beta.amity.services/notifications/last-read

Headers

Name	Type	Description
Authorization*	String	Bearer {accessToken} accessToken is retrieved from Amity SDK

Name

Type

Description

Authorization*

String

Bearer {accessToken}

accessToken is retrieved from Amity SDK

Mark a Notification Record as Read

POST https://beta.amity.services/notifications/read

Headers

Name	Type	Description
Authorization*	String	Bearer {accessToken} accessToken is retrieved from Amity SDK

Name

Type

Description

Authorization*

String

Bearer {accessToken}

accessToken is retrieved from Amity SDK

Request Body

Name	Type	Description
verb*	String	Verb of the notification record
targetId*	String	Target ID of the notification record
targetGroup*	String	Target Group of the notification record

Name

Type

Description

verb*

String

Verb of the notification record

targetId*

String

Target ID of the notification record

targetGroup*

String

Target Group of the notification record

Limitations

If a user changes his/her display name, actor name in Tray Message is not updated. If you need the latest name when rendering Notification Tray we recommend using the record's user ID to get the latest user display name via the SDK.
Notification Tray currently does not support
- Post on user feed
- Reply comment
- Reaction on comment
Only "like" reaction name is supported at this time. Reactions with other name is ignored by Notification Tray.
Custom Avatar URL is not supported. If an actor is one with customAvatarUrl , his/her customAvatarUrl is not updated to imageUrl of the Notification 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.

PreviousWebhook Events NextMigration Guides

Last updated 1 year ago