---
source_url: https://www.pubnub.com/docs/data-storage/message-history/import-legacy-messages
title: Import legacy messages into Message Persistence
updated_at: 2026-10-27T09:13:26.000Z
---

# Import legacy messages into Message Persistence

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

Move messages from your legacy data store into [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md) with a batch process. The process publishes each message with a publish timetoken override (`ptto`), so PubNub stores the message under the timetoken you set instead of the time of the import.

## Before you start

Confirm you have:

* **Message Persistence enabled.** Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default.
* **A long enough retention period.** A `ptto` value can't be older than the keyset's retention period. An import usually needs Unlimited retention, so the imported history doesn't expire. 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.
* **ptto enabled on the keyset.** Contact [PubNub Support](mailto:support@pubnub.com) with your subscribe key and ask them to enable publish timetoken override.
* **The secret key, if Access Manager is enabled.** A batch process that uses the secret key has access to all channels without granting permissions first. The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications.

## Convert each timestamp to a timetoken

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. To get a timetoken, multiply a Unix timestamp in seconds by 10,000,000. A PubNub timetoken exceeds the largest integer a JavaScript `Number` represents exactly, so increment or compare timetokens with an arbitrary-precision integer type such as `BigInt` rather than with plain numeric arithmetic.

## Publish each message with its timetoken

The SDK API references don't document a `ptto` parameter, so call the [REST publish API](https://www.pubnub.com/docs/sdks/rest-api/publish-message-to-channel.md) directly:

```text
https://ps.pndsn.com/publish/{pub_key}/{sub_key}/0/{channel}/0/{message}?uuid={user_id}&ptto={timetoken}&norep=1
```

| Parameter | Value |
| --- | --- |
| `ptto` | The 17-digit timetoken PubNub stores the message under. |
| `norep` | Turns off replication of the message across points of presence. |
| `uuid` | The User ID of the batch process. |

If Access Manager is enabled, sign each request with the secret key. Refer to [Signature Generation in Access Manager](https://www.pubnub.com/docs/sdks/rest-api/access-manager-introduction.md).

## Check an imported message

Fetch one message by its timetoken. `end` is the oldest timetoken to include, and `start` is exclusive, so set `start` to the timetoken plus 1 to get only that message:

```text
https://ps.pndsn.com/v3/history/sub-key/{sub_key}/channel/{channel}?uuid={user_id}&max=1&start={timetoken_plus_1}&end={timetoken}&include_meta=true
```

The timetoken is the message's key in the channel. A successful publish returns the timetoken that retrieves the message.

If Access Manager is enabled, sign this request with the secret key too, or add an `auth` parameter with a token that grants `read` permission on the channel.

## Related pages

* [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md). What gets stored, how timetokens order storage, and retention.
* [Retrieve message history](https://www.pubnub.com/docs/data-storage/message-history/retrieve-message-history.md). Fetch stored messages with an SDK.
* [Delete messages from history](https://www.pubnub.com/docs/data-storage/message-history/delete-messages-from-history.md). Remove messages by time range or by timetoken.

Last updated at: 2026-10-27T09:13:26.000Z