Message Persistence

Message Persistence allows you to store all messages as they're published. The primary use case is to allow a device to retrieve messages that were published while that device was offline, but there are many other use cases as well. You can configure message retention for several different limited periods or for unlimited time.

Network interruptions

Brief network interruptions are handled by the automatic reconnection mechanism. Refer to Connection Management for more information.

When a message is published, it's stored using the channel name and the message's publish timetoken which you can use to retrieve, delete or annotate.

You can retrieve the following:

Message Retention

To retain a message, you'll need to enable Message Persistence for the given API Key in the Admin Portal. You may also want to configure the duration of the retention, whether you want to enable Delete-From-History and whether you want to retain Presence Events. Once configured, Message Persistence is enabled for all the channels that belong to the API Key.

Immutable message retention

Once a message is stored, you can't change its retention. Changes to Message Persistence retention only apply to messages published after the change has been made.

Retrieve Messages

Retrieving messages from Message Persistence is accomplished using the Message Persistence API. You can retrieve up to 100 messages for a single channel or 25 messages for multiple channels (up to 500) in a single request.

The Message Persistence API returns regular messages, file messages, and message actions. The value of the returned messageType parameter indicates the type of a particular message.

Message TypeDescriptionSaved in Message Persistence
0Regular messageYes
2App Context eventNo
3Message Reactions eventYes
4File messageYes
Retrieving message actions

You can retrieve messages and their associated message actions or you can just retrieve the message actions only. Refer to Retrieve Actions for more information.

You can provide start and end timetokens to get messages from a specific time range. Most use cases require retrieving only the most recent messages since a given timetoken (missed messages since last online). For this, you need only provide the end parameter with a timetoken of the last received message. The following example will retrieve the last 25 (default/max) messages on the two channels.

channels: ["chats.room1", "chats.room2"],
end: '15343325004275466',
count: 25 // default/max is 25 messages for multiple channels (up to 500)
function(status, response) {
console.log(status, response);

If more than 25 messages are needed, you can use the timetokens of the returned message to go further back in time to retrieve more messages. In other words, you can page through a channel's timeline recursively until you all the messages you require.

Parameters UsedBehavior
startRetrieves messages before the start timetoken, excluding any message at that timetoken
endRetrieves messages after the end timetoken, including any message at that timetoken
start & endRetrieves messages between the start and end timetokens, excluding any message at the start timetoken and including any message at the end timetoken

Filtering retrieved messages

There is currently no built-in search functionality in the Message Persistence API that would allow you to fetch only messages filtered by keywords. To filter the content of the messages, you must first retrieve them from Message Persistence and then filter them by keywords on the local client.

Alternatively, you can implement a self-hosted server and use the After Publish Function to automatically send all messages to your own database and filter them on the server side.

For more information or assistance, contact support.

Delete messages from history

Message Persistence allows you to delete messages from history. You can delete a number of messages that were published between two points in time or you can delete a specific message.

Deleting messages from history is only allowed for SDK clients that have been initialized with the secret key. Each SDK provides a different method of removing messages from storage. Consult the SDK documentation for reference.

For more information on how to initialize PubNub with secret key, refer to Application Configuration.

Receive Messages and Signals

When a message, or signal is received by the client, it triggers a message or signal event, respectively. Refer to Receive Messages to learn how to act upon these events.

How Messages are Fetched

The following details explain how messages are retrieved from Message Persistence based on the start and end parameters.

Scenario 1

Scenario 1 retrieves messages starting with the message stored before the start timetoken parameter value and continues until it has 25 messages or hits that oldest message (whichever comes first).

startvalue provided
endvalue not provided
Channel Timeline
oldest-message --------------- start-timetoken --------------- newest-message
[ <--------]

Scenario 2

startvalue not provided
endvalue provided
Channel Timeline
oldest-message --------------- end-timetoken --------------- newest-message
[ <---------------------]

Scenario 3

startvalue provided
endvalue provided
Channel Timeline
oldest-message ----- end-timetoken ----------------- start-timetoken ----- newest-message
[ <----------------------]

Get Message Counts

The Message Count API returns the number of messages sent after a given point in time. You can specify up to 100 channels in a single call.

Rather than retrieving lots of messages from hundreds of channels, you can get the number of missed messages and retrieve the messages later. For example, you can display the unread message count on channels that the client hasn't visited yet and retrieve those messages when the client actually visits the channel.

The Message Count API returns the number of messages sent for each channel greater than or equal to the provided timetoken. You can not specify a time range because it's only intended to give the number of messages since a given timetoken. Optionally, you can specify a different timetoken per channel or one timetoken to be applied to all channels.

Unlimited message retention

For keys with unlimited message retention enabled, this method considers only messages published in the last 30 days.

channels: ["chats.room1", "chats.room2"],
channelTimetokens: ['15518041524300251']
}).then((response) => {
}).catch((error) => {
// handle error
Last updated on