1. Overview
  2. APIs returning initial Unread Count
  3. Mark Messages as Read
  4. Unread Messages Count Related Events
  5. Sync Message Count

1. Overview

Requirements:

Spaces uses the FCM push-data technology to push updates about messages to client-apps. Therefore, Users should allow Push Messaging on their browser or mobile app, as well as enabling notification option per individual spaces.


Track Unread Messages Count

An application utilizing Spaces Unread Messages Count, should keep the followings in consideration:

2. APIs returning initial Unread Count

The following APIs would return properties needed for app to display and track unread counts per space.

APIs

Unread Count related Props

PropertyDescription
unreadMessagesCountunread messages count for the Viewer (Me)
messagesLastReadTimelast read time of messages by the Viewer (Me)

Mark Messages as Read

As soon as application detects that the user has read/viewed the new messages in a space, the application should mark those messages as read by calling the following API.

POST /api/users/me/spaces/:spaceId/markread

Note 1: For performance purposes, Spaces has lower throttling rules around this API,
so apps should be cautious on how often they call this api.

Note 2: To reduce traffic to server, the app should call this API 5 seconds after without the readTime upon the first message read. So any subsequent messages received until the delayed time to call markread api would be considered as read.

POST https://spacesapis.avayacloud.com/api/users/me/spaces/:spaceId/markread

4. Unread Messages Count Related Events

Event categories to increment unread count

Task, Post and Chat event catagories are considered valid events to increment the count

Note: App should ignore any events received with created timestamp before messagesLastReadTime


Reduce unread count

Application would decrement the unread count when receiving message deleted events "app.event.message.removed" with created time after messagesLastReadTime.

Note: App should ignore all delete events received before messagesLastReadTime

{
    ...
    "topicId": "5a2ec9521a77bf29fd92e255",
    "category": "app.event.message.removed",
    "created": "2019-10-30T12:34:50.239Z",
    ...
}
                

Note: The above events are sent via both socket and push-data. So, applications should consider one source to update counts.

i.e. Spaces web-app would ignore push-events and use socket events instead when subscribing socket to specific space.


Socket Event

Upon success of markread api a socket event is sent to all user's app instances, so all instances would reset their virtual Unread Messages Count.

{
  category: "topic.markread"
  content: {
    messagesLastReadTime: "2019-11-01T16:47:39.528Z", 
    unreadMessagesCount: 0
    }
  topicId: ":spaceId"
}

5. Sync Message Count

App should sync its current state with Spaces back-end whenever detecting anomalies like getting disconnected from network.

Calling the following API with filtertype=unread would return all spaces with unread messages.

GET https://spacesapis.avayacloud.com/api/users/me/spaces?topictype=group&filtertype=unread&size=20