Message Persistence

Message Persistence stores published messages on the PubNub network so your app can retrieve them later. You enable it once on your keyset in the Admin Portal. After that, your app reads stored messages through the SDK using fetchMessages or the equivalent. PubNub indexes each stored message by the same timetoken used in live delivery, so history and the live stream share one ordered timeline per channel.

What gets stored

Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default. It applies to every channel on that keyset. PubNub stores a message when:

• Message Persistence is enabled on the keyset, and
• the publish call does not set storeInHistory (or shouldStore) to false

Not every event type is stored.

Message type	Description	Stored
0	Regular message	Yes
1	Signal	No
2	App Context event	No
3	Message Action event	Yes
4	File message	Yes

PubNub never stores signals in Message Persistence, regardless of keyset settings. Each stored message records the publishing client's User ID, so your app can attribute history to individual users or filter by publisher.

Timetokens and the storage model

PubNub assigns every published message a server-side timetoken: a monotonically increasing 17-digit value precise to 100 nanoseconds (10⁻⁷ s), the number of 100-nanosecond intervals since the Unix epoch. Because the assignment happens on the server, messages on a channel have a consistent order in storage regardless of which client published them.

The timetoken PubNub returns in the publish response is the retrieval key for that message. Your app uses timetokens to:

• fetch a specific message by its exact position in the timeline
• page backward through a channel by passing start and end boundaries to the history API
• resume after a disconnect by replaying history from the last timetoken the client received

A subscriber that reconnects and replays history from its last timetoken gets exactly the messages it missed, in the same order live subscribers received them. For how the subscriber buffer and gap recovery work below the storage layer, see Data transport and delivery.

Retention

Message Persistence retention is 1 or 7 days on the Free plan, 30 days, 3 months, or 6 months on Starter, and 1 year or Unlimited on Pro. Testing keysets default to 7-day retention.

Changing a keyset's retention period applies to future messages only, and messages already in storage keep the period they were stored under. New messages use the updated period.

A per-message TTL set at publish time is fixed once the message is stored. A keyset using Unlimited retention ignores any per-message TTL and stores the message indefinitely.

Storage strategy

PubNub Message Persistence is not the only option. Three approaches fit different architectures:

Approach	When to use it
Store in PubNub	You want built-in history, message counts, and message actions without running your own storage infrastructure.
Store externally	You have an existing data store, need custom querying, or run analytics pipelines that pull from other systems. Use Events & Actions to forward messages to external targets.
Store in both	You want PubNub history for real-time retrieval and also forward messages to an external system for analytics or long-term archiving.

Events & Actions is the no-code path for forwarding published messages to external targets such as webhooks, Amazon SQS, Amazon Kinesis, or S3. You configure it from the Admin Portal without writing code.

Message actions

Message actions are stored as message type 3, separately from the messages they annotate. PubNub stores them regardless of whether the original message is stored, as long as Message Persistence is enabled on the keyset.

You can fetch a message and its actions together in one call, or retrieve only the actions. For how to do either, see Retrieve message history.