Send a file to a channel

Showing JavaScript examples.

This guide shows you how to upload a file to a PubNub channel. When the upload completes, PubNub delivers a file event to all subscribers on that channel.

The examples on this page are written for the current SDK releases: C# 9.0.0, Dart 8.0.3, Go v10.0.0, Java 6.4.5, JavaScript 13.0.3 (web, Node.js, and React Native tabs), Objective-C 7.0.4, PHP 9.0.3, Python 10.7.2, and Swift 10.2.0. Each example assumes a PubNub client initialized for its SDK, unless the example sets one up itself.

Prerequisite: File Sharing must be enabled on your keyset in the Admin Portal. For how the feature works, see Files.

File size limit

Function	Limit	Notes
File size	5 MB	To raise it, contact support@pubnub.com.
File retention	File retention is 1 or 7 days on the Free plan, 30 days on Starter, and Unlimited on Pro.	Set it per keyset in the Admin Portal.
Files per list call	A single list-files call returns up to 100 files for a channel.

Send a file

Choose the channel and the file. You can attach an optional text caption to the upload.

Custom message types

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

The upload code differs by environment because each one selects or reads the file differently. Choose the tab for your environment.

Web
Node.js
React Native

1import PubNub from 'pubnub';
2

3const pubnub = new PubNub({
4  publishKey: 'YOUR_PUBLISH_KEY',
5  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
6  userId: 'YOUR_USER_ID',
7});
8

9const input = document.querySelector('input[type="file"]');
10

11input.addEventListener('change', async () => {
12  const file = input.files[0];
13  if (!file) {
14    console.error('No file selected.');
15    return;
16  }
17

18  const result = await pubnub.sendFile({
19    channel: 'my_channel',
20    file: file,
21    customMessageType: 'file-message',
22  });
23});
show all 23 lines

1import fs from 'fs';
2import PubNub from 'pubnub';
3

4const pubnub = new PubNub({
5  publishKey: 'YOUR_PUBLISH_KEY',
6  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
7  userId: 'YOUR_USER_ID',
8});
9

10const myFile = fs.createReadStream('./cat_picture.jpg');
11

12const result = await pubnub.sendFile({
13  channel: 'my_channel',
14  file: { stream: myFile, name: 'cat_picture.jpg', mimeType: 'image/jpeg' },
15  customMessageType: 'file-message',
16});
show all 16 lines

1import PubNub from 'pubnub';
2

3const pubnub = new PubNub({
4  publishKey: 'YOUR_PUBLISH_KEY',
5  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
6  userId: 'YOUR_USER_ID',
7});
8

9// Local URI of the image to upload, for example returned by an image picker.
10const imageUri = 'file:///path/to/cat_picture.jpg';
11

12const result = await pubnub.sendFile({
13  channel: 'my_channel',
14  message: {
15    test: 'message',
16    value: 42,
17  },
18  file: {
19    uri: imageUri,
20    name: 'cat_picture.jpg',
21    mimeType: 'image/jpeg',
22  },
23  customMessageType: 'file-message',
24});
show all 24 lines

1PNResult<PNFileUploadResult> fileUploadResponse = await pubnub.SendFile()
2    .Channel("my_channel")
3    .File("cat_picture.jpg") // checks the bin folder if no path is provided
4    .Message("Look at this photo!")
5    .ExecuteAsync();
6PNFileUploadResult fileUploadResult = fileUploadResponse.Result;
7PNStatus fileUploadStatus = fileUploadResponse.Status; // contains troubleshooting info
8if (!fileUploadStatus.Error && fileUploadResult != null) // checks if successful
9{
10    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileUploadResult));
11}
12else
13{
14    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(fileUploadStatus));
15}

1file, err := os.Open("cat_picture.jpg")
2defer file.Close()
3if err != nil {
4    panic(err)
5}
6resSendFile, statusSendFile, errSendFile := pn.SendFile().
7  Channel("my_channel").
8  Message("Look at this photo!").
9  Name("cat_picture.jpg").
10  File(file).Execute()
11fmt.Println(resSendFile, statusSendFile, errSendFile)
12fmt.Println(resSendFile.Data.ID)

1NSURL *localFileURL = ...;
2PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"my_channel"
                                                         fileURL:localFileURL];
4request.customMessageType = @"file-message";
5

6[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
  if (!status.isError) {
      /**
       * File upload successfully completed.
       * Uploaded file information is available here:
       *   status.data.fileIdentifier is the unique file identifier
       *   status.data.fileName is the name used to store the file
       */
  } else {
      /**
       * Handle send file error. Check the 'category' property for reasons
       * why the request may have failed.
       *
       * Check 'status.data.fileUploaded' to determine whether to resend the
       * request or if only file message publish should be called.
       */
  }
23}];
show all 23 lines

1pubnub.sendFile()
  .channel("my_channel")
  .fileName("cat_picture.jpg")
  .customMessageType("file-message")
  .inputStream(inputStream)
  .message("Look at this photo!")
  .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());
      }).onFailure(exception -> {
          exception.printStackTrace();
      });
  });
show all 16 lines

1# synchronous
2with open("cat_picture.jpg", "rb") as fd:
  envelope = pubnub.send_file() \
      .channel("my_channel") \
      .file_name("cat_picture.jpg") \
      .message({"test_message": "test"}) \
      .custom_message_type('file-message') \
      .should_store(True) \
      .ttl(222) \
      .file_object(fd) \
      .cipher_key("secret") \
      .sync()
13

14# multithreaded asynchronous
15def callback(result, status):
  if status.is_error():
      print(f"Request failed: {status.error_data}")
      return
  print(result)
20

21with open("cat_picture.jpg", "rb") as fd:
  pubnub.send_file() \
      .channel("my_channel") \
      .file_name("cat_picture.jpg") \
      .message({"test_message": "test"}) \
      .custom_message_type('file-message') \
      .should_store(True) \
      .ttl(222) \
      .file_object(fd.read()) \
      .cipher_key("secret") \
      .pn_async(callback)
show all 31 lines

1pubnub.send(
.file(url: FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent("cat_picture.jpg")),
channel: "my_channel",
remoteFilename: "cat_picture.jpg",
publishRequest: .init(additionalMessage: ["text": "Look at this photo!"], customMessageType: "file-message")
6) { (fileTask) in
print("The task \(fileTask.urlSessionTask.taskIdentifier) has started uploading; no need to call `resume()`")
print("If needed, the `URLSessionUploadTask` can be accessed with `fileTask.urlSessionTask`")
print("You can use `fileTask.progress` to populate a  `UIProgressView`/`ProgressView` ")
10} completion: { (result) in
switch result {
case let .success((task, file, publishedAt)):
  print("The file with an ID of \(file.fileId) was uploaded at \(publishedAt) timetoken) ")
case let .failure(error):
  print("An error occurred while uploading the file: \(error.localizedDescription)")
}
17}
show all 17 lines

1import 'dart:io';
2import 'package:pubnub/pubnub.dart';
3

4void main() async {
5  var pubnub = PubNub(
6    defaultKeyset: Keyset(
7      subscribeKey: 'sub-c-abc-123',  // Replace with your subscribe key
8      publishKey: 'pub-c-def-456'     // Replace with your publish key
9    ),
10  );
11

12  var inputFile = File('cat_picture.jpg').readAsBytesSync();
13

14  try {
15    var result = await pubnub.files.sendFile(
16      'my_channel',
17      'cat_picture.jpg',
18      inputFile,
19      fileMessage: 'Look at this photo!',
20      customMessageType: 'file-message'   // Example with custom message type
21    );
22

23    print('File uploaded - timetoken ${result.timetoken}');
24  } catch (e) {
25    print('Failed to send file: $e');
26  }
27}
show all 27 lines

A successful upload returns a timetoken. Subscribers on the channel receive a file event carrying the file ID, file name, and a download URL. For how to handle that event on the subscriber side, see Receive and download files.

Encrypt a file

To encrypt a file before upload, set a cipher key in the SDK client configuration or pass it per upload request. Any client that downloads the file must use the same key. For how encryption works, see Files.

The Python example above shows cipher_key("secret") as an inline parameter. Check your SDK's configuration reference for the client-level cipher key option.

Receive and download files. Handle the file event on the subscriber side and build a download URL.
List and manage stored files. List files in a channel and delete uploads.

File size limit​

Send a file​

Custom message types

Encrypt a file​

Related tasks​

File size limit

Send a file

Encrypt a file

Related tasks