---
source_url: https://www.pubnub.com/docs/sdks/dart/api-reference/files
title: File Sharing API for Dart SDK
updated_at: 2026-06-15T12:13:46.749Z
sdk_name: PubNub Dart SDK
sdk_version: 7.1.0
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# File Sharing API for Dart SDK

PubNub Dart SDK, use the latest version: 7.1.0

Install:

```bash
dart pub add pubnub@7.1.0
```

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](#publish-file-message) 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](#publish-file-message).

### Method(s)

```dart
pubnub.files.sendFile(
  String channel, 
  String fileName, 
  List<int> file,
  {dynamic? fileMessage,
  bool? storeFileMessage,
  int? fileMessageTtl,
  String? customMessageType
  dynamic? fileMessageMeta,
  Keyset? keyset,
  String? using}
)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | String | Yes |  | Channel to send the file to. |
| fileName | String | Yes |  | Name of the file. |
| file | List<int> | Yes |  | File content. |
| fileMessage | dynamic | Optional | `null` | The file message that is published with the file. |
| storeFileMessage | bool | Optional | `true` | Whether to store the message in history. If not specified, the history configuration on the key is used. |
| fileMessageTtl | int | Optional |  | Storage time to live for each message. If `storeFileMessage` is `true`, and `ttl` is set to `0`, the message is stored with no expiry time. If `storeFileMessage` is `true` and `ttl` is `x` (`x` is an Integer value), the message is stored with an expiry time of `x` hours unless you have message retention set to `Unlimited` on your keyset configuration in the Admin Portal. If `storeFileMessage` is `false`, the `ttl` parameter is ignored. If `ttl` is not specified, expiration of the message defaults back to the expiry value for the key. |
| customMessageType | String | Optional |  | 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`. |
| fileMessageMeta | dynamic | Optional |  | Additional information about the message which can be used on stream filtering. |
| keyset | Keyset | Optional | `default keyset` | Override for the PubNub default keyset configuration. |
| using | String | Optional |  | Keyset name from the `keysetStore` to be used for this method call. |

:::warning Deprecated parameter
The `cipherKey` parameter in this method is deprecated. We recommend that you configure the [crypto module](https://www.pubnub.com/docs/sdks/dart/api-reference/configuration#cryptomodule) 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

:::tip 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.
:::

```dart
import 'dart:convert';
import 'package:pubnub/pubnub.dart';

void main() async {
  // Create PubNub instance with default keyset.
  var pubnub = PubNub(
    defaultKeyset: Keyset(
      subscribeKey: 'demo',
      publishKey: 'demo',
      userId: UserId('myUniqueUserId'),
    ),
  );

  // File details
  String channel = 'my_channel';
  String fileName = 'example.txt';
  List<int> fileContent = utf8.encode('Hello, PubNub! This is a test file.');

  // Send the file
  var result = await pubnub.files.sendFile(
    channel,
    fileName,
    fileContent,
    fileMessage: 'Check out this file!',
  );

  // Print result
  print('File uploaded and file message published - timetoken ${result.timetoken}');
}
```

### Response

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

### Returns

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

| Property Name | Type | Description |
| --- | --- | --- |
| `timetoken` | int | A representation of the timetoken when the file was published. |
| `isError` | Boolean | A flag that describes whether there was an error during upload. |
| `description` | String | File publish operation status description. |
| `fileInfo` | `FileInfo` | Uploaded file information. |

`FileInfo` contains the following properties:

| Property Name | Type | Description |
| --- | --- | --- |
| `id` | String | `id` of the uploaded file. |
| `name` | String | `name` of the upload file. |
| `url` | String | `url` of the uploaded file. |

### Other examples

#### Send file with push notification

:::tip 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.
:::

```dart
final message = {
'text': 'Check out this file!',
'pn_apns': {
  'aps': {
    'alert': {'title': 'New File', 'body': 'A file was shared'}
  },
  'pn_push': [
    {
      'targets': [{'topic': 'com.yourapp.bundleid', 'environment': 'production'}],
      'version': 'v2'
    }
  ]
},
'pn_fcm': {
  'notification': {'title': 'New File', 'body': 'A file was shared'}
}
};

final result = await pubnub.files.sendFile(
'my-channel',
'example.txt',
fileData,
fileMessage: message,
);
```

For more details on push notification payload structure, see the [iOS Push](https://www.pubnub.com/docs/general/push/ios) and [Android Push](https://www.pubnub.com/docs/general/push/android) 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 list of files uploaded to `Channel`.

### Method(s)

```dart
pubnub.files.listFiles(
  String channel,
  {int? limit, 
  String? next, 
  Keyset? keyset, 
  String? using}
)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `String`Default: n/a | Channel to send the file to. |
| `limit`Type: `int`Default: n/a | The max number of files that can be returned in the response. |
| `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. |
| `keyset`Type: `Keyset`Default: default keyset | Override for the PubNub default keyset configuration. |
| `using`Type: `String`Default: n/a | Keyset name from the `keysetStore` to be used for this method call. |

### Sample code

```dart
var result = await pubnub.files.listFiles('my_channel');

print('There are ${result.count} no. of files uploaded');
```

### Response

```json
{
  "data":[
      {
      "name":"cat_picture.jpg",
      "id":"d9515cb7-48a7-41a4-9284-f4bf331bc770",
      "size":25778,
      "created":"202007 - 26T13:42:06Z"
      }],
   "status": 200
   "totalCount": 1,
   "next": null,
   "prev": null
}
```

### Returns

The `listFiles()` operation returns a `ListFilesResult` which contains the following properties:

| Property Name | Type | Description |
| --- | --- | --- |
| `filesDetail` | `List<FileDetail>` | List of files information. |
| `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. |

`FileDetail` contains the following properties:

| Property Name | Type | Description |
| --- | --- | --- |
| `name` | String | `name` of the upload file. |
| `id` | String | `id` of the uploaded file. |
| `size` | int | `size` of the uploaded file. |
| `created` | String | Time of creation. |

## Get file URL

Generate a URL to be used to download a file from the target `channel`.

### Method(s)

```dart
pubnub.files.getFileUrl(
  String channel, 
  String fileId, 
  String fileName,
  {Keyset? keyset, 
  String? using})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `String`Default: n/a | Channel to send the file to. |
| `fileId` *Type: `String`Default: n/a | ID of the file. |
| `fileName` *Type: `String`Default: n/a | Name of the file. |
| `keyset`Type: `Keyset`Default: default keyset | Override for the PubNub default keyset configuration. |
| `using`Type: `String`Default: n/a | Keyset name from the `keysetStore` to be used for this method call. |

### Sample code

```dart
var fileURL = pubnub.files.getFileUrl(
  'my_channel', 'someFileID', 'cat_picture.jpg'
);
print('URI to download file is ${fileURL}');
```

### Response

```dart
https://ps.pndsn.com/v1/files/demo/channels/my_channel/files/someFileId/cat_picture.jpg?pnsdk=PubNub-Dart%2F1.2.0
```

### Returns

The `getFileUrl()` operation returns a `Uri`.

## Download file

Download the specified file.

### Method(s)

```dart
pubnub.files.downloadFile(
  String channel, 
  String fileId, 
  String fileName,
  {Keyset? keyset, 
  String? using})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `String`Default: n/a | Channel to send the file to. |
| `fileId` *Type: `String`Default: n/a | ID of the file. |
| `fileName` *Type: `String`Default: n/a | Name of the file. |
| `keyset`Type: `Keyset`Default: default keyset | Override for the PubNub default keyset configuration. |
| `using`Type: `String`Default: n/a | Keyset name from the `keysetStore` to be used for this method call. |

:::warning Deprecated parameter
The `cipherKey` parameter in this method is deprecated. We recommend that you configure the [crypto module](https://www.pubnub.com/docs/sdks/dart/api-reference/configuration#cryptomodule) 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

```dart
var result = await pubnub.files.downloadFile(
  'my_channel', 'someFileID', 'cat_picture.jpg');
```

### Response

```json
{
    "fileContent": <file data>
}
```

### Returns

The `downloadFile()` operation returns a `DownloadFileResult` which contains the following property:

| Property Name | Type | Description |
| --- | --- | --- |
| `fileContent` | dynamic | List of all bytes of the downloaded file. |

## Delete file

Delete a file from the specified channel.

### Method(s)

```dart
pubnub.files.deleteFile(
  String channel, 
  String fileId, 
  String fileName,
  {Keyset? keyset, 
  String? using})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `String`Default: n/a | Channel to send the file to. |
| `fileId` *Type: `String`Default: n/a | ID of the file. |
| `fileName` *Type: `String`Default: n/a | Name of the file. |
| `keyset`Type: `Keyset`Default: default keyset | Override for the PubNub default keyset configuration. |
| `using`Type: `String`Default: n/a | Keyset name from the `keysetStore` to be used for this method call. |

### Sample code

```dart
await pubnub.files.deleteFile(
  'my_channel', 'someFileID', 'cat_picture.jpg');
```

### Response

```json
{
  "status": 200
}
```

### Returns

The `deleteFile()` operation returns a `DeleteFileResult`.

## Publish file message

Publish the uploaded file message to a specified channel.

This method is called internally by [sendFile](#send-file) 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)

```dart
pubnub.files.publishFileMessage(
  String channel, 
  FileMessage message,
  {bool? storeMessage,
  int? ttl,
  dynamic? meta,
  Keyset? keyset,
  String? using,
  String? customMessageType})
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: `String`Default: n/a | Channel to send the file to. |
| `message` *Type: `FileMessage`Default: n/a | Message to publish. |
| `storeMessage`Type: `bool`Default: `true` | Whether to store the message in history. If not specified, the history configuration on the key is used. |
| `ttl`Type: `int`Default: n/a | Storage time to live for each message. If `storeMessage` is `true` and `ttl` is `0`, the message is stored with no expiry time. If `storeMessage` is `true` and `ttl` is `x` (`x` is an Integer value), the message is stored with an expiry time of `x` hours unless you have message retention set to `Unlimited` on your keyset configuration in the Admin Portal. If `storeMessage` is `false`, the `ttl` parameter is ignored. If `ttl` is not specified, then expiration of the message defaults back to the expiry value for the key. |
| `meta`Type: `dynamic`Default: n/a | Additional information about the message which can be used on stream filtering. |
| `keyset`Type: `Keyset`Default: default keyset | Override for the PubNub default keyset configuration. |
| `using`Type: `String`Default: n/a | Keyset name from the `keysetStore` to be used for this method call. |
| `customMessageType`Type: StringDefault: 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

```dart
var fileInfo = {
  'id': 'someFileID',
  'name': 'cat_picture.jpg'
};

var message = FileMessage(fileInfo, message: 'Look at this photo!');
var result =
  await pubnub.files.publishFileMessage('my_channel', message, customMessageType: 'file-message');
    
print('file message published - timetoken ${result.timetoken}');
```

### Response

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

### Returns

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

| Property Name | Type | Description |
| --- | --- | --- |
| `timetoken` | int | The timetoken at which the message was published. |
| `description` | String | result description e.g 'sent' for successfull publish |
| `isError` | Boolean | it shows error status of file Message publish operation |
| `fileInfo` | `FileInfo` | file information |

`FileInfo` contains the following properties:

| Property Name | Type | Description |
| --- | --- | --- |
| `id` | String | `id` of the uploaded file. |
| `name` | String | `name` of the uploaded file. |
| `url` | String | `url` of the uploaded file. |