> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# File Handling

> Upload, read, and delete generic file attachments with the Social+ SDKs.

Use file handling when your app needs to upload a generic attachment such as a PDF, document, archive, or audio-adjacent custom file. The SDK returns a file object with a `fileId`, URL, attributes, and access type. Pass that uploaded file or its `fileId` into post, comment, or message creation APIs when you want to attach it to user content.

This page covers generic files. Use the image and video pages for media-specific helpers such as image sizes, alt text, video status, and video resolution URLs.

## Platform Surface

| Platform   | Upload                                                                                  | Fetch                                                                          | Delete                                                                          | Notes                                                                                      |
| ---------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| TypeScript | `FileRepository.uploadFile(formData, onProgress?)`                                      | `FileRepository.getFile(fileId)` and `getFile.locally(fileId)`                 | `FileRepository.deleteFile(fileId)`                                             | `formData` must include a `files` key. Upload returns an array of uploaded files.          |
| iOS        | `AmityFileRepository.uploadFile(_:progress:)` and `uploadFile(with:fileName:progress:)` | `getFile(fileId:)`, then `mapToFileData()`                                     | `deleteFile(fileId:)`                                                           | URL-based upload is the source-recommended path for large local files.                     |
| Android    | `AmityCoreClient.newFileRepository().uploadFile(uri)`                                   | `getFile(fileId)`, then `asAmityFile()`                                        | `deleteFile(fileId)`                                                            | Upload progress is delivered through `AmityUploadResult`.                                  |
| Flutter    | `AmityCoreClient.newFileRepository().uploadFile(file)`                                  | Not exposed as a direct public file-repository fetch method in the current SDK | Not exposed as a direct public file-repository delete method in the current SDK | Use the uploaded `AmityFile` or file data loaded through post, comment, or message models. |

## Parameters

| Parameter                           | Platforms                         | Description                                                                                                                                                      |
| ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formData` / `file` / `url` / `uri` | TypeScript, iOS, Android, Flutter | The local file input. TypeScript expects `FormData`; iOS accepts `AmityUploadableFile` or a local `URL`; Android accepts `Uri`; Flutter accepts `File`.          |
| `fileName`                          | iOS                               | Optional filename for URL-based upload. If omitted, the SDK derives the name from the URL.                                                                       |
| `fileId`                            | TypeScript, iOS, Android          | ID returned by upload or embedded in content data. Used for direct fetch and delete calls where available.                                                       |
| `onProgress` / `progress`           | TypeScript, iOS, Android, Flutter | Upload progress callback or stream event. TypeScript emits a percentage; iOS emits `0.0...1.0`; Android and Flutter expose progress through `AmityUploadResult`. |
| `uploadId`                          | Android, Flutter                  | Optional lower-level identifier for tracking or canceling a specific upload. The default public upload methods generate one for you.                             |

## Upload A File

Upload a local file first, then use the returned `fileId` or file object in content creation APIs.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileRepository } from '@amityco/ts-sdk';

  async function uploadFile(file: File) {
    const formData = new FormData();
    formData.append('files', file);

    const { data: files } = await FileRepository.uploadFile(formData, percent => {
      console.log(`Upload progress: ${percent}%`);
    });

    const uploadedFile = files[0];
    return uploadedFile.fileId;
  }
  ```

  ```swift iOS theme={null}
  let fileURL = URL(fileURLWithPath: "/tmp/document.pdf")

  let uploadedFile = try await fileRepository.uploadFile(
      with: fileURL,
      fileName: "document.pdf",
      progress: { progress in
          print("Upload progress: \(progress)")
      }
  )

  let uploadedFileId = uploadedFile.fileId
  ```

  ```kotlin Android theme={null}
  val fileUri = Uri.parse("file:///tmp/document.pdf")

  AmityCoreClient.newFileRepository()
      .uploadFile(fileUri)
      .doOnNext { result: AmityUploadResult<AmityFile> ->
          when (result) {
              is AmityUploadResult.PROGRESS -> {
                  val progress = result.getUploadInfo().getProgressPercentage()
              }
              is AmityUploadResult.COMPLETE -> {
                  val uploadedFile = result.getFile()
                  val uploadedFileId = uploadedFile.getFileId()
              }
              is AmityUploadResult.ERROR -> {
                  val error = AmityError.from(result.getError())
              }
              is AmityUploadResult.CANCELLED -> {
                  // Upload was canceled.
              }
          }
      }
      .subscribe()
  ```

  ```dart Flutter theme={null}
  import 'dart:io';

  final file = File('/tmp/document.pdf');

  AmityCoreClient.newFileRepository()
      .uploadFile(file)
      .stream
      .listen((AmityUploadResult<AmityFile> result) {
    result.when(
      progress: (uploadInfo, cancelToken) {
        final progress = uploadInfo.getProgressPercentage();
      },
      complete: (uploadedFile) {
        final uploadedFileId = uploadedFile.fileId;
        final uploadedFileUrl = uploadedFile.getUrl;
      },
      error: (error) {
        final exception = error;
      },
      cancel: () {
        // Upload was canceled.
      },
    );
  });
  ```
</CodeGroup>

## Read File Data

Read file data when your app needs a direct file URL, filename, or MIME type for a previously uploaded file.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileRepository } from '@amityco/ts-sdk';

  async function getFile(fileId: string) {
    const { data: file } = await FileRepository.getFile<'file'>(fileId);

    return {
      fileId: file.fileId,
      fileUrl: file.fileUrl,
      name: file.attributes.name,
      mimeType: file.attributes.mimeType,
    };
  }
  ```

  ```swift iOS theme={null}
  let rawFile = try await fileRepository.getFile(fileId: fileId)

  if rawFile.type == .file, let fileData = rawFile.mapToFileData() {
      let localURL = try await fileRepository.downloadFile(fromURL: fileData.fileURL)
      print("Downloaded file to \(localURL)")
  }
  ```

  ```kotlin Android theme={null}
  AmityCoreClient.newFileRepository()
      .getFile(fileId)
      .doOnSuccess { rawFile: AmityRawFile ->
          if (rawFile.getFileType() == AmityFileType.FILE) {
              val file = rawFile.asAmityFile()
              val fileUrl = file.getUrl()
              val fileName = file.getFileName()
          }
      }
      .subscribe()
  ```

  ```dart Flutter theme={null}
  void inspectFile(AmityFile uploadedFile) {
    final uploadedFileId = uploadedFile.fileId;
    final uploadedFileUrl = uploadedFile.getUrl;
    final uploadedFileName = uploadedFile.fileName;
  }
  ```
</CodeGroup>

## Delete A File

Delete only files your app no longer needs. If a file is still referenced by a post, comment, message, user profile, community, or channel, update that content first so users do not see broken attachments.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileRepository } from '@amityco/ts-sdk';

  async function deleteFile(fileId: string) {
    const { success } = await FileRepository.deleteFile(fileId);
    return success;
  }
  ```

  ```swift iOS theme={null}
  try await fileRepository.deleteFile(fileId: fileId)
  ```

  ```kotlin Android theme={null}
  AmityCoreClient.newFileRepository()
      .deleteFile(fileId)
      .subscribe()
  ```
</CodeGroup>

## Related Topics

<CardGroup cols={3}>
  <Card title="Image Handling" icon="image" href="./image-handling">
    Upload images, read image metadata, and request sized image URLs.
  </Card>

  <Card title="Video Handling" icon="video" href="./video-handling">
    Upload videos and read transcoding status or resolution URLs.
  </Card>

  <Card title="File Posts" icon="file" href="/social-plus-sdk/social/content-management/posts/creation/file-post">
    Attach uploaded files to social posts.
  </Card>
</CardGroup>