Unread messages

Users can have unread messages in a channel because new messages arrived while they were away, or because they explictly marked a message as unread.

Marking a message as unread

You can mark a message as unread from client-side:

await channel.markUnread({ message_id: "<message_id>" });

Or from server-side by providing a user id:

await channel.markUnread({ message_id: "<message_id>", user_id: "<user_id>" });

For performance reasons it’s only possible to mark any of the last 100 messages of the channel as unread.

Marking a channel as read

You can mark all messages in a channel as read like this on the client-side:

channelClient.markRead().enqueue { result ->
  if (result.isSuccess) {
    // Messages in the channel marked as read
  } else {
    // Handle result.error()
  }
}

await channel.markRead();

await channel.markRead();

let channelController = client.channelController(for: .init(type: .messaging, id: "general"))

channelController.markRead()

Channel->MarkRead();

channelClient.markRead().enqueue(result -> {
  if (result.isSuccess()) {
    // Messages in the channel marked as read
  } else {
    // Handle result.error()
  }
});

await message.MarkMessageAsLastReadAsync();

Or from server-side by providing a user id:

await channel.markRead({ user_id: "foo" });

$mark = $channel->markRead('user-id');

Last read message

The last_read_message_id field tells which was the last read message that a given user read in the channel.

When you retrieve a channel from the API (e.g. using query channels), the read state for members is included in the response (up to 100 members, ordered by the most recent added, the current user’s read state is always included).

The read state includes the number of unread messages, the last read message id, and when the user read the channel. An example:

const channel = client.channel("messaging", "test");
await channel.watch();

console.log(channel.state.read["<user id>"]);

{
  last_read: "2024-02-09T12:23:46.361362996Z";
  last_read_message_id: "sara-e9c0d141-b109-4116-baec-e76966ae712e";
  unread_messages: 3;
}

The last read message id is updated in the following events:

message.read
notification.mark_read
notification.mark_unread

const channel = client.channel("messaging", "test");
await channel.watch();

// Any member read the channel
channel.on("message.read", (event) => {
  console.log(event.last_read_message_id);
  // Unread messages: 0
});

// Connected user read the channel
channel.on("notification.message_read", (event) => {
  console.log(event.last_read_message_id);
  // Unread messages: 0
});

// Connected user marked a message as unread
channel.on("notification.message_unread", (event) => {
  console.log(event.last_read_message_id);
  // Unread messages
  console.log(event.unread_messages);
});

Jump to last read message

This is how you can jump to the last read message inside a given channel:

const channel = client.channel("messaging", "test");
await channel.watch();

const lastReadMessageId = channel.state.read["<user id>"];
await channel.state.loadMessageIntoState(lastReadMessageId);

console.log(channel.state.messages);

Control read state exposure

Please take in account that user’s read state exposure can be controlled by user privacy settings:

// user object with privacy settings where read receipts are disabled
{
  // other user fields
  "privacy_settings": {
    "read_receipts": {
      "enabled": false
    }
  }
}

If privacy_settings.read_receipts.enabled is set to false, then the read state of this user will not be exposed to others. Additionally, read state related events, such as message.read and notification.mark_read, will not be delivered to others when this user reads messages.

Campaign API

Polls API