Retrieve message history

Showing JavaScript examples.

This guide shows you how to retrieve stored messages from PubNub channels using Message Persistence. It covers fetching missed messages, scoping requests to a time range, paging through histories longer than a single call, and counting unread messages without fetching them.

The examples on this page are written for the current SDK releases: C# 9.0.0, Dart 8.0.3, Java 6.4.5, JavaScript 13.0.3, Kotlin 13.4.4, Objective-C 7.0.4, Python 10.7.2, and Swift 10.2.0. Each example assumes a PubNub client initialized for its SDK, unless the example sets one up itself.

Prerequisite: Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default. Turn it on in the Admin Portal. If read access is restricted by Access Manager, your token must grant read on the channels you're querying.

For how Message Persistence works, see Message Persistence.

Fetch missed messages

The most common use case is catching up on messages published while your client was offline. Pass the timetoken of the last message your client received as the end parameter. A single history call returns up to 100 messages for one channel, or up to 25 messages per channel across as many as 500 channels.

• JavaScript
• Swift
• Objective-C
• Java
• C#
• Python
• Kotlin
• Dart

1pubnub.fetchMessages(
2  {
3    channels: ["chats_guilds.mages_guild"],
4    end: '15343325004275466',
5    count: 100
6  },
7  function(status, response) {
8    console.log(status, response);
9  }
10);

To avoid re-fetching the last message your client already received, pass lastReceivedTimetoken + 1 as end. A PubNub timetoken exceeds the largest integer a JavaScript Number represents exactly, so increment or compare timetokens with an arbitrary-precision integer type such as BigInt rather than with plain numeric arithmetic.

Fetch a time range

To retrieve messages between two points in time, pass both start and end to fetchMessages. The start parameter sets the newer boundary (exclusive) and must be a higher timetoken than end. The end parameter sets the older boundary (inclusive).

Parameter	Boundary	Inclusive?	Timetoken value
start	Newer (more recent)	No	Higher
end	Older (less recent)	Yes	Lower

Results return in oldest-first order regardless of the parameters you pass. For the exact parameter names and method signatures in your SDK, see your SDK reference.

Page through long history

To retrieve more messages than one call returns, use the timetokens returned in the response to page backward. Pass the timetoken of the oldest message in the current page as the start value in the next call. Continue until the response returns fewer messages than the requested count, which indicates you have reached the oldest available message.

How far back you can page depends on your keyset's configured retention period.

Count unread messages

To show an unread badge without fetching message content, use messageCounts. Pass the timetoken of the last message your client received. PubNub returns the number of messages published on or after that timetoken for each channel.

A single messageCounts call covers up to 100 channels. You can pass one timetoken that applies to all channels, or a different timetoken per channel.

Unlimited retention keysets

On a keyset with Unlimited retention, messageCounts considers only messages published in the last 30 days.

• JavaScript
• Swift
• Objective-C
• Java
• C#
• Python

1pubnub.messageCounts({
2    channels: ["chats.room1", "chats.room2"],
3    channelTimetokens: ['15518041524300251']
4    }).then((response) => {
5    console.log(response)
6    }).catch((error) => {
7    // handle error
8  }
9);

Filter by message type

Message Persistence does not support server-side content filtering. To show only certain message types, fetch the messages and filter client-side using the messageType (integer) and custom_message_type (string) fields in each response item.

messageType	Content
0	Regular message
3	Message Action event
4	File message

For server-side filtering or full-text search, use an After Publish Function to index messages in your own database at publish time.