Using the Dropzone Modal with Ada & Handoff to Zendesk – Online Help Center

This article walks through how to use the Dropzone Modal in conjunction with a chatbot live agent handoff to another messaging platform. Doing a live agent handoff can add complexity to your integration since the modal needs to be able to communicate with the chat widget before and after the handoff occurs.

This example builds on our original example for integrating with Ada Chatbot. In this example, the Ada Chatbot will do a live agent handoff to Zendesk Messaging when the conversation requires escalation to a human.

Pre-handoff Integration

Before the handoff occurs, the integration works identically to what is described in our original example. The end-user can upload files at any time using a button that is displayed at the bottom of the chat window.

In order to facilitate uploads after the handoff occurs, the following enhancements need to be made to the original example:

The Ada Conversation Id associated with the conversation is passed to Zendesk as a custom ticket field during the handoff process.
When files are uploaded, the Ada Conversation Id is also passed to the Dropzone using the PackageLabel field, making it available for use by a Dropzone Connector
A Dropzone Connector is used to lookup the ticket/conversation using the Conversation Id, allowing the conversation to be updated using the Zendesk API after the handoff occurs.

Configuring the Handoff

The first update that needs to be made is to configure the handoff from Ada to Zendesk. Within Zendesk you'll need to add a custom ticket field to store the Ada Conversation Id. In our example, we define a text field named ss_conversation_id as shown below.

You'll also need to update the handoff logic in Ada to populate this new field with Ada's "conversation_id" when the handoff occurs.

Updating the Modal Integration Logic

Next, you'll need to update the Dropzone Modal integration logic to pass the Ada Conversation ID to the Dropzone.

A new ss_conversation_id variable will be used to track the Ada conversation Id so that it can be passed to the Dropzone.
In order to support persistent conversations, we will also store the variable in local storage.
The optional packageLabel configuration property is used to pass the value to the Dropzone.

let myDropzoneModal = null;
var ss_conversation_id = localStorage.getItem("ss_conversation_id");

function createDropzoneModal() {
    return new SendSafelyDropzoneModal({
        dropzoneId: 'PUT_YOUR_DROPZONE_ID_HERE',
        url: 'https://PUT_YOUR_SENDSAFELY_HOSTNAME_HERE',
        packageLabel: ss_conversation_id,
        buttonStyles: {
            maxWidth: '375px',
            height: '48px',
            background: 'rgb(123, 82, 194)',
            bottom: '8px',
            right: '24px',
            boxShadow: 'rgba(0, 0, 0, 0.12) 0px 12px 48px 4px',
            borderRadius: '0 0 16px 16px',
            color: '#ffffff',
        },
        onUploadComplete: (url) => {
            window.adaEmbed.setMetaFields({
                ss_secure_link: url
            }).then(() => {
                setTimeout(() => {
                    window.adaEmbed.triggerAnswer('PUT_YOUR_ADA_PROCESS_ID_HERE');
                }, 1000);
            });
        },
        onUploadError: (errorType, errorMessage) => {
            //This should generally never happen. 
            alert('SendSafely upload failed: ' + (message || type) + ". Please notify the agent.");
        }
    });
}

In addition to the above updates, you will also need to add new logic that monitors the ada:conversation:message event to check the current conversation id and update the local variable if the value does not match.

adaEmbed.subscribeEvent('ada:conversation:message', (data) => {
    if (data.conversation_id && (ss_conversation_id !== data.conversation_id)) {
        ss_conversation_id = data.conversation_id;
        localStorage.setItem("ss_conversation_id", ss_conversation_id);
    };
});

Installing the Dropzone Connector (AWS Lambda)

The last update that needs to be made to facilitate the handoff is to install and configure the SendSafely Dropzone Modal Connector for Zendesk. When files are submitted to the Dropzone, the connector uses the Zendesk REST API to query the conversation or ticket that has the ss_conversation_id field set to the current conversation. If one is found, the conversation is updated programmatically via the Zendesk API. If one is not found, the onUploadComplete callback updates the conversation using Ada's adaEmbed.triggerAnswer function instead.

NOTE: The Dropzone Connector is installed using AWS CloudFormation. In order to perform the install you will generally need elevated AWS permissions/admin. The CloudFormation template be obtained by emailing success@sendsafely.com.

The steps for installing and configuring the Dropzone Modal Connector are the same as our normal Dropzone Connector for Zendesk except for the zendeskUsePublicComments configuration variable (this variable is not used by the modal and can be ignored).

These instructions can be found in Steps 1 through 7 of this article.

Uploading a file after the Live Agent Handoff

Uploading a file after the live agent handoff works the same way as when conversing with the chatbot. We recommend that after the setup is complete, you perform a test upload both before and after the handoff to make sure the flow is functioning as expected.

Complete Example Code

The full HTML from the example above is included below for reference. You will need to update the example to use a valid Ada Handle, SendSafely Dropzone ID, and Ada Process ID.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Ada SendSafely Example</title>
    <base href="/">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://files.sendsafely.com/js/SendSafelyDropzoneModal.js" type="module"></script>
    <style>
        #ada-chat-frame {
            bottom: 52px !important;
            z-index: 990 !important;
            border-radius: 16px 16px 0 0 !important;
            height: calc(100% - 52px) !important;
        }
    </style>
  </head>
  <body>
    <script id="__ada" data-handle="PUT_YOUR_ADA_HANDLE_HERE" src="https://static.ada.support/embed2.js"></script>

    <script type="text/javascript">
    
        let myDropzoneModal = null;
        function createDropzoneModal() {
            return new SendSafelyDropzoneModal({
                dropzoneId: 'PUT_YOUR_DROPZONE_ID_HERE',
                url: 'https://PUT_YOUR_SENDSAFELY_HOSTNAME_HERE',
                uploadButtonStyle: {
                    maxWidth: '375px',
                    height: '48px',
                    background: 'rgb(123, 82, 194)',
                    bottom: '8px',
                    right: '24px',
                    boxShadow: 'rgba(0, 0, 0, 0.12) 0px 12px 48px 4px',
                    borderRadius: '0 0 16px 16px',
                    color: '#ffffff',
                    position: 'fixed'
                },
                onUploadComplete: (url) => {
                    window.adaEmbed.setMetaFields({ ss_secure_link: url }).then(() => {
                        setTimeout(() => {
                            window.adaEmbed.triggerAnswer('PUT_YOUR_ADA_PROCESS_ID_HERE');
                        }, 1000);
                    });                    
                },
                onUploadError: (errorType, errorMessage) => {
                    //This should generally never happen. 
                    alert('SendSafely upload failed: ' + (message || type) + ". Please notify the agent.");                    
                }
            });
        }

        window.adaSettings = {
            onAdaEmbedLoaded: () => {
                window.adaEmbed.setMetaFields({ ss_secure_link: null });

                adaEmbed.subscribeEvent('ada:end_conversation', (data) => {
                    window.adaEmbed.setMetaFields({ ss_secure_link: null });
                });

                adaEmbed.subscribeEvent('ada:close_chat', (data) => {
                    myDropzoneModal.hideUploadButton();
                });
            },

            toggleCallback: function (isDrawerOpen) {
                if (isDrawerOpen) {
                    if (myDropzoneModal)
                    {
                        //Reset the existing one
                        myDropzoneModal.resetDropzone();    
                        myDropzoneModal.showUploadButton();
                    }
                    else
                    {
                        //Wait for the iFrame to appear and then create a new one 
                        SendSafelyDropzoneModal.watchForElement('ada-chat-frame',function(node) {
                            myDropzoneModal = createDropzoneModal();
                            myDropzoneModal.showUploadButton();
                            if (node.style.height === "100%")
                            {
                                //Iframe is in full screen mode
                                var button = document.querySelector('.sendsafely-upload-btn');
                                button.style.width = "100%";
                                button.style.maxWidth = "100%";
                                button.style.bottom = "4px";
                                button.style.right = "0px";
                            }
                        });
                    }
                } else {
                    myDropzoneModal.hideUploadButton();
                }
            }
        };
        
    </script>
  </body>
</html>

Articles in this section