Unread messages
The Unread Message Count feature shows users how many messages they missed while offline. Once they reconnect or log into the app again, they can get the number of messages published in a given channel while they were gone.
Chat SDK stores info about the timetoken of the last message the current user read on a given channel on the lastReadMessageTimetoken property. lastReadMessageTimetoken is available on the custom parameter of the Membership object.
This property is automatically set for a user when they first join (join()) a given channel or are invited to it (invite() and inviteMultiple()). For all further updates of this property, you must decide what user actions will trigger methods that mark messages as read in your chat app - whether that's some user interaction on UI, like scrolling, your app going offline, or any other behavior.
Requires App Context and Message Persistence
To store message timetokens on the user-channel membership relationship at PubNub, you must enable App Context and Message Persistence for your app's keyset in the Admin Portal.
Get last read message
You can use a getter method to check what is the timetoken of the last message a user read on a given channel. lastReadMessageTimetoken returns the last read message timetoken stored in the membership data between the channel and the current user. Use it to display markers on the message list denoting which messages haven't been read by the user yet.
Method signature
This method has the following signature:
membership.lastReadMessageTimetoken: string
Properties
| Property | Type | Description |
|---|---|---|
lastReadMessageTimetoken | string | Value of the returned timetoken. |
Basic usage
Get the timetoken of the last message read by the support_agent_15 user on the support channel.
// reference the "support_agent_15" user
const user = await chat.getUser("support_agent_15")
// get the list of all user memberships and filter out the right channel
const membership = await user.getMemberships({
filter: "channel.id == 'support'"
})
//
membership.lastReadMessageTimetoken
Get unread messages count (one channel)
getUnreadMessagesCount() returns the number of messages you didn't read on a given channel. You can display this number on UI in the channel list of your chat app.
Under the hood
Method signature
This method has the following signature:
membership.getUnreadMessagesCount(): Promise<number | false>
Input
This method doesn't take any parameters.
Output
| Type | Description |
|---|---|
Promise<number> or Promise<false> | Retrieves from Message Persistence the number of all messages unread by a given user on a given channel from the last read message. The method returns false when there is no last read message timetoken set on the Message object. |
Basic usage
Get the number of all messages unread by the support_agent_15 user on the support channel.
// reference the "support_agent_15" user
const user = await chat.getUser("support_agent_15")
// get the list of all user memberships and filter out the right channel
const membership = await user.getMemberships({
filter: "channel.id == 'support'"
})
// get the number of unread messages
await membership.getUnreadMessagesCount()
Get unread messages count (all channels)
getUnreadMessagesCounts() returns info on all messages you didn't read on all joined channels. You can display this number on UI in the channel list of your chat app.
Under the hood
Method signature
This method has the following signature:
chat.getUnreadMessagesCounts({
filter?: string,
sort?: object,
limit?: number,
page?: {
next?: string,
prev?: string
}
}): Promise<{
channel: Channel,
membership: Membership,
count: number
}[]>
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | string | No | n/a | Expression used to filter the results. Returns only these unread messages whose properties satisfy the given expression. The filtering language is defined here. |
sort | object | No | n/a | Key-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"}. By default, the items are sorted by the last updated date. |
limit | number | No | 100 | Number of objects to return in response. The default (and maximum) value is 100. |
page | object | No | n/a | Object used for pagination to define which previous or next result page you want to fetch. |
→ next | string | No | n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. |
→ prev | string | No | n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied. |
Output
| Parameter | Type | Description |
|---|---|---|
Promise<> | object | Returned object containing these fields: channel, membership, and count. The method returns an array of such objects corresponding to all channel memberships. |
→ channel | Channel | Channel with unread messages. |
→ membership | Membership | Returned Membership object showing the user-channel data. |
→ count | number | Total number of messages unread by the current user on a given channel. |
Basic usage
Get the number of all messages unread by the support_agent_15 user on all joined channels.
// reference the "support_agent_15" user
const user = await chat.getUser("support_agent_15")
// get all messages unread by that user
await chat.getUnreadMessagesCounts()
Mark messages as read (one channel)
setLastReadMessage() and setLastReadMessageTimetoken() let you set the timetoken of the last read message on a given channel to set a timeline from which you can count unread messages. You choose on your own which user action it is bound to.
Under the hood
Setting the last read message for users lets you implement the Read Receipts feature and monitor which channel member read which message.
Method signature
These methods take the following parameters:
-
setLastReadMessage()membership.setLastReadMessage(
message: Message
): Promise<Membership> -
setLastReadMessageTimetoken()membership.setLastReadMessageTimetoken(
timetoken: string
): Promise<Membership>
Input
| Parameter | Type | Required by setLastReadMessage() | Required by setLastReadMessageTimetoken() | Default | Description |
|---|---|---|---|---|---|
message | Message | Yes | No | n/a | Last read message on a given channel with the timestamp that gets added to the user-channel membership as the custom parameter called lastReadMessageTimetoken. |
timetoken | string | No | Yes | n/a | Timetoken of the last read message on a given channel that gets added to the user-channel membership as the custom parameter called lastReadMessageTimetoken. |
Output
| Type | Description |
|---|---|
Promise<Membership> | Returned Membership object updated with the lastReadMessageTimetoken custom parameter. |
Basic usage
Set the message with the 16200000000000001 timetoken as the last read message for the support_agent_15 user on the support channel.
-
setLastReadMessage()
show all 16 lines// reference the "support_agent_15" user
const user = await chat.getUser("support_agent_15")
// get the list of all user memberships and filter out the right channel
const membership = await user.getMemberships({
filter: "channel.id == 'support'"
})
// reference the "support" channel
const channel = await chat.getChannel("support")
// return the message object with the "16200000000000001" timetoken
const message = await channel.getMessage("16200000000000001")
// assuming a single membership which matches the filter -
setLastReadMessageTimetoken()
show all 16 lines// reference the "support_agent_15" user
const user = await chat.getUser("support_agent_15")
// get the list of all user memberships and filter out the right channel
const membership = await user.getMemberships({
filter: "channel.id == 'support'"
})
// reference the "support" channel
const channel = await chat.getChannel("support")
// return the message object with the "16200000000000001" timetoken
const message = await channel.getMessage("16200000000000001")
// assuming a single membership which matches the filter
Mark messages as read (all channels)
markAllMessagesAsRead() lets you mark as read all messages you didn't read on all joined channels.
Under the hood
Method signature
This method has the following signature:
chat.markAllMessagesAsRead({
filter?: string,
sort?: object,
limit?: number,
page?: {
next?: string,
prev?: string
}
}): Promise<{
page: {
next: string,
prev: string
},
total: number,
status: number,
Input
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | string | No | n/a | Expression used to filter the results. Returns only these messages whose properties satisfy the given expression. The filtering language is defined here. |
sort | object | No | n/a | Key-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"}. By default, the items are sorted by the last updated date. |
limit | number | No | 100 | Number of objects to return in response. The default (and maximum) value is 100. |
page | object | No | n/a | Object used for pagination to define which previous or next result page you want to fetch. |
→ next | string | No | n/a | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. |
→ prev | string | No | n/a | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied. |
Output
| Parameter | Type | Description |
|---|---|---|
Promise<> | object | Returned object containing these fields: page, total, status, and memberships. |
→ page | object | Object used for pagination to define which previous or next result page you want to fetch. |
→ next | string | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. |
→ prev | string | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied. |
→ total | number | Total number of messages marked as read. |
→ status | number | Status code of a server response, like 200. |
→ memberships | Membership[] | List of all related memberships. |
Basic usage
Mark the total number of 50 messages as read and specify you want to fetch the results from the next page using a string that was previously returned from the PubNub server.
await chat.markAllMessagesAsRead(
{
limit: 50,
page: {
next: "<returned_random_string>"
}
}
)