File Sharing

In addition to messages and signals, PubNub also allows users to send files.

The most common scenarios where you may need to share files are in social apps to share images or in medical apps to share medical records. You can send videos, images, or documents of up to 5 MB in size each.

Configuration​

Enable and configure File Sharing for your app's keyset in the Admin Portal.

Public Admin Portal demo

Want to browse through the Admin Portal without creating an account? Explore it through the Public Demo that shows examples of most PubNub features for transport and logistics use case.

By default, Admin Portal prompts you to enable File Sharing on every newly created keyset (unless you select Choose later for Region during keyset creation).

Testing keysets default to the US East region and 7 days retention, which determines how long files remain in storage before deletion.

File Sharing settings in Admin Portal: bucket region and retention controls

OptionDescription
Bucket Region
Geographical region where your files are stored and managed.

Align the file retention period with your Message Persistence settings. This stores messages and files for the same duration.
Retention
How long you'd like to save your files for. For free accounts, you can set it to 1 day or 7 days. Limits are higher for paid accounts.

Send files​

Sending a file is similar to publishing a message: specify the channel and provide the file. Optionally include a text caption.

You can also encrypt files using AES-256 Encryption (see Data Security). To send encrypted files, define a cipher key in your initial client configuration or pass a cipher key per request. Downloading clients must provide the same key to decrypt the file content.

The code below sends the file cat_picture.jpg of the custom type file-message on the channel my_channel.

Custom message types

Not all SDKs support sending messages with a custom message type. For details, see Message Types.

// web
const input = document.querySelector('input[file]');

input.addEventListener('change', async () => {
  const file = input.files[0];

  const result = await pubnub.sendFile({
    channel: 'my_channel',
    file: file,
    customMessageType: 'file-message'
  });
});

// Node.js
import fs from 'fs';
show all 36 lines

Even though the client sends files, the storage service stores and manages the actual files for each key.

After the file is uploaded to the storage service, subscribers to the channel receive a file message. The file message includes a description, filename, and file ID. Use SDK methods to generate a URL to display the file or download it. Refer to Retrieve Files for details.

Enable the feature

File Sharing is an optional feature that you must enable by turning on the feature for your keys in the Admin Portal.

File operations​

Beyond sending files, you can list files sent to a channel or delete previously uploaded files. If you enabled Message Persistence on your keyset, you can also search historical file messages using the Message Persistence API. The returned information allows you to display files in the browser or download them.

Refer to the File Sharing section in the SDK documentation to learn more about operations on files.

Receive files​

To receive a file, the client must listen to an event of type file, and subscribe to the channel where the file is sent. No special subscription is required.

Retrieve files​

Retrieving files is a two-step process using the Message Persistence API and File Sharing-related SDK methods. To retrieve a file:

  1. Get the file message using the Message Persistence API or the listFiles method.
  2. Display or download the file using dedicated SDK methods based on the obtained file information.
File URLs

Neither the Message Persistence API nor the listFiles method returns file URLs. They return file-specific information like the file's name and ID that you need to display or download the file.

When you fetch file messages using the Message Persistence API, the response includes the file details (ID and filename) and a message type of 4, which indicates a file message. You can use this information to display or download the file.

Display and download files​

Apart from the optional description, a file message contains the ID and name of the file.

As a file message does not contain the file URL, you must use one of the available SDK methods to construct the file URL to either display the file or download it.

The following code returns the URL of the cat_picture.jpg file sent to channel my_channel:

const result = pubnub.getFileUrl({ channel: 'my_channel', id: 'd9515cb7-48a7-41a4-9284-f4bf331bc770', name: 'cat_picture.jpg' });

The response to this call is the file URL which you can use to display the file in the browser.

You need the same set of file information to download the file. The following code downloads the file cat_picture.jpg sent to the channel my_channel:

// web
const file = await pubnub.downloadFile({
  channel: 'my_channel',
  id: '...',
  name: 'cat_picture.jpg',
});

const myImageTag = document.createElement('img');
myImageTag.src = URL.createObjectURL(await file.toFile());

document.body.appendChild(myImageTag);

// Node.js using streams
import fs from 'fs'

show all 38 lines

List files​

If you're only interested in the actual files and not the file messages (which include the optional description of the uploaded file) that were sent, you can list up to 100 files sent to a particular channel. However, if there are more than 100 files to be returned, the more flag will be present in the response.

The code below returns the name, ID, size, and created timestamp for up to 100 files sent to the channel my_channel:

const result = await pubnub.listFiles({ channel: 'my_channel' });
Last updated on
Related Resources
On this page