File Sharing API for Go SDK

Use the Files API to upload and share files up to 5 MB on PubNub. Common use cases include social apps that share images and healthcare apps that share medical records.

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)

1pn.SendFile().
2    Channel(string).
3    Message(interface{}).
4    Name(string).
5    File(*os.File).
6    TTL(int).
7    ShouldStore(bool).
8    Meta(interface{}).
9    CustomMessageType(string).
10    UseRawMessage(bool).    
11    Execute()

* required

Channel* required#

type: Type: string

Default: no default

Channel to upload the file.

Message#

type: Type: interface

Default: no default

Message to send along with the file to the specified channel. Accepts any JSON-serializable type: string, map[string]interface{}, []interface{}, number, bool, etc.

File* required#

type: Type: *os.File

Default: no default

Pointer to the file object.

TTL#

type: Type: int

Default: no default

How long the message should be stored in the channel's storage.

ShouldStore#

type: Type: bool

default: Default: false

Whether to store the published file message in the channel's history.

Meta#

type: Type: interface

default: Default: null

Metadata object which can be used with the filtering ability.

CustomMessageType#

type: Type: string

Default: no default

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.

UseRawMessage#

type: Type: bool

default: Default: false

When true, the message is sent directly without the {"text": ...} wrapper. When false (default), the message is wrapped in a "text" field for backward compatibility. Works with any JSON-serializable type: string, map[string]interface{}, []interface{}, number, bool, etc.

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

1

Returns

The SendFile() operation returns a type PNSendFileResponse which contains the following properties:

Property Name	Type	Description
Data	PNFileData	Details of type PNFileData are described in PNFileData
Timestamp	int64	Returns an int64 representation of the timetoken when the message was published.

PNFileData

PNFileData contains the following properties:

Property Name	Type	Description
ID	string	Returns the ID of the 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.

1message := map[string]interface{}{
2  "text": "Check out this file!",
3  "pn_apns": map[string]interface{}{
4      "aps": map[string]interface{}{
5          "alert": map[string]string{"title": "New File", "body": "A file was shared"},
6      },
7  },
8  "pn_push": []map[string]interface{}{
9      {
10          "targets": []map[string]interface{}{
11              {
12                  "topic":       "com.yourapp.bundleid",
13                  "environment": "production",
14              },
15          },
16          "version": "v2",
17      },
18  },
19  "pn_fcm": map[string]interface{}{
20      "notification": map[string]string{"title": "New File", "body": "A file was shared"},
21  },
22}
23

24response, status, err := pn.SendFile().
25  Channel("my-channel").
26  Message(message).
27  File(file).
28  Name("example.txt").
29  UseRawMessage(true).
30  Execute()

show all 30 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)

1pn.ListFiles().
2    Channel(string).
3    Limit(int).
4    Next(string).
5    Execute()

* required

Channel* required#

type: Type: string

Default: no default

Channel to get list of files.

Limit#

type: Type: int

default: Default: 100

Number of files to return.

Next#

type: Type: string

Default: no default

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

1

Returns

The ListFiles() operation returns a type PNListFilesResponse which contains the following properties:

Property Name	Type	Description
Data	PNFileInfo	Details of type PNFileInfo are described in PNFileInfo
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.

PNFileInfo

PNFileInfo contains the following properties:

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

Get file URL

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

Method(s)

1pn.GetFileURL().
2    Channel(string).
3    ID(string).
4    Name(string).
5    Execute()

* required

Channel* required#

type: Type: string

Name of channel within which file with name has been uploaded.

ID* required#

type: Type: string

Unique file identifier which has been assigned during file upload.

Name* required#

type: Type: string

Name under which the uploaded file is stored for the channel.

Sample code

1

Returns

The GetFileUrl() operation returns a type PNGetFileURLResponse which contains the following properties:

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)

1pn.DownloadFile().
2    Channel(string).
3    ID(string).
4    Name(string).
5    Execute()

* required

Channel* required#

type: Type: string

Name of channel within which file with name has been uploaded.

ID* required#

type: Type: string

Unique file identifier which has been assigned during file upload.

Name* required#

type: Type: string

Name under which uploaded file is stored for channel.

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

1

Returns

The DownloadFile() operation returns a type PNDownloadFileResponse which contains the following properties:

Property Name	Type	Description
File	io.Reader	File Reader that can be used to save the File.

Delete file

Delete a file from the specified channel.

Method(s)

1pn.DeleteFile().
2    Channel(string).
3    ID(string).
4    Name(string).
5    Execute()

* required

Channel* required#

type: Type: string

Name of channel within which file with name needs to be deleted.

ID* required#

type: Type: string

Unique file identifier of the file to be deleted.

Name* required#

type: Type: string

Name of the file to be deleted from the channel.

Sample code

1

Returns

The DeleteFile() operation returns a type PNDeleteFileResponse which is nil.

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)

1pn.PublishFileMessage().
2    TTL(int).
3    Meta(interface{}).
4    ShouldStore(bool).
5    Channel(string).
6    Message(PNPublishFileMessage).
7    CustomMessageType(string).
8    UseRawMessage(bool).
9    Execute()

* required

TTL#

type: Type: int

Default: no default

How long message should be stored in channel's storage.

Meta#

type: Type: interface

Default: no default

Meta data object which can be used with the filtering ability.

ShouldStore#

type: Type: bool

default: Default: true

Store in history.

Channel* required#

type: Type: string

Default: no default

Name of channel to publish file message.

Message* required#

type: Type: PNPublishFileMessage

Default: no default

The payload should be of the type PNPublishFileMessage.

CustomMessageType#

type: Type: string

Default: no default

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.

UseRawMessage#

type: Type: bool

default: Default: false

When true, the message is sent directly without the {"text": ...} wrapper. When false (default), the message is wrapped in a "text" field for backward compatibility. Works with any JSON-serializable type: string, map[string]interface{}, []interface{}, number, bool, etc.

Sample code

1

Returns

The PublishFileMessage() operation returns type PublishFileMessageResponse which contains the following properties:

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