Message Persistence API for JavaScript SDK
Message Persistence provides real-time access to the history of all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds and is stored across multiple availability zones in several geographical locations. Stored messages can be encrypted with AES-256 message encryption, ensuring that they are not readable while stored on PubNub's network. For more information, refer to Message Persistence.
Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.
You can retrieve the following:
- Messages
- Message reactions
- File Sharing (using File Sharing API)
Supported and recommended asynchronous patterns
PubNub supports Callbacks, Promises, and Async/Await for asynchronous JS operations. The recommended pattern is Async/Await and all sample requests in this document are based on it. This pattern returns a status only on detecting an error. To receive the status errors, you must use the try...catch
syntax in your code.
Fetch History
Requires Message Persistence
This method requires that Message Persistence is enabled for your key in the Admin Portal.
This function fetches historical messages from one or multiple channels. The includeMessageActions
flag also allows you to fetch message actions along with the messages.
It's possible to control how messages are returned and in what order.
- if you specify only the
start
parameter (withoutend
), you will receive messages that are older than thestart
timetoken - if you specify only the
end
parameter (withoutstart
), you will receive messages from thatend
timetoken and newer - if you specify values for both
start
andend
parameters, you will retrieve messages between those timetokens (inclusive of theend
value)
You will receive a maximum of 100 messages for a single channel or 25 messages for multiple channels (up to 500). If more messages meet the timetoken criteria, make iterative calls while adjusting the start
timetoken to fetch the entire list of messages from Message Persistence.
Method(s)
To run Fetch History
, you can use the following method(s) in the JavaScript SDK:
pubnub.fetchMessages({
channels: Array<string>,
count: number,
includeMessageType: boolean,
includeCustomMessageType: boolean,
includeUUID: boolean,
includeMeta: boolean,
includeMessageActions: boolean,
start: string,
end: string
})
Parameter | Description |
---|---|
channels *Type: Array <string> Default: n/a | Specifies channels to return history messages from. Maximum of 500 channels are allowed. |
count Type: number Default: 100 or 25 | Specifies the number of historical messages to return per channel. Default is 100 per single channel and 25 per multiple channels or per single channel if includeMessageActions is used. |
includeMessageType Type: boolean Default: true | Pass true to receive the message type with each history message. |
includeCustomMessageType Type: Boolean Default: n/a | Indicates whether to retrieve messages with the custom message type. For more information, refer to Retrieving Messages. |
includeUUID Type: boolean Default: true | Pass true to receive the publisher uuid with each history message. |
includeMeta Type: boolean Default: n/a | Whether message meta information should be fetched or not. |
includeMessageActions Type: boolean Default: n/a | Whether message-added message actions should be fetched or not. If used, the limit of messages retrieved will be 25 per single channel. Throws an exception if API is called with more than one channel . Truncation will happen if the number of actions on the messages returned is > 25000. Each message can have a maximum of 25000 actions attached to it. Consider the example of querying for 10 messages. The first five messages have 5000 actions attached to each of them. The API will return the first 5 messages and all their 25000 actions. The response will also include a more link to get the remaining 5 messages. |
start Type: string Default: n/a | Timetoken delimiting the start of time slice (exclusive) to pull messages from. |
end Type: string Default: n/a | Timetoken delimiting the end of time slice (inclusive) to pull messages from. |
Truncated response
If you fetch messages with messages actions, the number of messages in the response may be truncated when internal limits are hit. If the response is truncated, a more
property will be returned with additional parameters. Send iterative calls to history adjusting the parameters to fetch more messages.
Basic Usage
Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
Retrieve a message from a channel:
Response
//Example of status
{
error: false,
operation: 'PNFetchMessagesOperation',
statusCode: 200
}
//Example of response
{
"channels":{
"my-channel":[
{
"message":"message_1",
"timetoken":"15483367794816642",
"uuid":"my-uuid",
show all 23 lines