Unread messages

Track unread message counts for users who reconnect after being offline.

lastReadMessageTimetoken on the Membership object stores when a user last read messages on a channel. This is set automatically on Join() or Invite(). Update it based on user actions (scrolling, app focus, etc.) using mark as read methods.

Requires App Context and Message Persistence

Enable App Context and Message Persistence in the Admin Portal.

Get last read message

GetLastReadMessageTimeToken() returns the timetoken marking the user's last read position on a channel. This timetoken doesn't always correspond to an actual message. Use it to display unread markers in your UI.

Method signature

This method has the following signature:

1membership.GetLastReadMessageTimeToken()

Input

This method doesn't take any parameters.

Output

Type	Description
string	Retrieved timetoken marking the user's last read position on a given channel.

Sample code

Get the timetoken of the last message read by the support_agent_15 user on the support channel.

1

Get unread messages count (one channel)

GetUnreadMessagesCount() returns the number of messages you didn't read on a given channel.

This includes all messages published after your last read timetoken, including messages sent by yourself and all other channel members. The method cannot filter messages by sender - it counts all unread messages regardless of who published them. You can display this number on UI in the channel list of your chat app.

Method signature

This method has the following signature:

1membership.GetUnreadMessagesCount()

Input

This method doesn't take any parameters.

Output

Type	Description
Task<int>	Retrieves from Message Persistence the number of all messages unread by a given user on a given channel from the last read message.

Sample code

Get the number of all messages unread by the support_agent_15 user on the support channel.

1

Get unread messages count (all channels)

GetUnreadMessagesCounts() returns info on all messages you didn't read on joined channels that have unread messages.

This method only returns channels with unread message counts greater than 0 - channels with zero unread messages are filtered out. For each returned channel, this includes all messages published after your last read timetoken, including messages sent by yourself and all other channel members. The method cannot filter messages by sender - it counts all unread messages regardless of who published them. You can display this number on UI in the channel list of your chat app.

Unread counts and filtering

GetUnreadMessagesCounts uses the Memberships API. Filters here may target channel.* fields only (plus common fields: status, type, custom). You can't use uuid.* fields.

Unread counts always include all messages published after your last read timetoken including messages you sent yourself. You can't filter unread counts by sender but you can query Message Persistence from the last read timetoken and filter client-side.

See filterable fields: • Memberships filters • Members filters

Method signature

This method has the following signature:

1chat.GetUnreadMessagesCounts(
2    string filter = "",
3    string sort = "",
4    int limit = 0,
5    PNPageObject page = null
6)

Input

* required

Parameter	Description
filter Type: string (Memberships filter) Default: empty string	Filter expression evaluated against channel memberships only. Allowed targets: channel.* plus common fields (status, type, custom). uuid.* fields aren't supported.
sort Type: string Default: empty string	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 Type: number Default: 0	Number of objects to return in response.
page Type: PNPageObject Default: null	Object used for pagination to define which previous or next result page you want to fetch.

Output

Type	Description
Task<List<UnreadMessageWrapper>>	An awaitable Task with a list of UnreadMessageWrapper objects containing the filtered, sorted, and paginated unread message counts.

Sample code

Get the number of all messages unread by the current user.

1

To avoid counting your own recently sent messages as unread, ensure your app updates the last read timetoken.

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.

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()

  1membership.SetLastReadMessage(Message message)

• SetLastReadMessageTimeToken()

  1membership.SetLastReadMessageTimeToken(string timeToken)

Input

Parameter	Required by SetLastReadMessage()	Required by SetLastReadMessageTimeToken()	Description
message Type: Message Default: n/a	Yes	No	Last read message on a given channel with the timestamp that gets added as the lastReadMessageTimetoken property to the Membership object.
timeToken Type: string Default: n/a	No	Yes	Timetoken of the last read message on a given channel that gets added as the lastReadMessageTimetoken property to the Membership object.

Output

An awaitable Task.

Sample code

Set the message with the 16200000000000001 timetoken as the last read message for the support_agent_15 user on the support channel.

• SetLastReadMessage()

  1
  

• SetLastReadMessageTimeToken()

  1
  

Mark messages as read (all channels)

MarkAllMessagesAsRead() lets you mark as read all messages you didn't read on all joined channels.

Method signature

This method has the following signature:

1chat.MarkAllMessagesAsRead(
2    string filter = "",
3    string sort = "",
4    int limit = 0,
5    PNPageObject page = null
6)

Input

* required

Parameter	Description
filter Type: string Default: empty string	Expression used to filter the results. Returns only these unread messages whose properties satisfy the given expression. The filter language is defined here.
sort Type: string Default: empty string	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 Type: number Default: 0	Number of objects to return in response.
page Type: PNPageObject Default: null	Object used for pagination to define which previous or next result page you want to fetch.

Output

Type	Description
Task<MarkMessagesAsReadWrapper>	An awaitable Task with a wrapper object containing the filtered, sorted, and paginated list of user memberships.

Sample code

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.

1