File Sharing API for JavaScript SDK

Breaking changes in v9.0.0

PubNub Java SDK version 9.0.0 unifies the codebases for Java and Kotlin SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted status events. These changes can impact applications built with previous versions (< 9.0.0) of the Java SDK.

For more details about what has changed, refer to Java/Kotlin SDK migration guide.

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Send file

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, sendFile internally calls the publishFileMessage method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

Don't JSON serialize

You should not JSON serialize the message and meta parameters when sending signals, messages, or files as the serialization is done automatically. Pass the full object as the message/meta payload and let PubNub take care of everything for you.

Method(s)

pubnub.sendFile()
    .channel(String)
    .fileName(String)
    .inputStream(InputStream)
    .message(Object)
    .shouldStore(Boolean)
    .meta(Object)
    .ttl(Integer)
    .customMessageType(String)

* required

Parameter	Type	Default	Description
`channel` *	String		Channel for the file.
`fileName` *	String		Name of the file to send.
`inputStream` *	InputStream		Input stream with file content.
`message`	Object		Message which should be sent along with file to specified `channel`.
`shouldStore`	Boolean	`true`	Whether PubNub published `file message` should be stored in `channel` history.
`meta`	Object		`Meta` data object which can be used with the filtering ability.
`ttl`	Integer		How long message should be stored in channel's storage.
`customMessageType`	String		A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes `-` and underscores `_` are allowed. The value cannot start with special characters or the string `pn_` or `pn-`. Examples: `text`, `action`, `poll`.

Deprecated parameter

The cipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Basic Usage

pubnub.sendFile()
    .channel("my_channel")
    .fileName("cat_picture.jpg")
    .inputStream(inputStream)
    .cipherKey("my_cipher_key")
    .message("Look at this photo!")
    .customMessageType("file-message")
    .async(result -> {
        result.onSuccess(res -> {
            System.out.println("send timetoken: " + res.getTimetoken());
            System.out.println("send status: " + res.getStatus());
            System.out.println("send fileId: " + res.getFile().getId());
            System.out.println("send fileName: " + res.getFile().getName());
        });
    });

Response

{
  "timetoken": 15957709330808500,
  "status": 200,
  "file": {
      "id": "d9515cb7-48a7-41a4-9284-f4bf331bc770",
      "name": "cat_picture.jpg"
  }
}

Returns

The sendFile() operation returns a PNFileUploadResult which contains the following properties:

Property Name	Type	Description
`timetoken`	Long	A representation of the timetoken when the message was published.
`status`	Integer	Remote call return code.
`file`	PNBaseFile	Uploaded `file` information.

PNBaseFile contains the following properties:

Property Name	Type	Description
`id`	Long	`Id` of the uploaded file.
`name`	String	`Name` of the upload file.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.listFiles()
    .channel(String)
    .limit(Integer)
    .next(String)

* required

Parameter	Type	Default	Description
`channel` *	String		Channel to get list of files.
`limit`	Integer	100	Number of files to return. Minimum value is 1, and maximum is 100.
`next`	String		Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

Basic Usage

pubnub.listFiles()
        .channel("my_channel")
        .async(result -> {
            result.onSuccess(res -> {
                System.out.println("files status: " + res.getStatus());
                System.out.println("files status: " + res.getNext());
                System.out.println("files status: " + res.getCount());
                System.out.println("files status: " + res.getCount());
                for (PNUploadedFile file : res.getData()) {
                    System.out.println("files fileId: " + file.getId());
                    System.out.println("files fileName: " + file.getName());
                    System.out.println("files fileSize: " + file.getSize());
                    System.out.println("files fileCreated: " + file.getCreated());
                }
            });
show all 16 lines

Response

{
  "data":[
      {
      "name":"cat_picture.jpg",
      "id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
      "size":25778,
      "created":"202007 - 26T13:42:06Z"
      }],
   "status": 200
   "totalCount": 1,
   "next": null,
   "prev": null
}

Returns

The listFiles() operation returns a PNListFilesResult which contains the following properties:

Property Name	Type	Description
`timetoken`	Long	A representation of the timetoken when the message was published.
`status`	Integer	Remote call return code.
`next`	String	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
`count`	Integer	Number of files returned.
`data`	List	`List` of channel files.

PNUploadedFile contains the following properties:

Property Name	Type	Description
`id`	Long	`Id` of the uploaded file.
`name`	String	`Name` of the upload file.
`size`	Integer	`Size` of the uploaded file.
`created`	String	Time of creation.

Get File Url

Generate URL which can be used to download file from target Channel.

Method(s)

pubnub.getFileUrl()
    .channel(String)
    .fileName(String)
    .fileId(String)

* required

Parameter	Type	Description
`channel` *	String	Name of `channel` to which the file has been uploaded.
`fileName` *	String	Name under which the uploaded file is stored.
`fileId` *	String	Unique identifier for the file, assigned during upload.

Basic Usage

pubnub.getFileUrl()
        .channel("my_channel")
        .fileName("cat_picture.jpg")
        .fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
        .async(result -> {
            result.onSuccess(res -> {
                System.out.println("getUrl fileUrl: " + res.getUrl());
            });
        });

Response

{
  "url":"http://ps.pndsn.com/v1/files/demo/channels/my_channel/files/d9515cb7-48a7-41a4-9284-f4bf331bc770/cat_picture.jpg?pnsdk=PubNub-Java-Unified/4.32.0&timestamp=1595771548&uuid=pn-9ce9e988-8e04-40bf-90c4-ebe170478f7d"
}

Returns

The getFileUrl() operation returns a PNFileUrlResult which contains the following properties:

Property Name	Type	Description
`url`	String	`URL` to be used to download the requested file.

Download file

Download file from specified Channel.

Method(s)

pubnub.downloadFile()
    .channel(String)
    .fileName(String)
    .fileId(String)

* required

Parameter	Type	Description
`channel` *	String	Name of `channel` to which the file has been uploaded.
`fileName` *	String	Name under which the uploaded file is stored.
`fileId` *	String	Unique identifier for the file, assigned during upload.

Deprecated parameter

Basic Usage

pubnub.downloadFile()
        .channel("my_channel")
        .fileName("cat_picture.jpg")
        .fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
        .cipherKey("my_cipher_key")
        .async(result -> {
            result.onSuccess(res -> {
                System.out.println("downloadFile fileName: " + res.getFileName());
                System.out.println("downloadFile byteStream: " + res.getByteStream());
            });
        });

Response

{
    "fileName": "cat_picture.jpg",
    "byteStream": <file data>
}

Returns

The downloadFile() operation returns a PNDownloadFileResult which contains the following properties:

Property Name	Type	Description
`fileName`	String	Name of the downloaded file.
`byteStream`	InputStream	Input stream containing all bytes of the downloaded file.

Delete file

Delete file from specified Channel.

Method(s)

pubnub.deleteFile()
    .channel(String)
    .fileName(String)
    .fileId(String)

* required

Parameter	Type	Description
`channel` *	String	The `channel` from which to delete the file.
`fileName` *	String	Name of the file to be deleted.
`fileId` *	String	Unique identifier of the file to be deleted.

Basic Usage

pubnub.deleteFile()
        .channel("my_channel")
        .fileName("cat_picture.jpg")
        .fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
        .async(result -> { /* check result */ });

Response

{
    "status": 200
}

Returns

The deleteFile() operation returns a PNDeleteFileResult which contains the following property:

Property Name	Type	Description
`Status`	Integer	Returns a status code.

Publish file message

Publish the uploaded file message to a specified channel.

This method is called internally by sendFile as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when sendFile fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use publishFileMessage to manually resend a file message to a channel without repeating the upload step.

Don't JSON serialize

Method(s)

pubnub.publishFileMessage()
    .channel(String)
    .fileName(String)
    .fileId(String)
    .message(Object)
    .meta(Object)
    .shouldStore(Boolean)
    .customMessageType(String)

* required

Parameter	Type	Default	Description
`channel` *	String		Name of `channel` to publish file message.
`fileName` *	String		Name of the file.
`fileId` *	String		Unique identifier of the file.
`message`	Object		The payload.
`meta`	Object		Meta data object which can be used with the filtering ability.
`shouldStore`	Boolean	`true`	Set to `false` to not store this message in history. By default, messages are stored according to the retention policy you set on your key.
`customMessageType`	String		A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes `-` and underscores `_` are allowed. The value cannot start with special characters or the string `pn_` or `pn-`. Examples: `text`, `action`, `poll`.

Basic Usage

pubnub.publishFileMessage()
    .channel("my_channel")
    .fileName("cat_picture.jpg")
    .fileId("d9515cb7-48a7-41a4-9284-f4bf331bc770")
    .message("This is a sample message")
    .customMessageType("file-message")
    .async(result -> {
        result.onSuccess(res -> {
            System.out.println("send timetoken: " + res.getTimetoken());
        });
    });

Response

{
  "timetoken": 15957709330808500,
  "status": 200,
  "file": {
      "id": "d9515cb7-48a7-41a4-9284-f4bf331bc770",
      "name": "cat_picture.jpg",
  }
}

Returns

The publishFileMessage() operation returns a PNFileUploadResult which contains the following properties:

Property Name	Type	Description
`timetoken`	Long	The timetoken at which the message was published.
`status`	Integer	Remote call return code.
`file`	PNBaseFile	Uploaded `file` information.

PNBaseFile contains the following properties:

Property Name	Type	Description
`id`	Long	Unique identifier of the uploaded file
`name`	String	`Name` of the uploaded file

Breaking changes in v9.0.0

Send file​

Don't JSON serialize

Method(s)​

Deprecated parameter

Basic Usage​

Response​

Returns​

List channel files​

Method(s)​

Basic Usage​

Response​

Returns​

Get File Url​

Method(s)​

Basic Usage​

Response​

Returns​

Download file​

Method(s)​

Deprecated parameter

Basic Usage​

Response​

Returns​

Delete file​

Method(s)​

Basic Usage​

Response​

Returns​

Publish file message​

Don't JSON serialize

Method(s)​

Basic Usage​

Response​

Returns​

Send file

Method(s)

Basic Usage

Response

Returns

List channel files

Method(s)

Basic Usage

Response

Returns

Get File Url

Method(s)

Basic Usage

Response

Returns

Download file

Method(s)

Basic Usage

Response

Returns

Delete file

Method(s)

Basic Usage

Response

Returns

Publish file message

Method(s)

Basic Usage

Response

Returns