---
source_url: https://www.pubnub.com/docs/data-storage/message-history/overview
title: Message Persistence
updated_at: 2026-09-30T07:20:08.000Z
---

# Message Persistence

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

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](https://www.pubnub.com/docs/architecture/core-concepts.md#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](https://www.pubnub.com/docs/data-storage/metadata/overview.md) 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](https://www.pubnub.com/docs/architecture/core-concepts.md#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](https://www.pubnub.com/docs/architecture/data-transport-and-delivery.md).

## 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](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) 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](https://www.pubnub.com/docs/integrations/event-forwarding/overview.md) 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](https://www.pubnub.com/docs/pub-sub/message-actions/overview.md) 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](https://www.pubnub.com/docs/data-storage/message-history/retrieve-message-history.md).

Last updated at: 2026-09-30T07:20:08.000Z