On this page

File Sharing API for Objective-C 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, sendFileWithRequest internally calls the publishFileMessageWithRequest 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)

1- (void)sendFileWithRequest:(PNSendFileRequest *)request 
2                 completion:(nullable PNSendFileCompletionBlock)block;

* required

Parameter	Description
`request` * Type: PNSendFileRequest	`Send file` request with all information about file and where it should be uploaded.
`block` Type: PNSendFileCompletionBlock	`Send file` file request completion block.

PNSendFileRequest

* required

Parameter	Description
`fileMessageMetadata` Type: NSDictionary Default: n/a	`NSDictionary` with values to be used by PubNub service to filter file messages.
`fileMessageTTL` Type: NSUInteger Default: 0	How long the message should be stored in the channel's storage. Set to `0` (zero) to store the message according to the key's retention policy.
`fileMessageStore` Type: BOOL Default: YES	Whether to store published file messages in the channel's history.
`message` Type: id Default: n/a	Message to be sent along with the file to the specified `channel`.
`filename` * Type: NSString Default: n/a	Name to be used to store uploaded data. This is set by default only if the request is created with `requestWithChannel:fileURL:`.

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#import <Foundation/Foundation.h>
2#import <PubNub/PubNub.h>
3

4// Basic configuration
5PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"demo"
6                                                          subscribeKey:@"demo"
7                                                                userID:@"fileUser"];
8

9// Optional: Configure encryption for files
10config.cryptoModule = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma"
11                                           randomInitializationVector:YES];
12

13// Create a PubNub client instance
14PubNub *client = [PubNub clientWithConfiguration:config];
15

16// Add listener for PubNub events
17[client addListener:self];
18

19// Sending file from byte data object
20NSData *content = [@"This is a sample file uploaded using PubNub File API." dataUsingEncoding:NSUTF8StringEncoding];
21

22// Create the file send request
23PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"file-channel"
24                                                          fileName:@"sample.txt"
25                                                              data:content];
26

27// Add optional parameters
28request.message = @{@"description": @"Sample text file upload"};
29request.fileMessageMetadata = @{@"type": @"text", @"size": @"small"};
30request.fileMessageStore = YES;
31

32NSLog(@"Sending file binary data as: sample.txt");
33

34// Send the file
35[client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
36    if (!status.isError) {
37        NSLog(@"✅ File uploaded successfully!");
38        NSLog(@"File ID: %@", status.data.fileIdentifier);
39        NSLog(@"Stored as: %@", status.data.fileName);
40        NSLog(@"Timetoken: %@", status.data.timetoken);
41    } else {
42        NSLog(@"❌ Error uploading file: %@", status.errorData.information);
43        
44        if (status.data.fileUploaded) {
45            NSLog(@"⚠️ File was uploaded but message publishing failed.");
46            // Here you could implement retry logic for just the message publishing
47        } else {
48            NSLog(@"⚠️ File upload failed completely.");
49            // Here you could implement retry logic for the whole file upload
50        }
51    }
52}];
53

54// Subscribe to a file channel
55PNSubscribeRequest *request = [PNSubscribeRequest requestWithChannels:@[@"file-channel"]
56                                                        channelGroups:nil];
57    
58[self.client subscribeWithRequest:request];
59

60// Required PNEventsListener methods
61- (void)client:(PubNub *)client didReceiveStatus:(PNStatus *)status {
62    // Checking connectivity only using subscribe operation.
63    if (status.operation != PNSubscribeOperation) return;
64    
65    if (status.category == PNConnectedCategory) {
66        NSLog(@"✅ Successfully connected to PubNub!");
67    } else if (status.isError) {
68        NSLog(@"❌ PubNub connection error: %@", status);
69    }
70}
71

72- (void)client:(PubNub *)client didReceiveMessage:(PNMessageResult *)message {
73    NSLog(@"Received message: %@ on channel: %@", message.data.message, message.data.channel);
74}
show all 74 lines

Response

1@interface PNSendFileData : PNServiceData
2

3// Unique identifier assigned to the file during upload
4@property (nonatomic, nullable, readonly, strong) NSString *fileIdentifier;
5

6// Time at which the file information message was published.
7@property (nonatomic, nullable, readonly, strong) NSNumber *timetoken;
8

9// Name under which the uploaded file is stored
10@property (nonatomic, nullable, readonly, strong) NSString *fileName;
11

12/**
13 * Whether the file uploaded or not.
14 *
15 * This property should be used during error handling to identify whether the
16 * send-file request should be resent, or if you just need to call
17 * file message publish.
18*/
19@property (nonatomic, readonly, assign) BOOL fileUploaded;
20

21@end
22

23@interface PNSendFileStatus : PNAcknowledgmentStatus
24

25// Send file request processed information.
26@property (nonatomic, readonly, strong) PNSendFileData *data;
27

28@end
show all 28 lines

Other examples

Upload binary data

1NSData *data = [[NSUUID UUID].UUIDString dataUsingEncoding:NSUTF8StringEncoding];
2PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"channel"
                                                        fileName:@"cat_picture.jpg"
                                                            data:data];
5

6[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
  if (!status.isError) {
      /**
       * File upload successfully completed.
       * Uploaded file information available here:
       *   status.data.fileIdentifier - unique file identifier
       *   status.data.fileName - name which has been used to store file
       */
  } else {
      /**
       * Handle send file error. Check 'category' property to find out possible issue
       * because of which request did fail.
       *
       * Check 'status.data.fileUploaded' to figure out whether request should be resent or
       * only file message publish should be called.
       */
  }
23}];
show all 23 lines

Upload using stream

1NSInputStream *stream = ...;
2NSUInteger streamSize = /* size of data in stream */;
3PNSendFileRequest *request = [PNSendFileRequest requestWithChannel:@"channel"
                                                        fileName:@"image.png"
                                                          stream:stream
                                                            size:streamSize];
7

8[self.client sendFileWithRequest:request completion:^(PNSendFileStatus *status) {
  if (!status.isError) {
      /**
       * File upload successfully completed.
       * Uploaded file information available here:
       *   status.data.fileIdentifier - unique file identifier
       *   status.data.fileName - name which has been used to store file
       */
  } else {
      /**
       * Handle send file error. Check 'category' property to find out possible issue
       * because of which request did fail.
       *
       * Check 'status.data.fileUploaded' to figure out whether request should be resent or
       * only file message publish should be called.
       */
  }
25}];
show all 25 lines

Returns

Same as from basic usage.

List channel files

Retrieve list of files uploaded to Channel.

Method(s)

1- (void)listFilesWithRequest:(PNListFilesRequest *)request 
2                  completion:(PNListFilesCompletionBlock)block;

* required

Parameter	Description
`request` * Type: PNListFilesRequest	`List files` request with all information which should be used to fetch channel's files list.
`block` * Type: PNListFilesCompletionBlock	`List files` request completion block.

PNListFilesRequest

* required

Parameter	Description
`next` Type: NSString 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.
`limit` Type: NSUInteger Default: 100	Number of files to return in response.

Sample code

1PNListFilesRequest *request = [PNListFilesRequest requestWithChannel:@"channel"];
2request.limit = 20;
3request.next = ...;
4

5[self.client listFilesWithRequest:request
6                       completion:^(PNListFilesResult *result, PNErrorStatus *status) {
7    if (!status.isError) {
8        /**
9         * Uploaded files list successfully fetched.
10         *   result.data.files - List of uploaded files (information).
11         *   result.data.next - 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.
12         *   result.data.count - Total number of files uploaded to channel.
13         */
14    } else {
15        /**
16         * Handle fetch files list error. Check 'category' property to find out possible issue
17         * because of which request did fail.
18         *
19         * Request can be resent using: [status retry]
20         */
21    }
22}];
show all 22 lines

Response

1@interface PNListFilesData : PNServiceData
2

3// List of channel files.
4@property (nonatomic, nullable, readonly, strong) NSArray<PNFile *> *files;
5

6// 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.
7@property (nonatomic, nullable, readonly, strong) NSString *next;
8

9// How many files has been returned.
10@property (nonatomic, readonly, assign) NSUInteger count;
11

12@end
13

14@interface PNListFilesResult : PNResult
15

16// List files request processed information.
17@property (nonatomic, readonly, strong) PNListFilesData *data;
18

19@end
show all 19 lines

Get file URL

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

Method(s)

1- (nullable NSURL *)downloadURLForFileWithName:(NSString *)name 
2                                    identifier:(NSString *)identifier 
3                                     inChannel:(NSString *)channel;

* required

Parameter	Description
`name` * Type: NSString	Name under which uploaded `file` is stored for `channel`.
`identifier` * Type: NSString	Unique `file` identifier which has been assigned during `file` upload.
`channel` * Type: NSString	Name of channel within which `file` with `name` has been uploaded.

Sample code

1NSURL *url = [self.client downloadURLForFileWithName:@"user_profile.png"
2                                          identifier:@"<file-identifier>"
3                                           inChannel:@"lobby"];

Returns

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)

1- (void)downloadFileWithRequest:(PNDownloadFileRequest *)request 
2                     completion:(PNDownloadFileCompletionBlock)block;

* required

Parameter	Description
`request` * Type: PNDownloadFileRequest	`Download file` request with information about file which should be downloaded.
`block` * Type: PNDownloadFileCompletionBlock	`Download file` request completion block.

PNDownloadFileRequest

* required

Parameter	Description
`targetURL` Type: NSURL Default: Temporary location	URL where the downloaded file should be stored locally. A file downloaded to a temporary location is removed after the completion block returns.

Deprecated parameter

Sample code

1PNDownloadFileRequest *request = [PNDownloadFileRequest requestWithChannel:@"lobby"
                                                              identifier:@"<file-identifier>"
                                                                    name:@"user_profile.png"];
4request.targetURL = ...;
5

6[self.client downloadFileWithRequest:request
                        completion:^(PNDownloadFileResult *result, PNErrorStatus *status) {
8

  if (!status.isError) {
      /**
       * File successfully has been downloaded.
       *   status.data.location - location where downloaded file can be found
       *   status.data.temporary - whether file has been downloaded to temporary storage and
       *                           will be removed on completion block return.
       */
  } else {
      /**
       * Handle file download error. Check 'category' property to find out possible issue
       * because of which request did fail.
       *
       * Request can be resent using: [status retry]
       */
  }
24}];
show all 24 lines

Response

1@interface PNDownloadFileData : PNServiceData
2

3/**
4 * Whether file is temporary or not.
5 *
6 * Temporary file will be removed as soon as completion block will exit. Make sure
7 * to move temporary files (w/o scheduling task on secondary thread) to persistent
8 * location.
9 */
10@property (nonatomic, readonly, assign, getter = isTemporary) BOOL temporary;
11

12// Location where downloaded file can be found.
13@property (nonatomic, readonly, nullable, readonly, strong) NSURL *location;
14

15@end
16

17@interface PNDownloadFileResult : PNResult
18

19// Download file request processed information.
20@property (nonatomic, readonly, strong) PNDownloadFileData *data;
21

22@end
show all 22 lines

Delete file

Delete a file from the specified channel.

Method(s)

1- (void)deleteFileWithRequest:(PNDeleteFileRequest *)request 
2                   completion:(nullable PNDeleteFileCompletionBlock)block;

* required

Parameter	Description
`request` * Type: PNDeleteFileRequest	`Delete file` request with all information about file for removal.
`block` Type: PNDeleteFileCompletionBlock	`Delete file` request completion block.

Sample code

1PNDeleteFileRequest *request = [PNDeleteFileRequest requestWithChannel:@"channel"
                                                          identifier:@"<file-identifier>"
                                                                name:@"greetings.txt"];
4

5[self.client deleteFileWithRequest:request completion:^(PNAcknowledgmentStatus *status) {
  if (!status.isError) {
      // File successfully has been deleted.
  } else {
      /**
       * Handle file delete error. Check 'category' property to find out possible issue
       * because of which request did fail.
       *
       * Request can be resent using: [status retry]
       */
  }
16}];
show all 16 lines

Response

1@interface PNErrorData : PNServiceData
2

3// Stringified error information.
4@property (nonatomic, readonly, strong) NSString *information;
5

6@end
7

8@interface PNAcknowledgmentStatus : PNErrorStatus
9

10// Whether status object represent error or not.
11@property (nonatomic, readonly, assign, getter = isError) BOOL error;
12

13// Additional information related to error status object.
14@property (nonatomic, readonly, strong) PNErrorData *errorData;
15

16@end
show all 16 lines

Publish file message

Publish the uploaded file message to a specified channel.

This method is called internally by sendFileWithRequest 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 sendFileWithRequest 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 publishFileMessageWithRequest to manually resend a file message to a channel without repeating the upload step.

Method(s)

1- (void)publishFileMessageWithRequest:(PNPublishFileMessageRequest *)request 
2                           completion:(nullable PNPublishCompletionBlock)block;

* required

Parameter	Description
`request` * Type: PNPublishFileMessageRequest	`File message publish` request with all information about uploaded file.
`block` Type: PNPublishCompletionBlock	`File message publish` request completion block.

PNPublishFileMessageRequest

Property	Description
`identifier` Type: NSString*	Unique identifier provided during file upload.
`filename` Type: NSString*	Name with which uploaded data has been stored.
`customMessageType` Type: NSString*	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`.

You can also set any parameters from the PNBasePublishRequest request:

Property	Description
`arbitraryQueryParameters` Type: NSDictionary*	Arbitrary percent-encoded query parameters which should be sent along with the original API call.
`preparedMetadata` Type: NSString*	Serialized `NSDictionary` with values used by PubNub service to filter messages.
`replicate` Type: BOOL	Whether the message should be replicated across the PubNub Real-Time Network and sent simultaneously to all subscribed clients on a channel.
`store` Type: BOOL	Whether `published` data should be stored and available with the history API or not.
`metadata` Type: NSDictionary*	`NSDictionary` with values used by PubNub service to filter messages.
`channel` Type: NSString*	Name of channel to which the message should be published.
`message` Type: id	Message to be published. The object is serialized into JSON (supports `NSString`, `NSNumber`, `NSArray`, `NSDictionary`). If you configured a crypto module, the message is encrypted.
`ttl` Type: NSUInteger	Duration for which the message should be stored in the channel's storage. Passing \b 0 will store the message according to retention policy.
`retried` Type: BOOL	Indicates whether the request is repeatedly sent to retry after a recent failure.

Sample code

1PNPublishFileMessageRequest *request = [PNPublishFileMessageRequest requestWithChannel:@"channel"
2                                                                        fileIdentifier:@"fileIdentifier"
3                                                                                  name:@"fileName"];
4request.customMessageType = @"file-message";
5

6[self.client publishFileMessageWithRequest:request completion:^(PNPublishStatus *status) {
7    if (!status.isError) {
8        // File message successfully published.
9    } else {
10        // Handle file message publish error. Check 'category' property to find out possible
11        // issue because of which request did fail.
12        //
13        // Request can be resent using: [status retry];
14    }
15}];

Response

1@interface PNPublishData : PNServiceData
2

3/**
4 * Service-provided time stamp at which message has been pushed to remote
5 * data object live feed.
6 */
7@property (nonatomic, readonly, strong) NSNumber *timetoken;
8

9// Service-provide information about service response message.
10@property (nonatomic, readonly, strong) NSString *information;
11

12@end
13

14@interface PNPublishStatus : PNAcknowledgmentStatus
15

16// Stores reference on publish request processing status information.
17@property (nonatomic, readonly, strong) PNPublishData *data;
18

19@end
show all 19 lines

Send file​

Method(s)​

PNSendFileRequest​

Deprecated parameter

Sample code​

Response​

Other examples​

Upload binary data​

Upload using stream​

Returns​

List channel files​

Method(s)​

PNListFilesRequest​

Sample code​

Response​

Get file URL​

Method(s)​

Sample code​

Returns​

Download file​

Method(s)​

PNDownloadFileRequest​

Deprecated parameter

Sample code​

Response​

Delete file​

Method(s)​

Sample code​

Response​

Publish file message​

Method(s)​

PNPublishFileMessageRequest​

Sample code​

Response​

Send file

Method(s)

PNSendFileRequest

Sample code

Response

Other examples

Upload binary data

Upload using stream

Returns

List channel files

Method(s)

PNListFilesRequest

Sample code

Response

Get file URL

Method(s)

Sample code

Returns

Download file

Method(s)

PNDownloadFileRequest

Sample code

Response

Delete file

Method(s)

Sample code

Response

Publish file message

Method(s)

PNPublishFileMessageRequest

Sample code

Response