Scheduler runtime developer guide

In addition to the Widget settings that can be configured in the Mindful Callback user interface, some Widget actions can also be customized at runtime on your website.

When the required vht-conversation-bridge-runtime.js script has been executed on your website, it will automatically scan for HTML elements that define Widgets. It will then initialize each Widget it finds. The script also adds a new JavaScript object named vhtConversationBridgeClient to the global scope (window.vhtConversationBridgeClient). The properties and functions of this object can be used to further refine the behavior of your Widgets.

Overview

This runtime developer guide covers the following components of the global vhtConversationBridgeClient object:

  • Functions
  • Properties
  • Events

Functions

FunctionDescription
.initialize()This function will re-scan the DOM for widget elements and initialize them. This function is called automatically when the vht-conversation-bridge-runtime.js script is finished loading and can be called manually if Widget elements are dynamically added to the DOM after script load.
.destroy()This function will remove all previously initialized Widgets from the DOM and unregister their event handlers. Its primary use is to ensure that a view is properly cleaned up in a single-page application.
.update()This function will cause all initialized Widgets to request an update of their data. Normally a Widget will reload its own data periodically (see the updateInterval property) and this function would not need to be called manually.

Properties

PropertyData typeDescription
.updateIntervalnumberThe amount of time in milliseconds that a Widget should wait between data refresh requests. The default is 5000 ms (5 seconds).
.defaultSubmitErrorMessagestring
  • This message is shown to the user if the Widget cannot communicate with the Scheduler API while attempting to submit a callback request. Communication failures can occur if there is a network connectivity error or if the API is momentarily unresponsive.?
  • Defaults to "Unable to submit request. Please try again later."
.noFocusUpdateIntervalnumber
  • The interval at which the Widget will request updates from the server when the host page does not have focus or is otherwise running in the background
  • Defaults to 60000 ms (60 seconds)
.inactiveWidgetUpdateIntervalnumber
  • The interval at which the Widget will request updates from the server after a period of inactivity
  • Defaults to 60000 ms (60 seconds)
.inactiveWidgetTimeoutnumber
  • The amount of time with no activity on the page before the Widget is declared inactive and it starts updating at the rate specified by inactiveWidgetUpdateInterval
  • Defaults to 3600000 ms (1 hour).
.widgetExpirationTimeoutnumber
  • Once a Widget reaches this age, it is disabled. The server-generated Widget content is removed from the page and replaced with whatever fallback Widget contents were served with the page (if any). The widget also stops making requests to the server.?
  • Defaults to 86400000 ms (24 hours)

Events

By assigning a function to the following event properties, you can customize the way Widgets operate.

Note:

Assigning a function as an event handler will replace the existing default handler. To preserve the default behavior, you can assign a handler function that calls the original function. Consider the following example, which performs the default action in addition to a custom action when a Widget submits a callback request:

Text
const defaultSubmitStartHandler = window.vhtConversationBridgeClient.events.submitStart; window.vhtConversationBridgeClient.events.submitStart = function() {    console.log("Submitting a callback request");      // custom action    defaultSubmitStartHandler.apply(this, arguments);  // also call default action };
EventRelated functionDescriptionArguments
.events.widgetInitializedfunction(widgetElement, widgetInstance)
  • Called when a widget is initialized
  • The initial request for data will have been made asynchronously before this event is triggered, but may not have been completed. Thus, Widget data may not yet be visible.?
  • widgetElement: The DOM element that represents the Widget
  • widgetInstance: The Widget instance
.events.widgetDestroyedfunction(widgetElement, widgetInstance)Called when a Widget is destroyed (refer to the .destroy() function)?
.events.submitStartfunction(widgetElement)Called when the user clicks the Submit button in a Widget to request a callback
  • widgetElement: The DOM element that represents the Widget
  • XMLHttpRequest: The XMLHttpRequest object that was used to make the request
.events.submitSuccessfunction(widgetElement) function(widgetElement, XMLHttpRequest)Called when a callback request has been successfully submitted to Mindful
.events.setUserDatafunction(widgetId)
  • Called when the user clicks the Submit button in a widget to request a callback?
  • Override this function and return a JavaScript hash of key-value pairs to include as custom user data for the callback request. The user data will be attached to the callback request and can be used as an input to your telephony platform to populate screenpop displays or affect call routing.
widgetId: The ID of the Widget

Example

The following example uses the setUserData event to populate a user email and account number:

window.vhtConversationBridgeClient.events.setUserData = function() {  
	return {    
		userEmail: "customer@domain.com",    
		accountNumber: "123456"  
	};
}