What's Happening: Read Status Sample

This sample illustrates how browser based custom clients can use the Webex Javascript SDK's functions and events to discover and update the read status for the spaces that a user is a member of. Specifically it illustrates the use of the following functions:

Function Returns Purpose
rooms.listWithReadStatus() A list of spaces that the user is a member of.
Each space includes a lastSeenDate and a lastActivityDate 		Determine which spaces have unread messages in them.
rooms.getWithReadStatus()
An object with the lastSeenDate and a lastActivityDate for a specific space. 		Determine if a single, previously unfetched, space has unread messages in itls.
memberships.listWithReadStatus()
A list of members in a space.
Each member includes a lastSeenID and lastSeenDate. 		Determine which members are "caught up" or "behind" in a space.
memberships.updateLastSeen()
An updated membership object.
The lastSeenId will match the message object that was passed to it. 		Update the lastSeendId and lastSeenDate for the custom client's user.

After a valid token is provided and authorized, the application calls the rooms.listWithReadStatus() to get a list of spaces. For users who are in many spaces this API can take a long time to return, so it is initially called by pasing it the optional maxRecent parameter set to 30, in order to update the GUI quickly with 30 spaces with recent activity. It calculates which spaces are have unread messages by comparing the lastSeenDate and the lastActivity date of each space. While processing the first batch it calls rooms.listWithReadStatus() again to get the complete list of rooms. Its worth noting that the maximum number or rooms returned will be 1000 so it is not guaranteed that this function will return ALL the rooms, but clients can always call the rooms.getWithReadStatus(roomId) function anytime they get an event for a previously unseen space.

Once the application has built its cache of spaces the user is a member of, it registers to listen to the following events:

  • messages:created when this event arrives the application updates the "Most recent messages:created event" table, and updates the lastActivityDate of the cached space info. If the message was sent by someone other than the user it updates the "Most Recent Title" in the "Behind" column and calls the memberships.listWithReadStatus() function to update the "Other Member's Read Status" columns. It also enabled the "Mark as Read" button.
  • memberships:seen when this event arrives the application updates the "Most recent memberships:seen (read receipt) event" table. If the event was generated for our user, it might update the status of the space from "Behind" to "Caught Up". If the event is for another member, and the space is currently displayed on the top table, the "Other Member's Read Status" columns will be updated too.
  • memberships:created this event arrives when a new user has been added to a space. If it is our user the application calls the rooms.getWithReadStatus() function to get the details for the space and adds it to the list of "Caught Up" rooms. If the event is for another member, and the space is currently displayed on the top table, the "Other Member's Read Status" columns will be updated too.
  • memberships:deleted this event arrives when a user has been removed from a space. If it is our user the application removes the space from its cache. If it is another user in one of the spaces currently behind displayed, the "Other Member's Read Status" columns will be udpated accordingly.
  • rooms:updated this event may signal a change in the title for a space. If so the space cache and any releveant tables are updated.

See the Webex Webhook Documentation for more information on the payloads of the membership, message and room events. In general the SDK events closely match the payload of the webhooks, except in cases where the information in a traditional webhook envelope doesn't make sense, for example there is no name, targetUrl, or secret field in the SDK event envelopes. The SDK adds one event which is not yet supported in the webhooks. A memberships:seen event is generated when a Webex client sends a "read receipt". The membership:seen event will include a lastSeenId field with the id of the last message read by the user. This can be compared with the lastActivityId field of the space to determine if the member is "caught up".

A few final points. If the "Mark as Read" button is active, and pushed by the user, the application calls membership.updateLastSeen(message) passing the relevant message data to it. This generates a membership:seen event which is handled by our application as well as any Webex clients that the user or other members of the space are using.

As mentioned above the application maintains its own cache of space states which it updates when it receives events. This minimizes the number of calls it needs to make to the Webex Platform and keeps the application GUI response. The application is prepared to handle spaces that are not in its cache by calling rooms.getWithReadStatus() "just in time".

View the source for this app