Contact usRequest a demo

File upload configuration

Agents and visitors can upload files to conversations. However, you may want to restrict the types of file that they can upload. This article describes how to do so.


Being able to exchange files in a chat conversation is a highly useful feature that most people take for granted. However, it can pose a security risk:

  • Participants from outside your network might try to send malicious content to your agents and getting them to inadvertently compromise your network’s security.

  • Agents may inadvertently upload the wrong file to a conversation and thus share confidential information with unauthorized parties.

File upload checks

Unblu provides a number of configuration properties to mitigate the risks outlined above.

You can define lists of file types that users may and may not upload with com.unblu.filemanager.fileTypeBlacklist and com.unblu.filemanager.fileTypeWhitelist, respectively.

The configuration reference lists the possible values for both properties.

To make configuration easier, you can use groups of values for related file types:

  • GROUP_ANY is a pseudo-group that matches any file type. If your blacklist or whitelist is empty, it will be treated as if its value were GROUP_ANY.

  • GROUP_EXEC contains file types for executable files such as .exe, .bin or .app.

  • GROUP_IMAGE includes file types for common image file formats such as .png or .jpg.

  • GROUP_OFFICE contains types for files created by a variety of office software suites, for example .docx, .xlsx or .odt.

  • GROUP_PDF is used for PDF files.

Files uploaded to Unblu are checked against the file types in the blacklist and whitelist you specify. (File types are a combination of a file’s signature and their extensions, that is, the part of the file name after the final period.) If Unblu finds a match for the uploaded file in the blacklist, it won’t allow the user to upload the file. If it finds a match in the whitelist, the user will be allowed to upload the file.

Unblu always checks both the blacklist and the whitelist for matches.

What happens if Unblu finds a match in both the blacklist and whitelist? That depends on the configuration property com.unblu.filemanager.fileTypeBlackWhiteOrder:

  • If the configuration property has the value BLACK_WHITE, the file is checked against the blacklist first, then against the whitelist. If Unblu finds a match in both the blacklist and the whitelist, the match in the whitelist wins.

  • If the configuration property has the value WHITE_BLACK, the file is checked against the whitelist first, then against the blacklist. If Unblu finds a match in both the blacklist and the whitelist, the match in the blacklist wins.

You can use this behavior to your advantage, as you will see in the examples below.

Finally, you can encourage users only to upload files of certain types using the configuration property com.unblu.filemanager.fileTypeInputTagHint. Depending on the system the user is, this will restrict the kind of file they can choose to upload. In the visitor UI, for example, it adds an accept attribute to the send file icon Send file icon. Often, however, users can work around this limitation with little effort; it adds convenience rather than security.


Suppose you only want to allow users to upload PDF files and images in the PNG format. You also want to make it harder for them to choose other kinds of file to upload. You could use the following configuration:

Listing 1. File upload configuration example 1

In this configuration, the blacklist is evaluated first, then the whitelist. The blacklist blocks all file uploads. Then the whitelist allows users to upload the file types we want. Finally, the hint sets the accept attribute to discourage users from uploading files of any other type.

Now suppose you only want to block uploads of executable files. The following setup would achieve this:

Listing 2. File upload configuration example 2

Here, the whitelist is evaluated first and allows the upload of all file types. However, when the blacklist is evaluated, it blocks all the file types in GROUP_EXEC. A hint regarding the file types users may upload makes less sense in this case, so we can leave the configuration property for it blank.

Scanning file uploads for viruses

To scan files uploaded via an Unblu UI for viruses, you can use file interceptors.

If file interceptors aren’t a suitable option for your organization, you need a reverse proxy in place between the individual uploading the file and the Unblu server. The reverse proxy must be configured so that POST requests to a URL matching the following pattern are validated:

Listing 3. Regular expression that should trigger file validation by the reverse proxy

Replace <path-prefix> in the regular expression above with the appropriate prefix value:

The file that needs validating is the payload of the POST request. The reverse proxy should pass it to the validation mechanism your organization has in place.

How the reverse proxy proceeds once the file’s been validated depends on the outcome of the validation process:

  • If validation is successful, it should send the uploaded file to the Unblu server.

  • If the validation process determines that the file is too large, the reverse proxy should respond with a 413 Request Entity Too Large error. The file mustn’t be uploaded to the Unblu server.

  • If the validation process detects an issue with the file—​for example, if the file contains a virus--, the reverse proxy should respond with a 415 Unsupported Media Type error. Again, the file mustn’t be uploaded to the Unblu server.

  • If validation fails for any other reason, the reverse proxy should respond with a general 400 Bad Request error and not upload the file to the Unblu server.

See also