Getting Started with Scheduler Widgets

The Scheduler Widget is the preferred callback widget plugin for use in the Mindful ecosystem. The Scheduler Widget can be used on your website to offer ASAP or scheduled callbacks, making the customer experience more convenient when using a web browser or mobile device.  

Mindful Scheduler offers a wide range of options to customize your web Widgets to look, feel, and function just the way you want. In this guide, we will walk through the process of setting up new Widgets, testing them, and deploying them on your website or mobile application.

Overview

This quick-start guide walks through the following steps to help you quickly set up and deploy Widgets.

• Background
• Step 1: Create and configure a template
• Step 2: (Optional) Create a User Data Set
• Step 3: (Optional) Create an Access Control Policy
• Step 4: Create and configure a Widget
• Step 5: Test and embed a Widget
• Step 6: Analyze Scheduler interactions in reports
• (Optional) Use Intents to dynamically select Widgets
• (Optional) Leverage Messaging Automation for multi-modal Widget scheduling
• Next Steps: Mindful API

Background

Mindful Scheduler provides a quick way for web developers to create and embed a "Call Me" widget on your web page. We recommend that your organization uses Scheduler in a few common scenarios.

Scheduler Use Cases

There are two basic use cases to leverage your integration with the Scheduler platform:

• "Call Me" widget embedded on your web page
• REST API invoked from your application

Built-in Rate Limiting

In the following diagrams, a single IP address places too many callback requests via Widget in quick succession. Mindful identifies the incoming source by the requestor's IP address, and blocks requests from that source once the rate limit is reached.

What happens once the rate limit is met?

Once the max number of requests within a defined timespan has been reached:

• The individual placing the callback requests via your web Widget will see an error message in the Widget letting them know they've exceeded their maximum requests 
• The Scheduler application will prevent additional callback requests from being registered in the callback registration queue.

Step 1: Create and Configure a Template

Before creating a Widget, you must first configure a template to apply to the Widget. Templates control the visual presentation and formatting of the Widgets to which they are applied. Storing such visual configuration in templates, outside of the Widgets themselves, allows you to store sets of configured options to apply to several Widgets at once.

Create a New Template

Quick access: Scheduler > Templates tab

1. To create a new template with the default configuration, click Add Template, or... 
2. To begin by using an existing template's configuration to create a new one, find the template you wish to copy, then click the Clone icon. 
3. If you have created a new template rather than cloning, enter a name and description in the fields provided, then click Save Template.
4. Locate your new template on the Templates page, then click the Edit icon in its row to open the Edit Template page.
5. Edit the information in each of the following sections on the Edit Template page:
   • Template Details: Set the internal name and description of your template.
   • HTML: Customize the HTML code used to display buttons and text.
   • Callback Form: Customize the options and inputs provided to customers to help them request a callback.
   • API Message: Edit the default API responses that the template uses to communicate with your application. 
   • EWT Format: Customize the way that the Estimated Wait Time is presented.
   • Error Messages: Customize various error messages displayed to customers in specific scenarios.
   • Date/Time Format: Customize the way that dates and times are presented.

Step 2: (Optional) Create a User Data Set

User Data Sets allow you to define a set of key-value pairs (KVPs) that can be sent by a Scheduler Widget to Mindful. 

A User Data Set allows Mindful to receive data, but you must still configure a Metadata Item for your Call Target in order to pass the data on to the call center. For more information on configuring Metadata items, see How to Work With User Data and Metadata.

Use the steps below to create a User Data Set:

Quick Access: Scheduler > User Data Sets

1. Click Add New User Data Set to open the Create Scheduler User Data page.
   • Name: Enter a name to identify the User Data Set.
   • Description: Enter a description to define the purpose of the User Data Set.
2. Click Add New Key to add the first KVP.
3. In the modal window that appears, enter a Key Namefor the KVP. 
   • This name must precisely match the KVP that will be received by the Widget.
4. Enter a value in the Default Valuefield, if applicable. 
   • This value will be assigned to the KVP if no value is received.
5. If you wish to replace any value that is submitted for this KVP with the specified default value, enable the Replace Value from Widget with Default Value checkbox.
6. Click Save to save the User Data Key, then repeat this process for all remaining keys you wish to define for the User Data Set.

Step 3: (Optional) Create an Access Control Policy

You can use Access Control Policies with your Scheduler Widgets when all of your callback-request traffic will be routed through your own web servers. This creates a secure lane allowing all traffic from approved IP addresses to safely pass through the Scheduler Widget for processing, while any traffic not found in the ACP is blocked. 

You can create new ACPs in two different ways. You can start fresh with a new, empty policy, or clone an existing policy to start with an existing list of allowed IP addresses. If you choose to clone an existing ACP, you can then add or remove IP addresses from the new policy as needed to fit its intended purpose.

Follow the steps below to create a new ACP.

Quick Access: Scheduler > Access Control Policies

1. To create a new ACP with nothing configured, click Access Control Policy, or...
2. To use an existing ACP as a template for the new one, click the Clone icon in the row corresponding to the policy that you wish to clone. 
3. Enter a unique name for the new policy in the Name field.
4. (Optional) Enter a description to further identify the new policy in the Description field.
5. If you are cloning an existing ACP, click Save, then click Edit on the new row associated with the policy to continue.
6. Click Add Whitelisted IP Address to add an IP address.
7. In the Add Whitelisted IP Address to Access Control Policy modal window, enter the IP address in the Address field. If you wish to use the IP address of the server you are using to access the Callback user interface, click Use my IP address to automatically populate it in this field.

8. (Optional) Enter descriptive text to identify the server in the Description field.
9. Click Save to return.
10. Repeat Steps 6-9 for any additional IP addresses you would like to add to the new ACP, then save your changes.

You can return to any previously created Access Control Policy to make updates, as well.

Step 4: Create and Configure a Widget

With your Template complete, and possibly an Access Control Policy, you can now proceed to set up a new Scheduler Widget. 

Create a New Widget

Quick Access: Scheduler > Widgets

The Add Widget button allows you to create a new Widget and configure it at the same time. Use the following steps to create and configure a Widget.

1. Click Add Widget to open the Create Scheduler Widget page.

2. Provide the necessary input:
   • Name: Provide a unique name for your Widget.
   • (Optional) Public Name: Provide a publicly visible name for your Widget. If you do not provide a name, the name from Step 1 will be used as the publicly displayed name.
   • Description: Provide a description of the Widget's purpose.
   • Enable Digital Callback Widget: Only select this option if you are ready for Mindful to start actively using your Widget.
   • Callback Type: Select ASAP, Scheduled, or Both.
   • Template: Select the Template you would like to use as the basis for this new Widget.
   • Call Target: Select the Call Target you would like to assign to this new Widget. Any callbacks requested by the Widget will be handled by the selected Call Target.
   • (Optional) User Data Set: Select a User Data Set to apply to the Widget, if you have created one.
   • (Optional) Access Control Policy: Select an Access Control Policy to apply to the Widget, if you have created one.
3. When finished, click Save.

You should now see your new Widget listed on the Scheduler Widgets page.

Tips for Configuring Widgets

Expand the content below for configuration tips for different components of your Widget.

Callback Type

Layout Style

Callback Offer and Registration Form

Response

A response is a message displayed on the Widget that confirms your customer's callback selection and anticipated callback time.

Customize Your Responses

For this, we're going back to the Scheduler Template you created earlier.

Quick access: Scheduler > Templates

1. In the row of the template you just connected to your Widget, click the Edit icon.
2. Click the HTML link to configure the message your customers will see in the Widget after they have requested a callback.
3. Scroll down to the following to customize your messages. Note that only one message will be used per interaction, based on what is being offered:
   • Offer ASAP Callback Requested HTML
   • Offer ASAP Callback Only
   • Scheduled Callback Requested HTML
   • Display Estimated Wait Time Only HTML
   • Platform Unavailable HTML: This message will display when the Mindful Callback is unavailable for receiving or processing callback requests.
4. Preview your HTML messages in any website by clicking the Preview button and following the on-screen prompts. Close the Preview window when you're done testing.
5. When finished, scroll to the top of the page and click Save.

Using Dynamic Text Replacement

Near the text fields, you will see a list of buttons labeled Available Components. You can click any of these buttons to add the corresponding component, such as a specific input field, button, or message.

• ewt: The current Estimated Callback Time (ECBT)
• projected-answer-time: The time of day that customers can expect a callback (current time + ECBT)
• popup-callback-form-button: Adds a Request a Callback button
• inline-callback-form: Adds a Callback Request form directly into the code, which includes an input field for a customer phone number and a Submit button
• contact-number-input: Adds an unlabeled input form for a customer phone number
• contact-number-submit: Adds a Submit button to connect with a customer phone number input form
• callback-request-error-message: Populates an appropriate error message (configured in the Error Messages tab) if an error occurs
• working-spinner: Displays a spinning circle when the Widget is awaiting the final status of the callback request

• contact-number-confirmation: Displays the submitted customer contact phone number via text
• appointment-time: Displays the scheduled callback appointment time via text

EXAMPLE

The following example uses several components to personalize a notification message:
In this example, the customer would see something like the following:

View API Endpoints and Parameters For Testing

Quick Access: Scheduler > Widgets > API Endpoints

You can test the functionality of your Widget in a command-line environment with the information in the API Endpoints modal window. Click API Endpoints in the appropriate row on the Widgets page to view this information for a particular Widget. These endpoints can also be used to invoke the API to request callbacks directly in your own application.  

To learn more about using the API endpoints and parameters, see our API Documentation.

Step 5: Test and Embed a Widget

Quick Access: Scheduler > Widgets > Your Widget > Embed icon

The Embed icon opens the Embed HTML modal window and allows you to preview your Widget. The window also contains the HTML elements required for connecting the Widget to your website. 

1. Styling

Select the Enable default theme and styling checkbox if you would like to add a link to a default stylesheet into the code in Box #2, to be included in the <head> element of your HTML code. If the checkbox is deselected, you will need to apply your own CSS styling.

2. Embed Tags in Code

This section includes three blocks of HTML that must be copied into the HTML code of the website on which you plan to deploy the Widget. Follow the instructions on the page to place the three elements in the correct locations in your code.

3. Preview Bookmarklet

This section includes a button labeled <Your Widget> Preview that will allow you to embed a preview of the Widget directly on any webpage. This includes previewing the button on the webpage where the Widget will eventually live. This allows you to preview the visuals and test functionality without any changes to your existing webpage.

Use the following steps to preview a Widget.

1. Click and drag the preview button to the bookmarks bar in your web browser. 
   • You should see a new bookmark saved with the name of your Widget.
2. Open any webpage, either locally or via the internet, on which you would like to preview the Widget.
3. Click the saved bookmark, then click anywhere on the webpage that you would like to place the preview.

You should see the Widget preview loaded in the area of the webpage that you clicked. You can then interact with the Widget to review its styling, functionality, and dialogue steps.

Step 6: Analyze Scheduler Interactions in Reports

On the Call Detail page, select Web in the Source filter to view only Scheduler interactions. To confirm that an interaction came from a Scheduler Widget, look for source: CBWidget for any interaction on the Call Detail page. The example in this section shows a scheduled callback registered through a Widget.
On the Executive Summary dashboard (located on the Insights page), next to the Aggregate Volume graph, concentrate on the Digital section to view the number of callbacks requested via Widget. You can also see the percentage of digital-channel requests compared to the voice and messaging channels here.

(Optional) Use Intents to Dynamically Select Widgets

Scheduler Intents allow you to create interactive dialogues to determine a customer's needs before offering a callback via web Widget. 

You can use Intents to ask a series of questions that will determine which Widget to use to request a callback. Customers can interact with an Intents dialogue in a single place, and they will be able to register a callback on different Call Targets based on their responses. To learn more, see Scheduler Intents.

(Optional) Leverage Messaging Automation for Multi-modal Widget Scheduling

Rather than scheduling callbacks through an interactive dialogue in the voice menu, you can alternatively offer your customers the option to schedule callbacks via SMS messaging. This multi-modal approach begins in the voice menu, transitions to messaging, and ultimately schedules a callback via a Widget on a customer's smartphone. When enabled, customers in the voice menu will be given the option to receive a message to schedule a callback. If they accept, they will receive an SMS message with a secure link to a Scheduler Widget. They can then interact with the Widget directly on their smartphone to schedule their callback.

For complete instructions to implement this feature, see the related section in How to Offer Scheduled Callbacks on a Call Target .

Next Steps

Scheduler Widgets offer more functionality than just scheduling callbacks. For example, you can send request to the Get Widget Status API endpoint of a Widget to obtain the status of its associated Call Target. To learn more about the Mindful API, including all Scheduler-related endpoints, see our API documentation.