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.
Important: Scheduler Widgets require a Call Target to manage the callback requests. If you have not already set up a call target, see How to Set up a Call Target before proceeding.

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 theScheduler 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.

diagrams demonstrating rate limiting behavior

What happens once the rate limit is met?

Once the max number of requests within a defined time span 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.
Note: For additional security, we recommend using a single web server (or a small number of redundant servers) to make API requests to Scheduler Widgets. By configuring an Access Control Policy (ACP), specific IPs can be allowed to make unlimited requests to any Widget with that ACP assigned.Now that we have opened our API endpoints for web servers to access them, you can utilize Scheduler on the back end for large-scale call processing. Here's how the callback request flow will look:

diagram illustrating ACP whitelisting

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.
Note: Widget template configuration cannot be edited if the template is currently applied to a Widget.

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 Policieswith 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.

Note: This section only describes the process of adding IP addresses to an ACP to allow unlimited traffic from specific sources. However, you can also generate an API Access Token within an ACP to allow unlimited traffic from any sources that provide the token with requests to Scheduler. To learn more, see Access Control Policies.
image of the access control polies page

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.
Tip:
  • To add a range of IP addresses, follow CIDR notation:
    • For example, you want to use IP addresses 1.1.1.0 to 1.1.1.255, this would be entered into the Address field as 1.1.1.0/24
    • Note that /24 is the largest block size that is allowed.
example of adding I.P. addresses

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.

Click Add Widget to open the Create Scheduler Widget page.

image of the create scheduler widget page

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.

When finished, click Save. You should now see your new Widget listed on the Scheduler Widgets page, as seen below.example of a listed scheduler widget

Note: If you select Scheduled or Both for the Callback Type, then the Offer Scheduled Callback (Widget/API) option must be enabled for the Call Target assigned to the Widget (Call Target > General tab > Registration).

Tips for Configuring Widgets

Callback Type

Decide if you want to offer ASAP callbacks, scheduled callbacks, or both options.
Note: Scheduler Widgets are paired with a Mindful Call Target, and the Call Target needs to offer a compatible callback type to your Widget.
  • If your Call Target offers both ASAP and Scheduled callbacks, your Widget could offer ASAP, Scheduled, or both callback types.
  • If your Call Target only offers ASAP callbacks, your Widget must also only offer ASAP callbacks.

Layout Style

Decide how you want your callback request to appear within your website; as an inline form that is a part of your page flow or as a button that opens a pop-up window containing the form.

The inline callback request form will look like it is a part of your web page. In this example, the customer will see a callback request Widget directly on the page. The customer then fills out the request and clicks Submit to request a callback.

example of an inline callback request formexample of inline scheduling

A pop-up Widget first appears as a button on your website. Here's a pop-up Widget placed on a sample Contact page of a website:

example of popup callback requestsexample of popup scheduling

When the customer clicks the Request a Callback button, the callback request options display in a pop-up window. The customer then fills out the request and clicks Submit to request a callback.

Callback Offer and Registration Form

Use the callback offer statement to help set your customer's expectations of when they could receive their callback. This can be presented in two ways:

  • Based on the ECBT: "We can call you in approximately 10 minutes."
  • Based on the time that you expect the Agent to connect with the customer's callback: "We can call you today at 10:35 am."

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 Callback Form link to configure the form that your customers will use to request a callback.example of a callback request form
  3. Configure the following items, if desired:

    • Title:The title of the callback request form.

    • Messages: Configure the appropriate message, based on the callback types that will be offered. Add code snippets that announce the EWT or the projected answer time to your customers.

    • Phone Number Prompt: Configure how you prompt customers to enter their phone number and the format that you want them to use.

    • ASAP Callback Selector Label: If offering both ASAP and scheduled callbacks, enter the text that will appear next to the selection buttons for the two types of callbacks.

    • Submit Button Text: Configure the text that appears on the Submit or Cancel buttons.

    • Scheduling Style: If you offer scheduled callbacks, choose whether you want your customers to interact with date/time selectors in the form of buttons or in the form of dropdown menus.

Customize Responses

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

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

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 thePreviewbutton and following the on-screen prompts. Close thePreviewwindow when you're done testing.
  5. When finished, scroll to the top of the page and clickSave.

Using Dynamic Text Replacement

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

image of available components buttons
  • 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 aRequest a Callbackbutton
  • inline-callback-form: Adds aCallback Requestform directly into the code, which includes an input field for a customer phone number and aSubmitbutton
  • 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
example of available components
  • contact-number-confirmation: Displays the submitted customer contact phone number via text
  • appointment-time: Displays the scheduled callback appointment time via text

    View API Endpoints and Parameters For Testing

Example

The following example uses several components to personalize a notification message:

example of a customized message

In this example, the customer would see something like the following:

example of a customized button.

View API Endpoints and Parameters For Testing

You can test the functionality of your Widget in a command-line environment with the information in theAPI Endpointsmodal window. ClickAPI Endpointsin the appropriate row on theWidgetspage 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

TheEmbedicon opens theEmbed HTMLmodal window and allows you to preview your Widget. The window also contains the HTML elements required for connecting the Widget to your website.

image of the embed H.T.M.L. window

1. Styling

Select theEnable default theme and stylingcheckbox 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>Previewthat 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.

  • 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.

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

  1. On theCall Detailpage, select Web in the Source filter to view only Scheduler interactions.image of the source filter
  2. To confirm that an interaction came from a Scheduler Widget, look forsource: CBWidgetfor any interaction on theCall Detailpage. The example in this section shows a scheduled callback registered through a Widget.image of the source in a call detail report
  3. On the Executive Summary dashboard, 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.

    image of the aggregate volume graph

(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.

diagram illustrating multi modal callback scheduling

For complete instructions to implement this feature, see How to enable scheduled callbacks.

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.