For AI agents: this page in Markdown: https://www.pubnub.com/docs/sdks/javascript/api-reference/message-persistence.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Message Persistence API for JavaScript SDK

The PubNub JavaScript SDK reads, deletes, and counts the messages that Message Persistence stores, with fetchMessages(), deleteMessages(), and messageCounts(). Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default.

Each method returns a promise that resolves with the response and rejects with a PubNubError. The error carries a status object with category and statusCode, and status.errorData holds the details that PubNub returned for a failed request. Each method also takes a callback as the second argument, and with a callback the method returns nothing and PubNub calls it with (status, response). On success, status.error is false and status.operation names the operation, and on failure status.error is true and response is null. All examples use async/await, so wrap a call in try...catch to receive the error status.

The methods take channel ID strings, not SDK channel entities.

Message Persistence gives you real-time access to the history of messages published to PubNub. Each message is timestamped to the nearest 10 nanoseconds and stored across multiple availability zones in several geographic locations. You can encrypt stored messages with AES-256 so they are not readable on PubNub’s network. For details, see Message Persistence.

You control how long messages are stored through your account’s retention policy. Options include: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

  • Messages
  • Message reactions
  • Files (using the File Sharing API)

Fetch history​

fetchMessages() returns the messages that Message Persistence stores for one or more channels, using a PubNub client for JavaScript.

The start and end timetokens control which messages the call returns and in what order.

  • If you specify only start, the call returns messages older than that timetoken, because start is the newer, exclusive boundary of the query.
  • If you specify only end, the call returns messages with a timetoken equal to or newer than end, because end is the older, inclusive boundary of the query.
How to use the start and end parameters

PubNub retrieves messages by searching backward through time (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:

  • start is the newer boundary (higher timetoken value) - search begins here, exclusive
  • end is the older boundary (lower timetoken value) - search stops here, inclusive

When you provide both parameters, start must be a higher timetoken than end.

9:00 AM10:00 AM11:00 AM11:59 AM

Results are always returned in oldest-first order.

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.If more messages match the time range, call again and set start to the timetoken of the oldest message in the previous response.
required
channels required#
Type: string[]
Default: no default
IDs of the channels to fetch messages from, up to 500 channels. With includeMessageActions set to true, pass one channel only. With more than one channel, the call rejects with a PubNubError whose status.message says that history can return actions data for a single channel only.
start#
Type: string
Default: no default
Timetoken that sets the newer boundary of the query (exclusive). Retrieval begins at this timetoken and moves backward in time. With end, start must be a higher timetoken than end.
end#
Type: string
Default: no default
Timetoken that sets the older boundary of the query (inclusive). Retrieval stops at this timetoken. With start, end must be a lower timetoken than start.
count#
Type: number
Default: no default
Number of messages to return for each channel. The default is 100 for one channel, and 25 for several channels or with includeMessageActions set to true. The SDK lowers a larger value to that default.
includeMessageType#
Type: boolean
Default: true
Whether each returned message includes its PubNub message type in the messageType property.
includeCustomMessageType#
Type: boolean
Default: no default
Whether each returned message includes the custom message type that its publisher set, in the customMessageType property. A message carries it only when the publisher set one. For the background, see Message Persistence.
includeUUID#
Type: boolean
Default: true
Whether each returned message includes the User ID of its publisher in the uuid property.
includeMeta#
Type: boolean
Default: false
Whether each returned message includes the metadata that its publisher set at publish time, in the meta property.
includeMessageActions#
Type: boolean
Default: false
Whether the response includes the message actions of each message, which limits the call to one channel and 25 messages. With more than one channel, the call rejects with a PubNubError whose status.message says that history can return actions data for a single channel only.

Retrieve a message from a channel:

Returns​

fetchMessages() resolves with channels, an object that maps each channel ID to an array of messages. With a callback, status.operation is PNFetchMessagesOperation. Each message has these properties:

channel#
Type: string
ID of the channel that holds the message.
timetoken#
Type: string
Timetoken that PubNub assigned to the message.
message#
Type: any
Decrypted message payload.
messageType#
Type: number
PubNub message type, -1 for a regular message and 4 for a file message. Present with includeMessageType.
customMessageType#
Type: string
Custom message type that the publisher set. Present only when the publisher set one.
uuid#
Type: string
User ID of the publisher. Present with includeUUID.
meta#
Type: any
Metadata that the publisher set at publish time. Present only when the message has metadata.
actions#
Type: object
Message actions on the message, grouped by action type and then by action value. Present with includeMessageActions when the message has actions.
error#
Type: string
Decryption error. Present only when the SDK fails to decrypt the message, and message then holds the undecrypted payload.

With includeMessageActions set to true, a response that PubNub truncates also has a more property. PubNub truncates when the returned messages hold more than 25000 message actions in total. To fetch the remaining messages, call fetchMessages() again with more.start as start and more.max as count.

The more property holds url, start, and max.

Syntax

1pubnub.fetchMessages({
2    channels: string[],
3    start?: string,
4    end?: string,
5    count?: number,
6    includeMessageType?: boolean,
7    includeCustomMessageType?: boolean,
8    includeUUID?: boolean,
9    includeMeta?: boolean,
10    includeMessageActions?: boolean
11}): Promise<FetchMessagesResponse>;

Delete messages from history​

deleteMessages() deletes stored messages from channel history, optionally within a time range, using a PubNub client for JavaScript.

Delete-From-History must be enabled for the keyset in the Admin Portal before a delete call succeeds. The JavaScript SDK also needs a secretKey in its configuration, and only the Node.js build signs requests with it. See Server operations.

The start timetoken is always the exclusive boundary and the end timetoken is always the inclusive boundary. The call deletes the message at end but not the message at start, whichever of the two values is larger. For the full walkthrough, see Delete messages from history.

required
channel required#
Type: string
Default: no default
ID of the channel to delete messages from. The method takes the ID string, not an SDK channel entity.
start#
Type: string
Default: no default
Timetoken that sets the exclusive boundary of the range to delete. The call keeps the message at this timetoken.
end#
Type: string
Default: no default
Timetoken that sets the inclusive boundary of the range to delete. The call deletes the message at this timetoken.

Returns​

deleteMessages() resolves with an empty object, {}. With a callback, status.operation is PNDeleteMessagesOperation.

Syntax

1pubnub.deleteMessages({
2    channel: string,
3    start?: string,
4    end?: string
5}): Promise<DeleteMessagesResponse>;

Message counts​

messageCounts() returns the number of messages published to one or more channels since a timetoken, using a PubNub client for JavaScript.

The count includes every message with a timetoken greater than or equal to the timetoken you pass for the channel.On a keyset with Unlimited retention, messageCounts considers only messages published in the last 30 days.
required
channels required#
Type: string[]
Default: no default
IDs of the channels to count messages in.
channelTimetokens required#
Type: string[]
Default: no default
Timetokens from which to count messages, listed in the same order as channels. A single timetoken applies to all channels. Any other list must hold one timetoken per channel. If the number of channels and timetokens differ and more than one timetoken is given, the call rejects with a PubNubError whose status.message says that the lengths do not match.

Returns​

messageCounts() resolves with channels, an object that maps each channel ID to its message count. A channel without messages has a count of 0. A channel with 10,000 messages or more has a count of 10000. With a callback, status.operation is PNMessageCountsOperation.

Syntax

1pubnub.messageCounts({
2    channels: string[],
3    channelTimetokens: string[]
4}): Promise<MessageCountResponse>;

Deprecated history method​

history() is a deprecated method of the PubNub JavaScript SDK that fetches the messages of one channel, and fetchMessages() replaces it.

The reference for apps that still call history() or read the deprecated data property of actions is Message Persistence API: deprecated history() method and actions data property for JavaScript SDK. New apps use Fetch history and read actions.

Was this page useful?

Last updated on