SendSafely Dropzone Modal (Beta)

The SendSafely Dropzone Modal (DZ Modal) is a client-side Javascript component that allows you to add a modal window containing a SendSafely Dropzone to any web page. The DZ Modal was specifically designed to facilitate integrating SendSafely with chatbots, since it can provide a seamless upload experience to users that are actively engaged in a chat conversation. 

This article provides an overview of how to integrate and use the DZ Modal. 

Installing the DZ Modal 

The preferred method for loading our DZ Modal code is to have your website reference the code directly from our website. By doing that you will ensure that you are always using the most up-to-date version. 

The code can be referenced by adding the following line to your HTML page:

<script src="https://files.sendsafely.com/js/SendSafelyDropzoneModal.js" type="module"></script>

Initializing the DZ Modal 

Once the DZ Modal JavaScript file is loaded into the page, you will need to initialize the modal. There are four steps required to initialize:

• Create a new DZ Modal instance
• Specify optional configuration parameters
• Specify callbacks for open/close/success/error events  
• Initialize the instance 

The following code example shows how to load and initialize the DZ Modal:

const myDropzoneModal = new SendSafelyDropzoneModal({

  // Required configuraiton parameters: SendSafely Dropzone ID and Portal URL   
  dropzoneId: 'put-your-dropzone-id-here',
  url: 'https://app.sendsafely.com', 

  // Callback after a drop zone submission is made 
  onUploadComplete: (url) => {
    console.log('Upload completed:', url);
  },

  // Callback if an error occurs during upload or submission  
  onUploadError: (errorType, errorMessage) => {
    console.error('Upload failed:', errorType, errorMessage);
  },

  // Callback when the modal is opened   
  onModalOpen: () => {
    console.log('Modal opened')
  },

  // Callback when the modal is closed without submitting  
  onCancel: () => {
    console.log('Modal closed');
  }

});

If the email address of the end-user is known, you can also pass this information to the modal so that it gets captured when files are uploaded. The optional submitterEmail configuration parameter can be passed in when initializing the modal, or the setSubmitterEmail() function can also be called at any time before files get uploaded. 

Submitting files with the DZ Modal

Once the modal is initialized, the modal can be launched programmatically by chatbots that support triggering client-side events by invoking showModal().  By default the modal will appear in the center of the screen with options to submit and cancel as shown below. 

By default, at least one file must be attached on each submission. 

• If the user chooses "Cancel" or presses the "x" to close the modal, the modal will close and the onCancel callback will be invoked. By default, the state of the modal is preserved. You can choose to reset the modal within the onCancel callback by calling resetDropzone().
• After attaching file(s) and pressing submit, the files are submitted and the onUploadComplete callback will be invoked. The hideModal() and resetDropzone() functions are automatically called to return focus back to the original window and reset the Dropzone so that it can be used again as needed.
• By default, any Dropzone Connectors that are configured for the Dropzone will automatically run when files are submitted. This behavior can be changed by setting the optional invokeDropzoneConnectors: false configuration value when initializing the modal. 

Using the Upload Button (optional) 

For some workflows, you may want to provide the user with an option to upload files at any point during a conversation. The "Upload Button" is an optional UI element that can be attached to the chat interface and allows the end-user to launch the Dropzone Modal at any point. 

The upload button can be shown and hidden by calling showUploadButton() and hideUploadButton() respectively. 

• The show/hide functions should be called any time the chat widget is opened/closed by the user. Most chatbots have built-in functions that allow you to invoke code in response to these two events.  
• If you want to use the Upload Button and your chatbot does not have functions to invoke code in response to show/hide, refer to the Appendix section of this document.
• The Upload Button will require custom CSS styling to position and size the button correctly. The uploadButtonStyle configuration parameter can be used to set all of the button CSS properties when initializing the modal. 

Handling Dropzone Submissions

Once files are submitted to the Dropzone, you'll need to make sure the conversation is updated. This can typically be done in one of two ways:

• Using a Dropzone Connector - If the conversation can be updated programmatically through a REST API, we recommend obtaining the conversation ID from the chat widget and passing it to the Dropzone using setPackageLabel(). The package label is automatically passed to any configured Dropzone Connectors, so the connector can update the conversation after the files are submitted.
• Using your Client-Side Chatbot SDK - If your chatbot SDK supports passing metadata back to the conversation, you can invoke this functionality within the onUploadComplete callback. The secure link to the uploaded files is passed to the callback function so that you can then use it as needed within the function. If you use this approach you may want to set the optional invokeDropzoneConnectors: false configuration value when initializing the modal. 

Refer to the following articles for a complete end-to-end example using real world chatbots:

• Forethought AI
• Ada Chat (Coming Soon)
• Amazon Connect (Coming Soon)
• Zendesk (Coming Soon) 

Appendix - API Reference  

API Methods

Available methods for controlling the modal programmatically:

• showModal() — Open the upload modal
• hideModal() — Close the upload modal
• showUploadButton() — Show the floating upload button
• hideUploadButton() — Hide the floating upload button
• setPackageLabel() — Used to set the package label after initialization
• setSubmitterEmail() — Used to set the submitter email after initialization
• updateConfig(newConfig) — Update modal configuration
• destroy() — Remove modal and clean up
• resetDropzone() — Reset the modal Dropzone

Configuration Options

Option	Type	Default	Description
dropzoneId	string	'sendsafely-dropzone-id'	Required. Unique SendSafely Dropzone Identifier
url	string	'https://demo.sendsafely.com'	SendSafely portal URL
invokeDropzoneConnectors	boolean	false	Invoke SendSafely Dropzone Connector
buttonText	string	'Upload a File'	Upload button text
buttonIcon	string	'Url or SVG Data'	Upload button icon
uploadButtonStyle	object	{ bottom: '22px', right: '24px', position: 'fixed',width: '25rem' }	Upload Button CSS properties (launches the modal)
submitButtonStyle	object	{ backgroundColor: '#eee', color: "#333", padding: "10px 18px"}	Submit Button CSS properties (shown on the modal)
cancelButtonStyle	object	{ backgroundColor: '#007bff', color: "#333", padding: "10px 18px"}	Modal Cancel Button CSS properties (shown on the modal)
modalTitle	string	'Secure Attachments'	Modal window title
packageLabel	string	''	Package Label (optional)
submitterEmail	string	''	Submitter email address (optional)
showSubmissionConfirmation	boolean	false	Show successful submission modal after upload
showSubmissionId	boolean	false	Show submission ID after upload
onUploadComplete	function	null	Called when upload succeeds
onUploadError	function	null	Called when upload fails
onModalOpen	function	null	Called when modal is opened
onCancel	function	null	Called when modal is closed without submitting files