File Sharing API for Unity SDK

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.

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)

pubnub.SendFile()
    .Channel(string)
    .File(string|byte[])
    .Texture(Texture2D | RenderTexture)
    .FileName(string)
    .Ttl(int)
    .ShouldStore(bool)
    .Message(string)
    .Meta(Dictionary<string, object>)
    .CustomMessageType(string)
    .Execute(System.Action<PNFileUploadResult, PNStatus>)

* required

Parameter	Description
`Channel` * Type: string	`Channel` for the file.
`File` Type: string or `byte[]`	Full path of the file with file name or an array of bytes. When using an array of bytes, you must set `FileName`.
`Texture` Type: `Texture2D` or `RenderTexture`	An instance of a `Texture` object. When you send a `Texture`, a `Message` with its size and format is added automatically.
`FileName` Type: string	Name of the file to send. You can use it to override the default file name.
`TTL` Type: int	How long the message should be stored in the channel's storage.
`ShouldStore` Type: bool	Whether to store the published file message in the channel's history.
`Message` Type: string	Message which should be sent along with file to specified `channel`.
`Meta` Type: Dictionary`<string, object>`	Dictionary`<string, object>` with values which should be used by PubNub service to filter file messages.
`CustomMessageType` Type: 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`.
`Execute` * Type: `System.Action`	`System.Action` of type `PNFileUploadResult`.
`ExecuteAsync` Type: None	Returns `Task<PNResult<PNFileUploadResult>>`.

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

{
    "Timetoken":15957709330808500,
    "FileId":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
    "FileName":"cat_picture.jpg"
}

Returns

The SendFile() operation returns a PNResult<PNFileUploadResult> which contains the following properties:

Property Name	Type	Description
`Result`	PNFileUploadResult	Returns a `PNFileUploadResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNFileUploadResult contains the following properties:

Property Name	Type	Description
`Timetoken`	long	Returns a `PNFileUploadResult` object.
`FileId`	string	Returns the `ID` of the file.
`FileName`	string	Returns the `name` of the file.

List channel files

Retrieve a list of files uploaded to a channel.

Method(s)

pubnub.ListFiles()
    .Channel(string)
    .Limit(int)
    .Next(string)
    .QueryParam(Dictionary<string, object>)
    .Execute(System.Action<PNListFilesResult, PNStatus>)

* 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.
`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.
`QueryParam` Type: Dictionary`<string, object>` Default: n/a	Dictionary `object` to pass name/value pairs as query `string` params with PubNub URL request for debug purpose.
`Execute` * Type: `System.Action` Default: n/a	`System.Action` of type `PNListFilesResult`.
`ExecuteAsync` Type: None Default: n/a	Returns `Task<PNResult<PNListFilesResult>>`.

Sample code

Response

{
    "FilesList":[
    {
        "Name":"cat_picture.jpg",
        "Id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
        "Size":25778,
        "Created":"2020-07-26T13:42:06Z"
    }],
    "Count":1,
    "Next":null
}

Returns

Returns PNResult<PNListFilesResult>.

Property Name	Type	Description
`Result`	PNListFilesResult	Returns a `PNListFilesResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNListFilesResult fields:

Property Name	Type	Description
`FilesList`	list`<PNFileResult>`	`List` of channel files.
`Count`	int	Number of files returned.
`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.

PNFileResult fields:

Property Name	Type	Description
`Name`	string	`Name` of the file.
`Id`	string	`ID` of the file.
`Size`	int	`Size` of the file.
`Created`	string	Create date of the file.

Get file URL

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

Method(s)

pubnub.GetFileUrl()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNFileUrlResult, PNStatus>)

* required

Parameter	Description
`Channel` * Type: string	Name of `channel` within which file with name has been uploaded.
`FileId` * Type: string	Unique file identifier which has been assigned during file upload.
`FileName` * Type: string	Name under which uploaded file is stored for `channel`.
`Execute` * Type: `System.Action`	`System.Action` of type `PNFileUrlResult`.
`ExecuteAsync` Type: None	Returns `Task<PNResult<PNFileUrlResult>>`.

Sample code

Returns

Returns PNResult<PNFileUrlResult>.

Property Name	Type	Description
`Result`	PNFileUrlResult	Returns a `PNFileUrlResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNFileUrlResult fields:

Property Name	Type	Description
`Url`	string	`URL` which can be used to download remote file with specified name and identifier.

Download file

Download a file from the specified channel.

Method(s)

pubnub.DownloadFile()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNDownloadFileResult, PNStatus>)

* required

Parameter	Description
`Channel` * Type: string	Name of `channel` within which file with name has been uploaded.
`FileId` * Type: string	Unique file identifier which has been assigned during file upload.
`FileName` * Type: string	Name under which uploaded file is stored for `channel`.
`Execute` * Type: `System.Action`	`System.Action` of type `PNDownloadFileResult`.
`ExecuteAsync` Type: None	Returns `Task<PNResult<PNDownloadFileResult>>`.

Deprecated parameter

Sample code

Response

{
    //Call fileDownloadResult.SaveFileToLocal(<destination path>) to save file.
    "FileBytes":"/9j/4AAQSkZJRgABAQEAkACQAAD/4RCERXhpZgAATU0AKgAAAAgABAE7AAIAAAAGAAAISodpAAQAAAABAAAIUJydAAEAAAA...<truncated due to lengthy data",
    "FileName":"cat_picture.jpg"
}

Returns

Returns PNResult<PNDownloadFileResult>.

Property Name	Type	Description
`Result`	PNDownloadFileResult	Returns a `PNDownloadFileResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNDownloadFileResult fields:

Property Name	Type	Description
`FileBytes`	byte[]	Bytes of the downloaded file.
`FileName`	string	Name of the downloaded file.
`SaveFileToLocal(string)`	n/a	Call with a destination path to save the file locally.

Delete file

Delete a file from the specified channel.

Method(s)

pubnub.DeleteFile()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Execute(System.Action<PNDeleteFileResult, PNStatus>)

* required

Parameter	Description
`Channel` * Type: string	Name of `channel` within which file with name needs to be deleted.
`FileId` * Type: string	Unique file identifier of the file to be deleted.
`FileName` * Type: string	Name of the file to be deleted from the `channel`.
`Execute` * Type: `System.Action`	`System.Action` of type `PNDeleteFileResult`.
`ExecuteAsync` Type: None	Returns `Task<PNResult<PNDeleteFileResult>>`.

Sample code

Response

{}

Returns

Returns PNResult<PNDeleteFileResult>.

Property Name	Type	Description
`Result`	PNDeleteFileResult	Returns a `PNDeleteFileResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNDeleteFileResult is empty.

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)

pubnub.PublishFileMessage()
    .Channel(string)
    .FileId(string)
    .FileName(string)
    .Message(object)
    .Meta(Dictionary<string, object>)
    .ShouldStore(bool)
    .CustomMessageType(string)
    .Execute(System.Action<PNPublishFileMessageResult, PNStatus>)

* required

Parameter	Description
`Channel` * Type: string Default: n/a	Name of `channel` to publish file message
`FileId` * Type: string Default: n/a	Unique file identifier of the file.
`FileName` * Type: string Default: n/a	Name of the file.
`Message` Type: string Default: n/a	The payload.
`Meta` Type: string Default: n/a	Metadata object which can be used with the filtering ability.
`ShouldStore` Type: bool Default: `true`	Whether to store the message in 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`.
`Execute` * Type: `System.Action` Default: n/a	`System.Action` of type `PNPublishFileMessageResult`.
`ExecuteAsync` Type: None Default: n/a	Returns `Task<PNResult<PNPublishFileMessageResult>>`.

Sample code

Response

{
    "Timetoken":15957738720237858
}

Returns

Returns PNResult<PNPublishFileMessageResult>.

Property Name	Type	Description
`Result`	PNPublishFileMessageResult	Returns a `PNPublishFileMessageResult` object.
`Status`	PNStatus	Returns a `PNStatus` object.

PNPublishFileMessageResult contains the following properties:

Property Name	Type	Description
`Timetoken`	long	Returns a long representation of the timetoken when the `message` was published.

Send file​

Method(s)​

Deprecated parameter

Sample code​

Reference code

Response​

Returns​

List channel files​

Method(s)​

Sample code​

Response​

Returns​

Get file URL​

Method(s)​

Sample code​

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

List channel files

Method(s)

Sample code

Response

Returns

Get file URL

Method(s)

Sample code

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