File Sharing

Overview

Users can easily share files through channels and surveys. But administrators should take into consideration the file-sharing aspects explained below to take full advantage of the possibilities the API tools can grant.

Security Features

For security reasons, uploaded files are digitally signed. Only verified users from the same company can access the uploaded files and are required to provide the digitally signed file URL each time they wish to access a file.

By default, users on the platform have a maximum of 15-minute access to files. Once that time passes, the file must be signed again. Through the API request, access time can be set between 1 to 15 minutes.

File Specifications

Compatible file formats include:

• videos: .mpeg, .mpg, .mov, .mp4, .avi
• images: .gif, .jpg, .jpeg, .png
• documents: .xlsx, .xls, .xlsm, .ods, .docx, .doc, .odt, .ppt, .pptx, .odp, .key, .rtf, .pdf, .csv, .ics, .txt, .zip, .log, .md

Maximum file size: 25 MB

File Destination

Files are uploaded to our servers and stored in company folders according to their content type, i.e., video, image, document. Files are also processed according to their content type, e.g., image files are processed and stored in different folders with their original and thumbnail files, respectively.

Upload a File

Uploads a file and returns a COTFile instance.

Summary of asynchronous upload process:

• Request 1 => File is uploaded.
• Request 2 => Loop. Verifies if file upload is ready.
• Request 3 => File URL is generated.

POST /media/file/upload

Endpoint URL

https://www.cotalker.com/api/v3/media/file/upload

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates the body's format.	Required	multipart/form-data

Request Body

multipart/form-data

Key	Description	Type	Required	Example
uploadInput	Posts a value in a response field.	object	Optional	{ "public": true }
context	Indicates the data models related to the file.	object	Optional
file	The path of the file you want to upload to the server.	string($binary)	Required	@"/folder/image.png"

Request Sample

cURL

Uploads an image file:

curl --location --request POST 'https://www.cotalker.com/api/v3/media/file/upload' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@"images/0_g05f8USWpxeQ4fkU.jpeg"' \
--form 'uploadInput="{ \"fileName\": \"new_image.jpeg\" }"'

Typescript

Uploads file and obtains a signed file URL:

const uploadingFile = await api.uploadFile(filePath);
let isReady = false;
let uploadedFile;

while (!isReady) {
  // timeout 1s
  await sleep(1000);
  // get file status
  uploadedFile = await api.getFileById(uploadingFile.id);
  // check if ready
  isReady = uploadedFile.status == 'uploaded';
}

const signedUrl = await api.signUrl(uploadedFile.url);

Response Sample

The response follows the COTFile data model.

Obtain Signed File URL

Requests a signed file URL that grants the user time-limited access to the file.

POST /media/signature

Endpoint URL

https://www.cotalker.com/api/v3/media/signature

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates the body's format.	Required	application/json

Request Body

application/json

Element	Description	Type	Required	Notes
key	Indicates the relative path of the file.	string	Required	Obtained through the POST /media/file/upload or GET /media/file response.
expires	Indicates the number of seconds the file is available to the user before needing to get another signed URL.	number	Required	Minimum: 60 (1 minute) Maximum: 900 (15 minutes)
disposition		string	Optional	Set to "inline".
fileName	Gives the file a new name.	string	Optional	Should include the proper extenstion.

Request Sample

Requests a signed file URL for a jpeg image.

curl --location --request POST 'https://www.cotalker.com/api/v3/media/signature' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
    "key": "acme_inc/image/v4_619e70899b5de1914b5f4ad4/square/d3y9um697me01.jpeg",
    "expires": 900,
    "disposition": "inline",
    "fileName": "new-name.jpeg"
}'

Response Sample

Signed URL that lasts 15 minutes:

"https://cotalker-us-files.s3.amazonaws.com/acme_inc/image/v4_619e70899b5de1914b5f4ad4/square/d3y9um697me01.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ27XMZVIFCIAPLHA%2F20211125%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211125T172501Z&X-Amz-Expires=900&X-Amz-Signature=a9f0bf2f4769811b58dffa93799535c027b6c66395eb237d95793ce9269d0caf&X-Amz-SignedHeaders=host&response-content-disposition=inline%3B%20filename%3Dnew-name.jpeg"

Get Files Shared on a Channel

Returns all the files shared on a channel according to their content type.

GET /media/file

Endpoint URL

https://www.cotalker.com/api/v3/media/file

Query Parameters

Parameter	Description	Type	Required	Values
contentType	Indicates the category of files to return.	string	Required	Options: image, video, or document.
channel	Indicates the channel to search through.	ObjectId<COTChannel>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Samples

curl --location --request GET 'https://www.cotalker.com/api/v3/media/file?contentType=image&channel=6052c3f5f2970a8b35f91589' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

The response follows the COTFile data model.

---