# Amazon Connect Agent Workspace File API
<a name="api-reference-3P-apps-file-client"></a>

The Amazon Connect SDK provides a `FileClient` which serves as an interface that you can use to make file requests to upload, retrieve, and delete attached files.

The `FileClient` accepts an optional constructor argument, ` ConnectClientConfig` which itself is defined as:

```
export type ConnectClientConfig = {  
    context?: ModuleContext;  
    provider?: AmazonConnectProvider;
};
```

If you do not provide a value for this config, then the client will default to using the ** AmazonConnectProvider** set in the global provider scope. You can also manually configure this using **setGlobalProvider**.

You can instantiate the agent client as follows:

```
import { FileClient } from "@amazon-connect/file";

const fileClient = new FileClient({ provider });
```

**Note**  
You must first instantiate the [ AmazonConnectApp](getting-started-initialize-sdk.md) which initializes the default AmazonConnectProvider and returns ` { provider } `. This is the recommended option.

Alternatively, providing a constructor argument:

```
import { FileClient } from "@amazon-connect/file";
            
const fileClient = new FileClient({
    context: sampleContext,  
    provider: sampleProvider
});
```

**Note**  
Third-party applications must be configured with \$1 permission in order to utilize the FileClient APIs.

The following sections describe API calls for working with the File API.

**Topics**
+ [batchGetAttachedFileMetadata()](3P-apps-file-requests-batchgetattachedfilemetadata.md)
+ [completeAttachedFileUpload()](3P-apps-file-requests-completeattachedfileupload.md)
+ [deleteAttachedFile()](3P-apps-file-requests-deleteattachedfile.md)
+ [getAttachedFileUrl()](3P-apps-file-requests-getattachedfileurl.md)
+ [startAttachedFileUpload()](3P-apps-file-requests-startattachedfileupload.md)

# Get metadata about multiple attached files in Amazon Connect Agent Workspace
<a name="3P-apps-file-requests-batchgetattachedfilemetadata"></a>

Get metadata about multiple attached files on an associated resource while handling an active contact. The activeContactId is the id of the contact the agent is actively viewing. Each attached file provided in the input list must be associated with the associatedResourceArn in the RelatedAttachments request object.

 **Signature** 

```
batchGetAttachedFileMetadata({ relatedAttachments, activeContactId }: { relatedAttachments: RelatedAttachments; activeContactId: string; }): Promise<BatchGetAttachedFileMetadataResponse>
```

 **BatchGetAttachedFileMetadataResponse Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| files | AttachmentMetadata[] | Array of file metadata objects that were successfully retrieved | 
| errors | AttachmentError[] | Array of errors of attached files that could not be retrieved | 

 **AttachmentMetadata Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileId | string | The unique identifier of the attached file resource | 
| fileArn | string | The unique identifier of the attached file resource (ARN). | 
| fileName | string | A case-sensitive name of the attached file being uploaded. | 
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" | 
| fileSizeInBytes | number | The size of the attached file in bytes. | 
| creationTime | string | The time of Creation of the file resource as an ISO timestamp. It's specified in ISO 8601 format: yyyy-MM-ddThh:mm:ss.SSSZ. For example, 2024-05-03T02:41:28.172Z. | 

 **AttachmentError Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| errorCode | string | Status code describing the failure | 
| errorMessage | string | Why the attached file couldn't be retrieved | 
| fileId | string | The unique identifier of the attached file resource | 

 **RelatedAttachments Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileIds | string[] | The unique identifiers of the attached file resources | 

 **Usage** 

```
const relatedAttachments: RelatedAttachments = {
  fileIds: [sampleFileId1, sampleFileId2],
  associatedResourceArn: sampleAssociatedResourceArn, 
};

const response: BatchGetAttachedFileMetadataResponse = await fileClient.batchGetAttachedFileMetadata({
  relatedAttachments,
  activeContactId: sampleActiveContactId, // The contact the agent is actively handling
});

const { files, errors } = response;

// Add logic to handle response
```

# Confirm that an attached file has been uploaded in Amazon Connect Agent Workspace
<a name="3P-apps-file-requests-completeattachedfileupload"></a>

Allows you to confirm that the attachment has been uploaded using the pre-signed URL provided in the startAttachedFileUpload API. The request accepts an Attachment object, which has the following properties:
+ `associatedResourceArn: string`: Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN
+ `fileId: string`: ID in Connect's File record

 **Signature** 

```
completeAttachedFileUpload(attachment: Attachment): Promise<void>
```

 **Usage** 

```
/* Logic with startAttachedFileUplaod and uploading attachment to pre-signed URL */

/* ... */

await fileClient.completeAttachedFileUpload({
  associatedResourceArn: sampleAssociatedResourceArn, // Get this from the response from `startAttachedFileUpload`
  fileId: sampleFileId // Get this from the response from `startAttachedFileUpload`
});
```

# Delete an attached file in Amazon Connect Agent Workspace
<a name="3P-apps-file-requests-deleteattachedfile"></a>

Deletes an attached file along with the underlying S3 Object. The attached file is permanently deleted if S3 bucket versioning is not enabled. The request accepts an Attachment object, which has the following properties:
+ `associatedResourceArn: string`: Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN
+ `fileId: string`: ID in Connect's File record

 **Signature** 

```
deleteAttachedFile(data: Attachment): Promise<void>
```

 **Usage** 

```
await fileClient.deleteAttachedFile({
  associatedResourceArn: sampleAssociatedResourceArn, // Get this from the response from `startAttachedFileUpload`
  fileId: sampleFileId // Get this from the response from `startAttachedFileUpload`
});
```

# Get a pre-signed S3 URL to download an approved attached file in Amazon Connect Agent Workspace
<a name="3P-apps-file-requests-getattachedfileurl"></a>

Returns a pre-signed URL to download an approved attached file while handling an active contact. The activeContactId is the id of the contact the agent is actively viewing. This API also returns metadata about the attached file and it will only return a downloadUrl if the status of the attached file is APPROVED.

 **Signature** 

```
getAttachedFileUrl({ attachment, activeContactId }: { attachment: Attachment; activeContactId: string; }): Promise<DownloadableAttachment>
```

 **DownloadableAttachment Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileId | string | The unique identifier of the attached file resource. | 
| downloadUrl | string | A pre-signed URL that should be used to download the attached file. | 
| fileArn | string | The unique identifier of the attached file resource (ARN). | 
| fileName | string | A case-sensitive name of the attached file being uploaded. | 
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" | 
| fileSizeInBytes | number | The size of the attached file in bytes. | 
| creationTime | string | The time of Creation of the file resource as an ISO timestamp. It's specified in ISO 8601 format: yyyy-MM-ddThh:mm:ss.SSSZ. For example, 2024-05-03T02:41:28.172Z. | 

 **Attachment Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileId | string | The unique identifier of the attached file resource. | 

 **Usage** 

```
const downloadableAttachment = await fileClient.getAttachedFileUrl({
  attachment: {
    associatedResourceArn: sampleAssociatedResourceArn,
    fileId: sampleFileId,
  },
  activeContactId: sampleActiveContactId, // The contact the agent is actively handling
});

const { downloadUrl } = downloadableAttachment;
const response: Response = await fetch(downloadUrl, { method: "GET" });
```

# Start uploading a file to Amazon Connect Agent Workspace
<a name="3P-apps-file-requests-startattachedfileupload"></a>

Provides a pre-signed Amazon S3 URL in response to upload a new attached file.

 **Signature** 

```
startAttachedFileUpload(data: NewAttachment): Promise<UploadableAttachment>
```

 **UploadableAttachment Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. Could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileId | string | ID in Connect's File record | 
| uploadUrl | string | A pre-signed S3 URL that should be used for uploading the attached file. | 
| uploadHeaders | Record<string, string> | A map of headers that should be provided in the request when uploading the attached file. | 
| uploadMethod | "PUT" | The upload request must be a PUT. | 
| fileStatus | FileStatus | The current status of the attached file. Supported values: "APPROVED", "REJECTED", "PROCESSING", "FAILED" | 

 **NewAttachment Properties** 


|  **Parameter**  |  **Type**  |  **Description**  | 
| --- | --- | --- | 
| associatedResourceArn | string | Amazon Connect ARN of the resource that the file is attached to. This could be a Connect Email Contact ARN or a Connect Case ARN | 
| fileName | string | A case-sensitive name of the attached file being uploaded. Minimum length of 1; Maximum length of 256. Supported pattern: ^\$1P\$1C\$1\$1\$1 | 
| fileSizeInBytes | number | The size of the attached file in bytes. Minimum value of 1. | 
| fileUseCaseType | "ATTACHMENT" | The use case for the file. Must be "ATTACHMENT" | 

 **Error Handling** 

When beginning the process to upload attached files, agents may encounter issues. The @amazon-connect/file library provides methods to handle common errors:
+ `isInvalidFileNameError()`: Handle errors when the name of the file is not valid
+ `isInvalidFileTypeError()`: Handle errors when the file type is not supported
+ `isInvalidFileSizeError()`: Handle errors when the size of the file is invalid
+ `isTotalFileSizeExceededError()`: Handle errors when the total size of all files (being uploaded) exceeds the limit.
+ `isTotalFileCountExceededError()`: Handle errors when the total number of files (being uploaded) exceeds the limit.

 **Usage** 

```
import { 
    isInvalidFileNameError,
    isInvalidFileTypeError,
    isInvalidFileSizeError,
    isTotalFileSizeExceededError,
    isTotalFileCountExceededError
} from "@amazon-connect/file";

/* ... */

const newAttachment: NewAttachment = {
  associatedResourceArn: sampleAssociatedResourceArn, // This could be an email contact ARN or case ARN that you are uploading the attached file to
  fileName: sampleFileName,
  fileSizeInBytes: sampleFileSizeInBytes,
  fileUseCaseType: "ATTACHMENT"
};

let uploadableAttachment: UploadableAttachment;
try {
  uploadableAttachment = await fileClient.startAttachedFileUpload(newAttachment);
} catch (e) {
  if (isInvalidFileNameError(e)) {
    // Handle InvalidFileName error
  } else if (isInvalidFileTypeError(e)) {
    // Handle InvalidFileType error
  } else if (isInvalidFileSizeError(e)) {
    // Handle InvalidFileSize error
  } else if (isTotalFileSizeExceededError(e)) {
    // Handle TotalFileSizeExceeded error
  } else if (isTotalFileCountExceededError(e)) {
    // Handle TotalFileCountExceeded error
  }
}

// Assuming startAttachedFileUpload succeeded, we upload the attached file to the pre-signed S3 URL
const { uploadUrl, uploadHeaders, uploadMethod } = uploadableAttachment;

await fetch(uploadUrl, {
  method: uploadMethod,
  headers: uploadHeaders,
  body: file, // This is the file you're uploading
});
```