Files are an essential component of modern software applications. Amity provides a powerful file management system that enables you to easily handle different types of files, such as document files, videos, and audio files. In this section, we will introduce you to the concept of a file in Amity and provide an overview of file handling in Amity.

File Data

Upload Files

To upload a file to the system, you can use the Amity File Upload API provided by the SDK. The API allows you to upload a file to the Amity server by providing the file's data and the file metadata, such as the file name, file type, and file size. The SDK simplifies the process of uploading files by providing pre-built components that you can easily integrate into your application.

import { FileRepository, LoadingStatus } from '@amityco/js-sdk';

const liveObject = FileRepository.createFile({ 
  file, // https://developer.mozilla.org/en-US/docs/Web/API/File
  onProgress: ({ currentFile, currentPercent }) => {
  },
});

liveObject.on('loadingStatusChanged', ({ newValue }) => {
  if (newValue === LoadingStatus.Loaded) {
    console.log('The file is uploaded', liveObject.model);
  }
});

liveObject.on('dataError', (error) => {
  console.error('can not upload the file', error);
});

// upload video
const liveObject = FileRepository.createVideo({ 
  file,
  onProgress: ({ currentFile, currentPercent }) => {
  },
});
Refer to the 
file model
 for the description of the response after a successful file creation. If an error is encountered while creating the file, it will return the following errors:
//Attached file payload is too large
{
  "status": "error",
  "code": 500000,
  "message": "Payload too large."
}

// Unexpected error
{
  "status": "error",
  "code": 500000,
  "message": "Unexpected error"
}

Retrieve Files

You can retrieve a file from Amity using the Amity File Retrieval API provided by the SDK. The API enables you to retrieve a file from the Amity server by supplying the file ID. The SDK streamlines the process of retrieving files by offering pre-made components that can be smoothly integrated into your app.

import { FileRepository } from '@amityco/js-sdk';

let file;
const liveObject = FileRepository.getFile(fileId);

liveObject.on('dataUpdated', (updatedModel) => {
  file = updatedModel;
});

liveObject.on('dataError', (error) => {
  console.error('Can not get the file', error);
});

file = liveObject.model;

Delete Files

In addition to uploading and retrieving files, Amity provides a deleting function to delete a file that is no longer needed.

import { FileRepository } from '@amityco/js-sdk';

const success = await FileRepository.deleteFile(fileId);

"data": {
    "success": true
  }

//Permission denied error
{
  "status": "error",
  "code": 400301,
  "message": "Permission denied"
}

Resource Not Found error
{
  "status": "error",
  "code": 400400,
  "message": "Resource Not Found."
}

//Passed the wrong parameters error
{
  "status": "error",
  "code": 500000,
  "message": "Parameters error."
}

File upload and download are key features of our product, which enable developers to easily incorporate file-sharing functionality into their applications. With support for a wide range of file types, including images, videos, audio, and documents, developers can create highly engaging and interactive user experiences that drive engagement and increase retention. The maximum file size of a file regardless of its type is 1 GB.‌

By enabling users to share files directly within the chat or social feed, developers can create highly personalized and engaging experiences that foster deeper connections among users. For example, users can share photos and videos with friends and family, or exchange documents and other files within a community. To support various use cases and make it easy to handle files, images, and videos, we offer convenient methods for managing these types of content:

• File Handling

• Image Handling

• Video Handling

Video Data

The video data is the representation of the video that has been uploaded using the SDK. The uploaded video will be transcoded to other different resolutions depending on console settings. Below is a table of properties that it contains.

Upload Videos

To upload a video to the system, you can use the Amity Video Upload API provided the SDK. The API allows you to upload a video to the Amity server. The SDK simplifies the process of uploading videos by providing pre-built components that you can easily integrate into your application.

//Attached file payload is too large
{
  "status": "error",
  "code": 500000,
  "message": "Payload too large."
}

// Unexpected error
{
  "status": "error",
  "code": 500000,
  "message": "Unexpected error"
}

Retrieve Videos

Get a Specific Video Resolution

Once you uploaded a video the videos undergo transcoding from their original resolution. You can quickly access the original size of the video right after you make the video message. However, it takes time for the transcoded resolutions to be ready. Here are the available transcoded resolutions.

• 1080p

• 720p

• 480p

• 360p

• original

Get a Video Thumbnail Image

Additionally, you can display a video preview in the user interface by utilizing a video thumbnail image. This allows for a more visually appealing representation of the video and provides a quick preview for users before they choose to view the full video. The thumbnail may not immediately available after the video was uploaded. However, eventually, the thumbnail will be become available.

let fileRepository = AmityFileRepository(client: client)
    ...
    
    func downloadVideoThumbnailAsData(from message: AmityMessage) {
        guard let thumbnailFileId = message.data?["thumbnailFileId"] as? String,
              !thumbnailFileId.isEmpty,
              let imageInfo = message.getVideoThumbnailImageInfo() else { return }
        
        
        // Download from url and return saved image url.
        fileRepository.downloadImage(fromURL: imageInfo.fileURL, size: .small) { imageUrl, error in
            // Handle image url and error.
        }
    }
    
    func downloadVideoThumbnailAsUIImage(from message: AmityMessage) {
        guard let thumbnailFileId = message.data?["thumbnailFileId"] as? String,
              !thumbnailFileId.isEmpty,
              let imageInfo = message.getVideoThumbnailImageInfo() else { return }
        
        // Download from url and return image.
        fileRepository.downloadImageAsData(fromURL: imageInfo.fileURL, size: .small) { image, size, error in
            // Handle image and error.
        }
    }

The use of images as a visual representation of information is crucial in many software applications. Our SDK provides the tools and functionality needed to easily handle images. In this section, we will introduce you to image handling in Amity, including how to upload and retrieve images in the SDK.

Image Data

Upload Images

To upload an image to the system, you can use the Amity Image Upload API provided by the SDK. The API allows you to upload an image to the Amity server/ The SDK simplifies the process of uploading images by providing pre-built components that you can easily integrate into your application.

Retrieve Images

You can retrieve an image from Amity using the Amity Image Retrieval API provided by the SDK. The API enables you to retrieve an image from the Amity server by supplying the image URL. Once an image is uploaded to the server, the image will be automatically transformed into four different sizes for versatile usage. We provided an option to retrieve a specific image size which are:

• Small: is used for image thumbnails, with a maximum image size of 160 pixels per dimension. For example, this should be used for small previews in an image gallery that displays a large number of images in a grid.

• Medium: is used for standard image display, with a maximum image size of 600 pixels per dimension.

• Large: is used for full-screen image display, with a maximum image size of 1500 pixels per dimension.