File Storage¶

By default, users cannot attach files to chat messages. To enable file uploads via drag and drop or the Attach file button, you must connect your Endpoint to a third-party storage provider.

Enabling file uploads in your Endpoint enhances the user experience by allowing seamless sharing of documents, images, and other files within the chat. Users can upload screenshots to illustrate technical issues and share various documents such as contracts, invoices, order confirmations, and photos of purchased goods.

After uploading a file to the chat interface, the file will be saved in the storage of your third-party provider and will be accessible for viewing by both the sender and the recipient in the chat.

Supported Endpoints¶

You can use the File Storage section in the following Endpoints:

Security Measures¶

Cognigy.AI performs a virus scan on the file before uploading it to the cloud storage provider. This process ensures the file is checked for potential malware or viruses, helping to prevent harmful content from being stored or shared through the cloud.

Create Connections to File Storage Providers¶

To enable file uploads, connect to one of the following file storage providers:

Azure Blob Storage ContainerAmazon S3 Bucket and Amazon S3-Compatible CloudGoogle Cloud Storage Bucket

Make sure that you have access to Azure Blob Storage Container and at least one container has been created, or create a new one. Note that the container must be publicly available; otherwise, users cannot upload files via the chat interface.
Open the Azure portal.
In the Azure services section, select Storage Accounts.
On the Storage accounts page, select the account from the Name column.
In the left-side menu, navigate to Data storage > Containers. Copy the name of the target container from the Name column. This container will store user-uploaded files. Save the container name for later use.
In the left-side menu, go to Security + networking and select Access Keys.
On the Access Keys page, copy the name from the Storage account name field and the key from the Key field for later use.
On the Cognigy.AI side, open the Project that contains the Endpoint for which you want to configure file uploads. In the left-side menu of the Project, go to Deploy > Endpoints. On the Endpoints page, select one of the Endpoints that supports file uploads or create a new one.
Depending on the Endpoint you select, proceed as follows:
- Webchat v3 — go to Webchat Behavior > Attachment Upload on the Endpoint Settings page. Activate the Allow Attachment Upload setting.
- Other Endpoints — go to the File Storage section on the Endpoint Settings page.
From the File Storage Provider list, select Azure.
Next to the Azure Connection, click +.
In the New Connection window, fill in the following fields:
- Container Name — the name of the container that you copied and saved previously.
- Account — enter the storage account name that you copied and saved previously.
- Account Key — enter the key that you copied and saved previously.
Click Create, then Save.

Make sure that you have access to Amazon S3 bucket or to an Amazon S3-compatible cloud, for example, Open Telekom Cloud, DigitalOcean Spaces, Backblaze B2. You need to have at least one bucket or to create a new one. The bucket must be publicly accessible; otherwise, users can't upload files via the chat interface. For an Amazon S3-compatible cloud storage, you need similar information as described in the following steps.
Open the Amazon S3 console.
On the Amazon S3 page, go to the General purpose buckets tab.
From the Name column, copy the name of the target bucket from the Name column. This bucket will store user-uploaded files. Save the bucket name for later use.
From the AWS Region column, copy the region ID, for example, us-east-1, and save it for later use.
In the upper-right corner, go to your account, then select Security credentials.
On the My Security Credentials page, go to Access keys and click Create access key.
On the Alternatives to root user access keys page, review the security recommendations. To continue, select the option, and then click Create access key. On the Retrieve access key page, your access key ID is displayed.
Under Secret access key, click Show and then copy the access key ID and secret key from your browser window and save them for later use. Click Done. If you want to use temporary access with MFA instead of a secret key, you need a session token. To set up a session token, obtain this value via AWS API and specify the token in the AWS_SESSION_TOKEN variable in the values.yaml file. For more information, read Using temporary credentials with AWS resources.
On the Cognigy.AI side, open the Project that contains the Endpoint for which you want to configure file uploads. In the left-side menu of the Project, go to Deploy > Endpoints. On the Endpoints page, select one of the Endpoints that supports file uploads or create a new one.
Depending on the Endpoint you select, proceed as follows:
- Webchat v3 — go to Webchat Behavior > Attachment Upload on the Endpoint Settings page. Activate the Allow Attachment Upload setting.
- Other Endpoints — go to the File Storage section on the Endpoint Settings page.
From the File Storage Provider list, select AWS.
Next to AWS Connection, click +.
In the New Connection window, fill in the following fields:
- Connection Name — enter a name for the connection.
- Access Key ID — enter the access key ID that you copied and saved previously.
- Secret Access Key — enter the secret key that you copied and saved previously.
- Region — enter the AWS region that you copied and saved previously.
- Bucket Name — enter the name of the bucket that you copied and saved previously.
- Custom URL — enter the custom URL of your S3-compatible storage. This parameter applies only for Amazon S3-compatible cloud storages.
Click Create, then Save.

Make sure that you have access to Google Cloud Storage and that at least one bucket has been created, or create a new one. Note that the bucket must be publicly available; otherwise, users cannot upload files via the chat interface.
Open the Google Cloud console.
In the left-side menu, select Cloud Storage > Buckets.
On the Buckets page, copy the name of the target bucket from the Bucket column. This bucket will store user-uploaded files. Save the bucket name for later use.
In the left-side menu, select IAM & Admin > Service Accounts.
From the Email field, copy the email address and save it for later use.
In the Actions column, click Actions > Manage Keys.
On the Keys tab, click Add Key > Create New Key and select the JSON key type. The key will be downloaded to your computer. Open the JSON file and copy the entire value of the private_key parameter, including the lines:
```
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
```
Save the key for later use.
On the Cognigy.AI side, open the Project that contains the Endpoint for which you want to configure file uploads. In the left-side menu of the Project, go to Deploy > Endpoints. On the Endpoints page, select one of the Endpoints that supports file uploads or create a new one.
Depending on the Endpoint you select, proceed as follows:
- Webchat v3 — go to Webchat Behavior > Attachment Upload on the Endpoint Settings page. Activate the Allow Attachment Upload setting.
- Other Endpoints — go to the File Storage section on the Endpoint Settings page.
From the File Storage Provider list, select Google Cloud.
Next to Google Cloud Connection, click +.
In the New Connection window, fill in the following fields:
- Bucket Name — enter the bucket name that you copied and saved previously.
- Client Email — enter the email address that you copied and saved previously.
- Private Key — enter the key that you copied and saved previously.
Click Create, then Save.

After setting up, open the chat in test mode and upload a file to the chat interface by either dragging it from your computer or using the Attach file button. The file will begin uploading automatically.

To test file uploads for the Webchat v2 and Webchat v3 Endpoints, use Demo Webchat. For other Endpoints, testing only works in the production environment. Upload a file to the chat interface and go to the file storage on your provider's side. If the file appears in the storage, then file uploads work correctly.

Access Files in the Input Object¶

By default, uploaded files are recorded in the input.data.attachments array. Each file object in this array contains a file name, file type, and URL pointing to the uploaded file:

{
  "name": "example_file.png",
  "url": "https://example.com/uploads/example_file.png",
  "type": "image"
}

Use Cases¶

Use Case	Description	CognigyScript	Example Output
Confirm Uploaded Files	To ensure the user uploaded the correct file, display the file name for confirmation.	`{{input.data.attachments[0].name}}`	`example_file.png`
Provide the Direct File URL	Share the direct URL of the uploaded file with the user.	`{{input.data.attachments[0].url}}`	`https://example.com/uploads/example_file.png`
Validate Attachments	To check if a valid file has been uploaded in the most recent user input, verify the length of the `input.data.attachments` array.	`{{input.data.attachments.length}} > 0`	-

Resize Images¶

For image file types, such as JPEG, PNG, GIF, WebP, and others, you can automatically resize images based on the query parameters in the URL. The available parameters are in the table.

Query Parameter	Description
`maxWidth`	The maximum width of the image.
`maxHeight`	The maximum height of the image.
`maxFileSizeInBytes`	The maximum file size of the image, specified in bytes.

Use Cases¶

Use Case	Description	Example	URL Example
Use original Attachment URL	An attachment is uploaded with the original URL.	The image has dimensions of 3840 x 2160 and a size of 8 MB.	`https://files-trial.cognigy.ai/123/456/789`
Resize to Specific Dimensions	When `maxWidth` and `maxHeight` parameters are provided, the image will be resized to fit within those bounds while maintaining its aspect ratio.	To resize the image to a maximum of 640x480, append the `maxWidth` and `maxHeight` parameters.	`https://files-trial.cognigy.ai/123/456/789?maxWidth=640&maxHeight=480`
Limit File Size	If the `maxFileSizeInBytes` parameter is provided, the image quality is gradually reduced until the image file size meets the specified limit.	To ensure the image is less than 100 KB (102,400 bytes), use the `maxFileSizeInBytes` parameter.	`https://files-trial.cognigy.ai/123/456/789?maxFileSizeInBytes=102400`

HTTP Error Codes¶

Error Code	Description
`500`	Returns if the image can't be resized according to the specified parameters. For example, if the `maxFileSizeInBytes` can't be reached.