Freshworks Developer Docs | Object storage

Object store allows an app to store multimedia files, such as images, spreadsheets, and other data files to perform various actions. Some apps require the ability to store and retrieve such data. For example, a user might want to import a large number of tickets using a CSV file.

To support the development of these apps, we provide an object store that enables apps to store, retrieve, and delete files as required.

Important:

Object store has the following limitations for processed files and their associated details:

Allowed file types: PNG, JPG, JPEG, XLS, XLSX, CSV, and JSON.
Maximum file size: 10 MB per upload.
Alphanumeric characters only: File name, tag name, and description.
Tag name: Less than 50 characters.
File name: 2–255 characters.
File description: Less than 255 characters.
Maximum file storage (per app per account): 100 MB. To increase this limit, raise a ticket requesting for increased limit for the account here.

This section explains how to,

Take a look at the Object Storage sample apps for a demonstration of this feature.

Upload a file

Uploads the file to the data store for processing.

Sample code

app.js file

client.files.upload(<formdata>)

server.js file

$files.upload(<formdata>)

Request parameters

Parameters	Description
file Mandatory	Location from which the file is retrieved for upload.
description	Meaningful description of the file provided by the user.
tag	Term or phrase related to the file provided by the user that can be used while filtering for files.
expires_at	Expiry time of the file uploaded is provided by the user. If the expires_at value is provided the file is deleted at the mentioned time. Note: The expiry time should be given in ISO8601 format. The mentioned time must be at least a minimum of one hour in the future from the time of file upload.

Response

When a file is uploaded successfully, a file object containing all the details of the file is generated and returned as the response.

idstring
Identifier of the file object, generated when the file is uploaded.
created_atstring
Timestamp of when the file was uploaded is specified in the UTC format.
content_typestring
File format of the file.
descriptionstring
Meaningful description of the file provided by the user.
expires_atstring
The expiry time of the file uploaded is optional and if the user defines it, the file is deleted at the mentioned time.
Time mentioned by the user as the expiry time of the file is specified in the UTC format.
file_namestring
Name of the file.
file_size_bytesinteger
Size of the file in bytes.
tagstring
Term or phrase related to the file provided by the developer that can be used while filtering for files.

Sample app.js

Sample server.js

const fileInput = document.getElementById('cl-file-store-fileInput');
let file = fileInput.files[0];
const formData = new FormData();
      formData.append('file', file);
      formData.append('description', 'This is a test file upload');
      formData.append('tag', 'automationtag');

      client.files.upload(formData).then(
        function (data) {
          const isSuccess = !!data.id;
          console.log(`File upload ${isSuccess ? 'successful' : 'failed'}`, data);
        },
        function (err) {
          console.log('File upload failed', err);
        }
      );

Sample response

{
  "id": "d2784e7c-a414-4da8-954c-911fe425094a",
  "created_at": "2018-01-29T13:07:32+05:30",
  "file_name": "file1.png",
  "content_type": "image/png",
  "description": "kyc approve document",
  "file_size_bytes": 127343,
  "expires_at": "2019-01-29T13:07:32+05:30",
  "tag": "First-quarter"
}

Note:For a file to be uploaded using $files.upload(), you need to write the file path in $files.getSandboxedPath(), so the filepath can be called while uploading the file from server.js.

List all files

Lists the uploaded files as a JSON object.

Sample code

app.js file

client.files.list({})

server.js file

$files.list({})

sample filter

{
  page: 1,
  limit: 10,
  filters: [
   {
    "field": "tag",
    "operator": "equals",
    "values": [
      "abc"
    ]
   }
  ] 
}

You can use the filters to get a specific list of files as per the conditions using the following attributes.

pageinteger
Retrieves a specific page from the list of files.
Note: By default, the value of this attribute is set to 1, which means it returns the first page of the list.
limitinteger
Specifies the number of the file object to retrieve.
Note: The maximum and default value for the limit is 20 per page.
filtersarray of objects
Denotes the condition to be met with for filtering the files.

Response

A successful call returns a list of file objects that match the criteria. Pagination details such as page, limit, and total_records, which indicate the number of files matching the filters, are included in the response under the pagination object.

Sample response

{
  "files": [
    {
      "id": "d2784e7c-a414-4da8-954c-911fe425094a",
      "created_at": "2018-01-29T13:07:32+05:30",
      "file_name": "file1.png",
      "content_type": "image/png",
      "description": "kyc approve document",
      "file_size_bytes": 127343,
      "tag": "first-quarter"
    },
    {
      "id": "d2784e7c-a414-4da8-954c-911fe425094a",
      "created_at": "2018-01-29T13:07:32+05:30",
      "file_name": "file1.png",
      "content_type": "image/png",
      "description": "kyc approve document",
      "file_size_bytes": 127343,
      "tag": "second-quarter"
    }
  ],
 "pagination": {
   "total_records": "6",
   "limit": "10",
   "page": "1"
 }
}

Retrieve a file

Retrieves a specific file identified by the value of the files.id attribute.

Note:To see the value of the id attribute for all the uploaded files, use the list() method.

Sample code

app.js file

client.files.get('d2784e7c-a414-4da8-954c-911fe425094a')

server.js file

$files.get('d2784e7c-a414-4da8-954c-911fe425094a')

Response

A successful call returns the files object of the file identified in response.

Notes:

To learn about the attributes returned in the response payload, see the Upload method response payload.
As part of the response, you get download_url attribute, a signed URL to be used for downloading the file. The URL retrieved is valid only for 5 minutes, and you need to retrieve the file again for a new download URL.

Sample response

{
  "id": "d2784e7c-a414-4da8-954c-911fe425094a",
  "created_at": "2018-01-29T13:07:32+05:30",
  "file_name": "file1.png",
  "content_type": "image/png",
  "description": "kyc approve document",
  "file_size_bytes": 127343,
  "download_url": "https://myfileurl",
  "tag": "first-quarter"
}

Delete a file

Deleted a specific file identified by the value of the files.id attribute.

Note:To see the value of the id attribute for all the uploaded files, use the list() method.

Sample code

app.js file

client.files.delete('d2784e7c-a414-4da8-954c-911fe425094a')

server.js file

$files.delete('d2784e7c-a414-4da8-954c-911fe425094a')

Response

When the file is deleted, a success message confirming the deletion is returned.

Errors

In case of failure, a status code is displayed along with a message to troubleshoot the issue.

Example


{
    "status": 400,
    "message": "Validation failed'",
    “errors”: [
          {
           “message”: “”
         }
     ],
     “errorSource”: “”
}

The following table lists the supported status code.

Status code	Files interfaces	Description
400	Upload	Is returned due to invalid input. In case of files, the scenario may include missing file, unsupported file, or file size is beyond maximum limit. This status code is also received when the limitations mentioned for the tag name, file name, file description, or expires_at value are not followed.
	List	Is returned due to invalid input. Some of the scenarios that might result in such an error include when the value for the page value is not greater than 0 or the limit value is not between 1 to 20. This status code is also received when the filter attributes don’t adhere to their respective rules as mentioned: field value mentioned under the key attribute must be a string. The only operator value supported is EQUALS. values attribute should be in an array format with at least one value.
404	Get	Is returned when the requested file is not found. For example, when the value of the id attribute provided for identifying a file is incorrect, you may receive this value in the status code.
	Delete	Is returned when the requested file is not found. For example, when the value of the id attribute provided for identifying a file is incorrect, you may receive this value in the status code.
429	Upload	Is returned when the files uploaded exceed the limit of 100 MB.

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Object storage

Upload a file

List all files

Retrieve a file

Delete a file

Errors

Tutorials

Sample apps

Guides

Blogs

Assist catalog

Events

Object storageOn this page

Upload a file

List all files

Retrieve a file

Delete a file

Errors

Object storage