Data storage FAQ
16 questions on this page
Short answers to common questions about Message Persistence, File Sharing, and DataSync.
Does PubNub store messages?
No, not by default. Message Persistence is an optional feature that stores published messages for the retention period set on your keyset. 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.
To read stored messages, fetch them from Message Persistence. PubNub Chat stores messages through Message Persistence too.
PubNub will enter into a Business Associate Agreement (BAA) with eligible customers upon request. Customers remain responsible for their own HIPAA obligations and appropriate service configuration.
To keep message content private, encrypt messages in the SDK with a cipher key. With a CryptoModule configured, the SDK encrypts message and file payloads on the device. The cipher key never leaves the client, so PubNub can't decrypt those payloads. Metadata stays readable to PubNub: the meta field, channel names, user IDs, custom message types, presence state, App Context, message actions, and in most SDKs signals. For setup, see Encryption, which encrypts payloads on the client.
How do I turn on Message Persistence and File Sharing?
Turn them on for your keyset in the Admin Portal. Both are keyset-level switches on the keyset overview page, so every client that uses the keyset gets them. See Enable the features your app calls.
- Message Persistence. Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default. You also set the retention period on the keyset. 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.
- File Sharing. It stores files in one region, which you choose when you enable it. You can't change the region after you save it.
How do I import my existing data into PubNub storage?
Publish each old message with a publish timetoken override (ptto), and PubNub stores it under the timetoken you set instead of the time of the import. You need three things first:
pttoenabled on the keyset. Ask PubNub Support to enable it.* Message Persistence enabled on the keyset.- A retention period at least as long as the age of your oldest message, because a
pttovalue can't be older than the retention period. An import usually needs Unlimited retention.
See Import legacy messages for the steps.
Can I choose where PubNub stores my data?
Yes. By default, PubNub stores messages globally. You can ask PubNub Support to store your messages in a specific region.
DataSync and File Sharing each store data in one region, which you choose when you enable the feature in the Admin Portal. You can't change that region after you save it.
To store all of your messages and files in one region, contact Support and choose a data center in the EU, the US, or APAC. For File Sharing in the US, you can also choose East or West.
This setting:
- Applies to your existing and future keysets.
- Overrides the File Sharing region set on a keyset.
- Doesn't change the DataSync region, which you set when you enable DataSync on a keyset. For DataSync in the US, you can choose East or West.
For the region and retention of each storage system, see Storage, region, and retention by system.
Can I store messages for only some channels?
No. Message Persistence is enabled per keyset, so it stores messages on every channel of that keyset.
To skip storing one message, set the store parameter of the publish call to false. In the JavaScript SDK, the parameter is storeInHistory. For the name in your SDK, see its API reference.
Are stored messages replicated across regions?
Yes, unless you lock your message history to a region. PubNub replicates stored messages across its regions for availability. A region-locked history stays only in the region you choose.
Can I fetch history from several channels in one call?
Yes. A single history call returns up to 100 messages for one channel, or up to 25 messages per channel across as many as 500 channels.
In the JavaScript SDK, use fetchMessages. It returns messages published before the start timetoken, up to and including the end timetoken. See Retrieve message history, which covers fetching by channel and time range.
How many stored messages can one history call return?
A single history call returns up to 100 messages for one channel, or up to 25 messages per channel across as many as 500 channels.
To read more, page backward. Pass the timetoken of the oldest message in the current page as start in the next call, and repeat until a response returns fewer messages than you asked for. How far back you can go depends on your keyset's retention period. See Page through long history.
In what order does PubNub return stored messages?
Oldest first, whatever parameters you pass. The start, end, and reverse parameters change which messages you get, not their order. See Fetch a time range.
How do I use start, end, and count when I fetch history?
start is the newer boundary and excludes the message at that timetoken. end is the older boundary and includes the message at that timetoken. When you pass both, start must be a higher timetoken than end.
- With only
start, you get messages older than it. - With only
end, you get messages newer than or equal to it. countsets how many messages each channel returns. A single history call returns up to 100 messages for one channel, or up to 25 messages per channel across as many as 500 channels.
Messages come back oldest first. See Fetch a time range.
Can I hide a message without deleting it from storage?
Yes. Add a message action to the message, for example with the type deleted, and hide messages with that action in your app. The message stays in Message Persistence.
Subscribed clients receive the message action as an event, so they can mark the message as deleted.
To remove a message for good, delete it from history. That deletion is permanent.
Can I delete messages permanently?
Yes. Delete messages from Message Persistence with the delete messages call. The deletion is permanent, and nothing can recover the messages afterward. Before you call it:
- Turn on Enable Delete-From-History for the keyset in the Admin Portal.
- Initialize the client with your secret key, in server-side code only.
- If Access Manager is on, use a token that grants
deleteon the channel.
The call deletes the message at end but not the message at start, even when you pass the two values in either order. See Delete messages from history.
Can I use PubNub to share files?
Yes. File Sharing sends images, videos, and documents up to the file size limit. Enable it on your keyset in the Admin Portal first.
Sending a file works like publishing a message. You choose the channel and the file, and you can add a text caption.
To receive files, a client subscribes to the channel and adds a listener for file events.
How do I retrieve files from storage?
Get the file's details from a file message in Message Persistence, or list the channel's files. Then use the SDK's file methods to get the download URL and download the file. See Receive and download files and List and manage stored files.
Can I upload several files at once?
No. File Sharing uploads one file at a time. To upload several files, queue them and send each one separately. See Send a file to a channel.
Why does a DataSync request return a 404 error?
A DataSync request returns a 404 in two cases:
DS-0100: the entity, class, or relationship you addressed doesn't exist. Create it before you get, replace, update, or delete it.DS-0600: the subscribe key is unknown or has no DataSync region configured. Check that you saved a region when you enabled DataSync.
See DataSync error codes.