On this page

File Sharing API for Kotlin SDK

Breaking changes in v9.0.0

PubNub Kotlin SDK version 9.0.0 unifies the codebases for Kotlin and Java 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 Kotlin SDK.

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

You can upload and share files up to 5 MB on PubNub. Common uses include sharing images in chat apps and documents in healthcare.

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.

Request execution

Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously.

You must invoke the .sync() or .async() method on the Endpoint to execute the request, or the operation will not be performed.

1val channel = pubnub.channel("channelName")
2

3channel.publish("This SDK rules!").async { result ->
4    result.onFailure { exception ->
5        // Handle error
6    }.onSuccess { value ->
7        // Handle successful method result
8    }
9}

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.

For details on the method that publishes the file message, see Publish file message.

Method(s)

1pubnub.sendFile(
  channel: String,
  fileName: String,
  inputStream: InputStream,
  message: Any? = null,
  meta: Any? = null,
  ttl: Int? = null,
  shouldStore: Boolean? = null
  customMessageType: String
10)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Channel for the file.
`fileName` * Type: String Default: n/a	Name of the file to send.
`inputStream` * Type: InputStream Default: n/a	Input stream with file content.
`message` Type: Any? Default: n/a	Message to send along with the file to the specified `channel`.
`meta` Type: Any? Default: n/a	Metadata object which can be used with the filtering ability.
`ttl` Type: Int? Default: n/a	How long the message should be stored in the channel's storage.
`shouldStore` Type: Boolean? Default: true	Whether to store the published `file message` in the `channel` history.
`customMessageType` Type: String Default: n/a	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.

Sample code

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

Response

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

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`	Int	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.

Other examples

Send file with push notification

Trigger push notifications when sharing files

To send mobile push notifications when sharing a file, include pn_apns (for iOS) and/or pn_fcm (for Android) payloads in the message parameter of the sendFile method.

When PubNub detects these reserved keys, it automatically forwards the push notification to the appropriate push service (APNs or FCM) for all devices registered on the channel.

val pushPayloadHelper = PushPayloadHelper().apply {
    // APNS (iOS)
    apnsPayload = APNSPayload().apply {
        aps = APNSPayload.APS().apply {
            alert = mapOf("title" to "New File", "body" to "A file was shared")
            sound = "default"
        }
        apns2Configurations = listOf(
            APNSPayload.APNS2Configuration().apply {
                targets = listOf(
                    APNSPayload.APNS2Configuration.Target().apply {
                        topic = "com.yourapp.bundleid"
                        environment = PNPushEnvironment.PRODUCTION
                    }
                )
                version = "v2"
                authMethod = APNSPayload.APNS2Configuration.APNS2AuthMethod.TOKEN
            }
        )
    }
21

    // FCM (Android)
    fcmPayloadV2 = PushPayloadHelper.FCMPayloadV2().apply {
        notification = PushPayloadHelper.FCMPayloadV2.Notification().apply {
            title = "New File"
            body = "A file was shared"
        }
        data = mapOf("type" to "file_shared", "channel" to "my-channel")
    }
30

    // Common payload
    commonPayload = mapOf("text" to "Check out this file!")
}
34

val message = pushPayloadHelper.build()
val fileInputStream: InputStream = FileInputStream("path/to/your/file.txt")
pubnub.sendFile(
    channel = "my-channel",
    fileName = "example.txt",
    inputStream = fileInputStream,
    message = message
).async { result ->
    result.onSuccess { res ->
        println("File ID: ${res.file.id}")
    }.onFailure { ex ->
        println("Error: ${ex.message}")
    }
}
show all 48 lines

For more details on push notification payload structure, see the iOS Push and Android Push documentation. To prevent the sender from receiving their own push notification, add their device token to excluded_devices in the pn_push targets.

List channel files

Retrieve a list of files uploaded to a channel.

Method(s)

1pubnub.listFiles()
2    channel: String,
3    limit: Int,
4    next: String?
5)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Channel to get list of files.
`limit` Type: Int Default: 100	Number of files to return. Minimum value is 1, and maximum is 100.
`next` Type: String? Default: n/a	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.

Sample code

Response

1{
"data":[
    {
    "name":"cat_picture.jpg",
    "id":"fileId",
    "size":25778,
    "created":"202007 - 26T13:42:06Z"
    }],
 "status": 200
 "totalCount": 1,
 "next": null,
 "prev": null
13}

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`	Int	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`	Int	Number of files returned.
`data`	List`<PNUploadedFile>`	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`	Int	Size of the uploaded file.
`created`	String	Time of creation.

Get file URL

Generate a URL to download a file from the target channel.

Method(s)

1pubnub.getFileUrl(
2    channel: String,
3    fileName: String,
4    fileId: String
5)

* required

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

Sample code

Response

1{
2    "url" : http://ps.pndsn.com/v1/files/demo/channels/my_channel/files/fileID/cat_picture.jpg?pnsdk=PubNub-kotlin-Unified/4.32.0&timestamp=1595771548&uuid=someUuid
3}

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 the specified file.

Method(s)

1pubnub.downloadFile(
2    channel: String,
3    fileName: String,
4    fileId: String
5)

* required

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

Deprecated parameter

Sample code

Response

1{
2    "fileName": "cat_picture.jpg",
3    "byteStream": <file data>
4}

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 a file from the specified channel.

Method(s)

1pubnub.deleteFile(
2    channel: String,
3    fileName: String,
4    fileId: String
5)

* required

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

Sample code

Response

1{
2    "status": 200
3}

Returns

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

Property Name	Type	Description
`Status`	int	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.

Method(s)

1pubnub.publishFileMessage(
  channel: String,
  fileName: String,
  fileId: String,
  message: Any?,
  meta: Any?,
  shouldStore: Boolean,
  customMessageType: String
9)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Name of channel to publish file message.
`fileName` * Type: String Default: n/a	Name of the `file`.
`fileId` * Type: String Default: n/a	Unique identifier of the file.
`message` Type: Any? Default: n/a	The payload.
`meta` Type: Any? Default: n/a	Metadata object which can be used with the filtering capability.
`shouldStore` Type: Boolean Default: true	Whether to store this message in history. Set to `false` to not store it. By default, messages are stored according to the retention policy you set on your key.
`customMessageType` Type: String Default: n/a	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`.

Sample code

Response

1[1, "Sent", "17483548017978763"]

Returns

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

Property Name	Type	Description
`timetoken`	Long	The timetoken at which the message was published.
`status`	Int	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

Request execution

Send file​

Method(s)​

Deprecated parameter

Sample code​

Reference code

Response​

Returns​

Other examples​

Send file with push notification​

Trigger push notifications when sharing files

List channel files​

Method(s)​

Sample code​

Response​

Returns​

Get file URL​

Method(s)​

Sample code​

Response​

Returns​

Download file​

Method(s)​

Deprecated parameter

Sample code​

Response​

Returns​

Delete file​

Method(s)​

Sample code​

Response​

Returns​

Publish file message​

Method(s)​

Sample code​

Response​

Returns​

Send file

Method(s)

Sample code

Response

Returns

Other examples

Send file with push notification

List channel files

Method(s)

Sample code

Response

Returns

Get file URL

Method(s)

Sample code

Response

Returns

Download file

Method(s)

Sample code

Response

Returns

Delete file

Method(s)

Sample code

Response

Returns

Publish file message

Method(s)

Sample code

Response

Returns