Deploy a Twilio Flex Web Chat Sandbox for Testing

Mindful Feedback allows you to quickly establish a sandbox implementation of the Twilio Flex web chat for testing. Use the steps below to set up a Twilio web chat sandbox:

Quick access: Settings > Customer Settings > Integrations > Configure Twilio Flex > WebChat Demo tab

• Account SID and Flow SID: You can find both of these on the Developer Setup page in Twilio Flex.
• Default web survey URL: Enter the URL of the web survey to use. See Add a Survey via Webhook for more information.

When finished, click Save Changes then click the Launch Demo button to open the demo page:

This page will contain a "Chat with us" button in the bottom-right corner. You can click this button to open a demo chat window connected to a Twilio Flex agent. When the chat ends, the web survey will appear.

Twilio Flex Web Chat Client Code Sample

You can access sample Javascript for each type of web survey implementation using the Example JS... links on the web chat demo page (see the previous screenshot).

The following code excerpt comes from the sample Javascript code provided by clicking the Example JS for chat window link. It consists of the standard Twilio Flex web chat sample JavaScript and some additional code provided by Mindful Feedback (as an example only).

The remainder of this section describes each area of the sample Javascript code.

// generates a UUID or grabs the existing sdxReference cookie if one exists
let SDX_Ref = uuidv4();
if (Cookies.get('sdxReference') && typeof Cookies.get('sdxReference') !== 'undefined') {
    SDX_Ref = Cookies.get('sdxReference');
}
function uuidv4() {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
        var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
        return v.toString(16);
    });
}

// replace with your own values
const FLEX_ACCOUNT_SID = 'Flex account sid'; //todo
const FLEX_FLOW_SID = 'Flex webchat flow sid'; //todo
const SDX_BASE_URL = 'Default survey URL, found under the Advanced tab of any Survey Management Page'; //todo
const SDX_URL_PARAMS = SDX_BASE_URL.includes('?') ? '&external_ref=' + SDX_Ref : '?external_ref=' + SDX_Ref;
const SDX_URL = SDX_BASE_URL + SDX_URL_PARAMS;

The uuidv4 function will generate a 16-digit UUID. The function is defined and invoked, and the returned value is assigned to a variable called SDX_Ref. This unique ID will become an attribute on the Twilio Flex task. Logic is included to ensure the value of SDX_Ref remains consistent after page refreshes.

The constants (such as FLEX_ACCOUNT_SID and FLEX_FLOW_SID) should be defined according to the details of your environment.

// Set up the Webchat configuration.
const appConfig = {
    accountSid: FLEX_ACCOUNT_SID,
    flexFlowSid: FLEX_FLOW_SID,
    context: {
        // The SDX_Ref needs to be passed in here and also needs to be connected to the Flex Task in the Studio flow.
        // Syntax and how to include context data in the Studio flow: https://www.twilio.com/docs/flex/webchat/pre-engagement-and-context#pre-engagement-and-context-data-in-studio
        friendlyName: "John Doe", //todo
        sdxReference: SDX_Ref,
    }
};
Twilio.FlexWebChat.renderWebChat(appConfig);

// Once the chat is opened, the sdxReference has been passed to Twilio and will persist through page refreshes
// We need the sdxReference on the browser to match, so an easy way is to store it as a cookie.
// Of course, you can ensure the sdxReference persists through refreshes using whatever method you want
Twilio.FlexWebChat.Actions.on('afterToggleChatVisibility', (payload) => {
    Cookies.set('sdxReference', SDX_Ref);
});

In the excerpt above, the Twilio Flex web chat is invoked. During invocation the SDX_Ref value is passed as sdxReference to the Twilio task. This will become a property that can be passed onward in the Send to Flex block within the task flow.

The last bit of the excerpt above sets a cookie after the web chat is initiated. This ensures that the value of SDX_Ref remains consistent.

// This code is used to determine when the web chat has ended. There may be a better way to do this
// It checks every second if the chat has ended and if it has, shows a survey and removes our saved sdxReference Cookie
let check_if_chat_ended;
check_if_chat_ended = setInterval(function () {
    let chat_ended_element = document.getElementsByClassName('MessageCanvasTrayContent');
    if (chat_ended_element.length) {
        clearInterval(check_if_chat_ended);
        Cookies.remove('sdxReference');
        showSdxSurvey();
    }
}, 1000);

A regular check is performed to see if the web chat has ended. When it has ended, the showSdxSurvey function is invoked to display the survey.

function showSdxSurvey() {
    let webchat_body = document.getElementsByClassName('Twilio-MessagingCanvas')[0];
    webchat_body.innerHTML = '';
    let iframe = document.createElement('iframe');
    iframe.setAttribute('id', 'sdx-survey-iframe');
    webchat_body.appendChild(iframe);
    iframe.setAttribute('src', SDX_URL);
    if(screen.width > 600) {
        increase_webchat_window_size(iframe);
    } else {
        iframe.style.height = '90vh';
    }
    iframe.style.width = '100%';
    iframe.setAttribute('class','survey-iframe'); //todo - add some CSS to the survey-iframe class if you want
}

function increase_webchat_window_size(iframe) {
    let webchat_container = document.getElementsByClassName('Twilio-MainContainer')[0];
    webchat_container.style.height = '600px';
    webchat_container.style.width = '600px';

    let messaging_container = document.getElementsByClassName('Twilio-MessagingCanvas')[0];
    messaging_container.style.height = '556px';
    messaging_container.style.width = '600px';
    // Hide the minimize button as it doesn't function properly when the chat window has changed size
    let minimize_button = document.getElementsByClassName('Twilio-Icon-Close')[0];
    minimize_button.style.display = 'none';
    iframe.style.height = '100%';
}

The two functions defined above are responsible for showing the web survey within the chat widget.

Configure Twilio Flex Survey Mapping in Mindful Feedback

After a customer has completed the survey:

• Twilio Flex will have a task record with an attribute named sdxReference containing a value such as "0812f7d0-834e-11ea-bcdb-0d29ea1301f4".
• Mindful Feedback will have a web survey interaction with an external_ref value that matches the sdxReference attribute: "0812f7d0-834e-11ea-bcdb-0d29ea1301f4".

As Mindful Feedback processes new Twilio Flex task data, a survey mapping defined for Match Only mode will sync data from the task onto the survey using a match on "sdxReference" = "external_ref".

Use the following steps to configure the survey mapping:

Quick access: Settings > Customer Settings > Integrations > Twilio Flex

1. On the Twilio Flex tab, click Configure Twilio Flex.
2. On the Configure Twilio Flex page (Configure Listening tab), scroll down to the Survey Mappings section.
3. Click Add Survey Mapping.
4. Complete the survey mapping as seen in the example above:
   • Description: Enter a description for the survey mapping.
   • Survey: Select the survey to which the mapping will apply.
   • Conditions: No conditions are needed for this mapping.
   • Survey Parameters: Select the Type and Value for all attributes required for the selected survey.
5. In the Match Conversations With Existing Survey Interactions section, configure the fields as shown in the example below:
   • Mode: Match Only
   • Conversation attribute: sdxReference (remember that you must define this as an attribute in the Send to Flex block of the web chat Studio Flow so that Twilio Flex can update the value.
   • Existing conversation attribute: External Reference