Files
File Sharing stores binary files uploaded to a channel and delivers a real-time event to subscribers when an upload completes. You enable it on your keyset in the Admin Portal, then upload and download files through the SDK. It is a separate storage system from Message Persistence and App Context, enabled per keyset, and priced independently.
How file delivery works
When a client uploads a file, PubNub stores the file and publishes a file event to all subscribers on that channel. The event carries the file ID, the file name, and a download URL. It also carries any text message attached to the upload and the uploading client's User ID.
File events have message type 4. Subscribers receive them on the same channel listener used for regular messages. No separate subscription is required. For the full event payload, see File events.
A successful upload returns a timetoken, the same 17-digit value PubNub assigns to published messages. This timetoken identifies the file event in the channel's timeline.
Message Persistence
If Message Persistence is enabled on the keyset, PubNub stores file events alongside regular messages. They appear in history with message type 4 and can be retrieved using the same fetchMessages API used for text messages.
File Sharing and Message Persistence have independent retention settings. If your app links file uploads to messages on the same channel, align the two retention periods. A file event in history that points to a file already deleted from File Sharing storage creates a broken reference.
Configuration
Enable File Sharing for your keyset in the Admin Portal. The two settings that govern storage behavior are:
Bucket region. PubNub stores all files for a keyset in one geographic region. You choose the region when you enable the feature. The region cannot be changed after saving. Plan your data-residency requirements before enabling.
Retention. How long PubNub keeps uploaded files before deleting them. The available options and limits are:
| Function | Limit | Notes |
|---|---|---|
| File size | 5 MB | To raise it, contact support@pubnub.com. |
| File retention | File retention is 1 or 7 days on the Free plan, 30 days on Starter, and Unlimited on Pro. | Set it per keyset in the Admin Portal. |
| Files per list call | A single list-files call returns up to 100 files for a channel. |
Retention applies to the file itself. The file event in Message Persistence history follows the Message Persistence retention setting for that keyset, not the File Sharing retention setting.
Encryption
PubNub encrypts files with AES-256 when a cipher key is set. Set a cipher key in the SDK client configuration to encrypt all files automatically, or pass a cipher key per request to encrypt individual uploads. Any client that downloads the file must use the same key. For where the key lives and what happens without it, refer to Encryption.
Access Manager
When Access Manager is enabled on your keyset, file operations require channel-level permissions:
| Operation | Required permission |
|---|---|
| Upload a file | write |
| List or download files | read |
| Delete a file | delete |
These use the same channel permissions as messaging. A token that grants write on a channel authorizes both message publishing and file uploads on that channel.