Message Persistence API: deprecated history() method and actions data property for JavaScript SDK

DeprecatedMessage Persistence is a current API. The history() method and the data property of actions are deprecated. New apps should use fetchMessages() and read actions. Go to Message Persistence

This page documents the deprecated pubnub.history() method and the deprecated data property of actions in fetchMessages() responses in the PubNub JavaScript SDK. Message Persistence is a current API, and only these two are deprecated. They remain for apps that already use them. New apps call fetchMessages() and read actions.

History (deprecated)

Deprecated

history() is deprecated in the JavaScript SDK. Use fetchMessages() instead.

Requires Message Persistence add-on

This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.

history() fetches the messages of one channel. You can control how it returns messages and in what order:

• By default, the search starts at the newest end of the timeline, which is reverse set to false.
• To search from the oldest end of the timeline, set reverse to true.
• To page through results, provide start or end.
• To retrieve a slice of the timeline, provide both start and end.
• To limit the number of messages, use count.

Method(s)

1pubnub.history({
2    channel: string,
3    reverse?: boolean,
4    count?: number,
5    stringifiedTimeToken?: boolean,
6    includeMeta?: boolean,
7    start?: string,
8    end?: string
9}): Promise<GetHistoryResponse>;

* required

channel* required#

type: Type: string

Default: no default

ID of the channel to return history messages from.

reverse#

type: Type: boolean

default: Default: false

Whether to traverse the timeline from the oldest message to the newest. If you provide both start and end, history() ignores reverse and returns the messages starting with the newest one.

count#

type: Type: number

default: Default: 100

Number of messages to return. The maximum is 100, and history() lowers a larger value to 100.

stringifiedTimeToken#

type: Type: boolean

default: Default: false

Whether to return timetokens as strings.

includeMeta#

type: Type: boolean

default: Default: false

Whether to include the meta object, if the publisher set one at publish time, in each message of the response.

start#

type: 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: 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.

history() always returns the messages sorted from the oldest to the newest, whatever reverse is. The reverse setting matters when more than 100 messages, or more than count if you set it, fall in the time interval. In that case, reverse decides which end of the interval the retrieval starts from.

Sample code

Retrieve the last 100 messages on a channel:

1

Returns

history() resolves with an object that has these properties. With a callback, status.operation is PNHistoryOperation.

messages#

type: Type: array

The returned messages. Each item has entry, timetoken, and, when present, meta and error.

startTimeToken#

type: Type: string or number

Timetoken of the start of the returned timeline.

endTimeToken#

type: Type: string or number

Timetoken of the end of the returned timeline.

In each item of messages, entry holds the decrypted message payload and timetoken holds the message timetoken. The meta property is present only when the publisher set metadata. The error property is present only when the SDK fails to decrypt the message.

1{
2    endTimeToken: "14867650866860159",
3    messages: [
4        {
5            timetoken: "14867650866860159",
6            entry: "[User 636] hello World"
7        },
8        {...},
9        {...},
10        {...}
11    ],
12    startTimeToken: "14867650866860159"
13}

Other examples

Retrieve the three oldest messages

Set reverse to true to traverse the timeline from the oldest message first.

1

Retrieve messages newer than a timetoken

Page from the oldest message to the newest, starting at a single point in time (exclusive).

1

Retrieve messages until a timetoken

Page from the newest message to the oldest, until a specific point in time (inclusive).

1

Page through all messages

Call the function with no argument or with a valid timetoken.

1

Fetch messages with metadata

1

Call history with promises

1

Deprecated data property of actions

Deprecated

The data property of actions is deprecated. Read actions instead.

fetchMessages() returns message actions on each message in actions, grouped by action type and then by action value. The response has them only with includeMessageActions and when the message has actions. The deprecated data property holds the same value as actions.

data#

type: Type: object

Holds the same value as actions.

Replacement

actions

See Fetch history for the full response.