Talkdesk and Mindful integration guide

The Mindful Callback integration with Talkdesk utilizes the PSTN for end-to-end communication while optionally using the Mindful Datastore service to store and retrieve custom user data. This guide presents detailed steps to configure a basic integration using Talkdesk Integrations, Actions, Functions, and Studio Flows.

Note:
  • The callback offer will be made in the Talkdesk inbound Studio Flow rather than the Mindful Callback IVR.

  • This guide uses standard (PSTN) telephony between each platform.

  • The example integration presented in this guide allows Talkdesk to post any required user data to Mindful Datastore before sending calls to Mindful for an offer, but it is also possible to send user data via custom SIP headers.

  • The configuration in this guide is an example and may be used as a template for integrating with Mindful. Any sample code in this guide should not be considered ready for production.

Overview

The order of steps in this guide will follow our standard five-stage outline:

StageDescription
EntryCustomers are presented with options (callback, hold, messaging, etc.) in the Talkdesk Studio Flow.
RegisteringCustomers provide information to Mindful Callback to request a callback.
ConnectingMindful Callback connects customers with Talkdesk agents at the appropriate time.
TalkingCustomers and agents are connected and talking.
ExitThe call is ended by the customer or agent.

The following configuration steps will be covered in their own sections corresponding with the appropriate stage:

  • Entry stage
    • Create and test an EWT phrase function
    • (Optional) Offer Second Chance Callback for customers who choose to hold
    • Configure Call Targets in Mindful Callback
    • Configure a Digital Callback Widget for each Call Target used in the integration
    • Configure a Data Set Template in Mindful Datastore
    • Create Integrations in Talkdesk for Digital Callback and Datastore API requests
    • Create Actions in Talkdesk to check Call Target status and push user data to Datastore
    • Begin to modify the inbound Flow
  • Registering stage
    • Complete the modifications to the inbound Flow
  • Connecting stage
    • Provision a phone number in Talkdesk and update the Call Target in Mindful Callback
    • Create an Action to retrieve user data from Datastore
    • Create a callback-return Flow
    • (Optional) Consolidate return-call destinations
  • Talking stage (no configuration needed for this stage)
  • Exit stage
    • (Optional) Transfer customers to a survey after speaking with an agent

Components and call flows

Definitions and acronyms

TermDescription
ANI (or CLI)
  • Automatic Number Identification: The caller's phone number in a voice call
  • Also known as Calling Line Identification (CLI) in some markets
APIApplication Programming Interface: A set of functions that allows applications to send requests to and receive responses from an application
DIDDirect Inward Dialing phone number
DNISDialed Number Identification Service: The number of the callee (typically the number that is being dialed) in a voice call
EWTEstimated Wait Time calculated by Talkdesk for a ring group
Mindful CallbackPart of the Mindful platform that provides the capability to request and receive callbacks
Mindful DatastorePart of the Mindful platform that stores and retrieves custom data for callbacks through a RESTful API
Mindful DigitalA feature of Mindful Callback that allows callbacks to be requested via API from third-party applications via web widgets
PSTNThe traditional circuit-switched telephone network that comprises all the world's telephone networks operated by local carriers

Inbound call flow

This call-flow diagram shows a callback being requested via an inbound call to Mindful Callback. Callbacks may also be requested via Mindful Digital APIs, with associated user data sent to Mindful Datastore via the Datastore API. Regardless of which method is used to create the callback, the call flow will be the same.

architecture diagram
  • A customer places a call into a Talkdesk contact center.
  • The inbound DID is matched to an Inbound Studio Flow.
  • After checking Mindful status, checking the EWT in Talkdesk, and offering a callback to the customer, the inbound Studio Flow optionally posts user data to Mindful Datastore using a Talkdesk Integration and Action.
  • The call is transferred to the phone number provisioned for the relevant Call Target in Mindful Callback.
    • If one of the following conditions occur, the call will queue to agents (the ring group) at normal priority instead of being transferred to Mindful Callback:
      • The Mindful Callback availability check fails.
      • EWT is below the configured threshold.
      • The customer declines the callback option.
      • An error occurs in the Flow (such as a Run Function or Execute Action failure).

Callback call flow (customer first)

This call-flow diagram shows a customer-first call flow for a return call. Mindful Callback also supports an agent-first call flow in which the agent is dialed first. The Talkdesk configuration and Studio Flows are the same regardless of which method is used.
architecture diagram
  • Mindful Callback dials a customer callback number. The customer answers and presses 1 to speak with an agent.
  • Mindful Callback dials the Call Center Phone Number configured for the associated Call Target.
  • The DID of the call from Mindful Callback is matched to a call-return Studio Flow in Talkdesk.
  • The call-return Studio Flow optionally obtains user data from Mindful Datastore using a Talkdesk Integration and Action, with the customer ANI used as the search key.
  • The call queues to agents (the ring group) at a higher priority than inbound calls.

Entry

Most of the unique configuration for the Talkdesk integration is related to the Entry stage. This stage begins when a call enters the call center and ends when Talkdesk transfers the customer to Mindful to register a callback. Several steps occur this stage:

  • A customer call enters an inbound Studio Flow in Talkdesk.
  • The Studio Flow quotes the current EWT to the customer and provides options to request a callback or remain on hold.
  • If the customer chooses to hold, the Studio Flow queues the call to a ring group.
  • If the customer chooses to request a callback, the Flow checks the status of the appropriate Call Target in Mindful Callback.
    • If the Call Target status check succeeds, the Flow posts user data to Mindful Datastore and transfers the call to Mindful Callback.

Review the steps in this section for more information and instructions to configure the Entry stage.

1) Create the EWT phrase function

The inbound Studio Flow must be configured to check the EWT and quote it to customers. This requires a function in Talkdesk to convert the Talkdesk EWT (in seconds) to a phrase that can be spoken via Text-to-Speech (for example, to convert an EWT of 900 seconds into a phrase such as "current Wait Time is 15 minutes"). This helps callers to make an informed decision to accept the offer or wait on hold.

Tip:

When quoting the estimated wait time prior to offering a callback, we recommend setting an upper limit for the amount of time that can be quoted. For example, if the wait time exceeds 10 minutes, you might say "...more than than 10 minutes from now" rather than quoting an exact time.

Use the following steps to create an EWT Phrase function in Talkdesk.

Quick access: (Talkdesk) Admin > Studio > Functions

  • Click Create Function in the Functions tab. This will open the New function page.
  • Name and Description: Enter a name for your function and a basic description in the fields provided. In our example integration, we named this function EWT_Phrase.
  • Inputs: Add one input with the following parameters:
    • Name: EWT
    • Type: Number
  • Outputs: Add two Outputs with the following parameters:
    • Output 1
      • Name: waitTime
      • Type: String
    • Output 2
      • Name: statusCode
      • Type: String
example talkdesk configuration
  • Function code: Copy and paste the function code directly beneath the comment that states "Write your code below". Be sure to paste the code above the final closing curly bracket in the provided template, as seen in the example screenshot.
    • Access the function code by expanding the content below:
example talkdesk configuration

EWT Phrase function code

{
    var oldestCallWaiting = EWT;
    var waitTime = "";
 
     console.log(oldestCallWaiting);
 
     if(oldestCallWaiting<60) {
 
        waitTime = "Current wait time is less than 1 minute."
 
    } else if(oldestCallWaiting>7200) {
 
                waitTime = "Current wait time is more than 2 hours."
 
    } else {
 
        var hours = Math.floor(oldestCallWaiting/3600);
        var minutes = Math.floor((oldestCallWaiting-(hours * 3600))/60);
        var seconds = oldestCallWaiting - (hours*3600) - (minutes*60);
        var hoursPhrase = "";
        var minutesPhrase = "";
 
         if(seconds > 0) {
             minutes = minutes + 1;
             if(minutes == 60) {
                 hours = hours + 1;
                 minutes = 0;
            }
        }
         if(hours == 1) {
             hoursPhrase = "1 hour";
        } else {
             if(hours > 0) {
                 hoursPhrase = `${hours} hours`;
            }
        }
          if(minutes == 1) {
             minutesPhrase = "1 minute";
        } else {
             if(minutes > 0) {
                 minutesPhrase = `${minutes} minutes`;
            }
        }
         waitTime = `Current wait time is approximately ${hoursPhrase} ${minutesPhrase}`;
     }
     
     console.log(waitTime);
     return {
         "statusCode": 200,
         "waitTime": waitTime
    };
};
You can customize the wording of the EWT phrase and the minimum/maximum ranges within the three conditions that assign a value to the waitTime variable:
  • if(oldestCallWaiting<60): This condition sets the minimum announced time and assigns a phrase to use when the EWT is below this value.
  • if(oldestCallWaiting>7200): This condition sets the maximum announced time and assigns a phrase to use when the EWT is above this value.
  • else: The final condition catches calls whose EWT is between the minimum and maximum values. You can customize the format and phrasing of the spoken EWT further in this section.

Test the EWT phrase function before saving.

Check everything before saving this function. Once a function is published, it cannot be changed or deleted in Talkdesk! Use the Test function page to make sure the function returns expected output values based on different input values before publishing.

You can test the EWT Phrase function by clicking the Test function button before saving. In the Test function modal window, enter any EWT value (in seconds), then click Test function to see the value of the waitTime variable (the EWT phrase). We recommend using different test values that will follow all possible paths in the function code.
example talkdesk configuration

(Optional) Offer Second Chance Callback

Expand the content below to learn how to make additional callback offers in your holding queue after a customer has declined the initial offer.

Second Chance Callback is a best-practice methodology that can increase the take-rate of callback offers and lower the abandon rate in your call center's holding queues. With a few updates to your routing logic, you can provide additional callback offers to customers waiting on hold who have already declined an initial offer.

There are a variety of reasons that customers might appreciate a second chance to accept an offer of a callback. For example, perhaps something has come up that requires their attention and they can no longer wait on hold. Perhaps the quoted wait time was low when they declined the first offer but queue conditions have quickly changed and resulted in a longer hold time. Regardless of the scenario, Second Chance Callback ensures that customers have the callback option available when they need it.

Benefits

Our research shows positive results for call centers offering Second Chance Callback, including:

  • Keeping customers in control with additional options while holding.
  • Reducing abandoned calls in the holding queue by offering an alternative option.
  • Fully controlling Second Chance offers in your ACD with no integration constraints.
  • Adding another tool to address unexpected increases in hold time.
  • No additional requirements for customers. They are not required to respond to Second Chance prompts, but can instead simply continue to wait on hold if they choose.

ACD configuration

Most configuration for Second Chance Callback is done on your ACD platform, so the technical implementation will vary based on your integration. In all integrations, the following logic must be introduced to interact with customers in the holding queue.

call flow diagram

  • Whether offers are made in your ACD or in Mindful Callback, the process begins with the first offer. If the initial offer is accepted, then a callback is registered and no Second Chance offer is needed.
  • If the initial offer is not accepted, callers are routed to a holding queue.
  • A timer begins in the holding queue. When the specified time expires, another callback offer is made.
  • If the customer declines the Second Chance offer, then the timer is reset, and another offer will be made when it expires again.
  • If the customer accepts the Second Chance offer, the call is sent to Mindful Callback for treatment.
Note:

You can add logic into the routing script to limit the total number of offers made per call.

Things You'll Need

If you wish to use a single Call Target for normal inbound calls and Second Chance calls, you will need:

  • Two Phone Numbers provisioned for the same Call Target.
  • The Return to Hold Call Target setting disabled. Offering a hold option in Mindful Callback after a customer has already chosen to leave the holding queue can negatively impact the customer experience.

If you wish to use separate Call Targets for normal inbound calls and Second Chance calls, you will need:

  • Two Call Targets configured with the same Call Center Phone Number targeting the same group of agents.
  • The Return to Hold setting disabled for the Second Chance Call Target. The setting can still be enabled for the normal inbound Call Target.

For either method, you will also need:

  • The ability to capture DTMF input from customers in your holding queue.
  • The ability to play audio prompts to customers in your holding queue based on a timer.

Mindful Callback configuration

There are two alternatives for preparing your Mindful Callback account for Second Chance Callback. Each alternative introduces its own advantages and drawbacks.

  • Option 1 (best practice): Use separate Call Targets for normal inbound calls and Second Chance calls.
  • Option 2: Use a single Call Target for both normal inbound calls and Second Chance calls.

Option 1 (best practice): Use separate Call Targets

This option uses the first Call Target to service normal inbound callback requests with a second Call Target dedicated to servicing Second Chance callback requests. For an initial offer, send the call to the first Call Target. For a Second Chance offer, send the call to the second Call Target. This option separates the two types of calls for ease of reporting and real-time analysis.

example call targets

AdvantagesDrawbacks
Call Detail reporting is more convenient.ECBT is not combined between the two Call Targets. Therefore, ECBT on the normal inbound Call Target may be lower than it should be, since the call volume from the Second Chance Call Target is not included in the calculation.
Real-time monitoring clearly distinguishes the two call types.
You can enable the Return to Hold option on the normal inbound Call Target while disabling it on the Second Chance Call Target.

Option 2: Use a single Call Target

The second option uses a single Call Target to service both normal inbound callback requests and Second Chance requests. This method is easier to configure and maintain, but it introduces a few additional drawbacks to consider.

example call target

AdvantagesDrawbacks
Configuration is simpler.When a Second Chance ASAP callback is registered, it will be placed at the back of the virtual queue or waitlist. This can result in customers who accept Second Chance offers waiting longer than they would have if they remained in the holding queue.
Return to Hold should not be offered by the Call Target. This can affect your offer strategy for normal inbound calls, which may not be intended.
Reporting on Second Chance interactions requires additional steps.
Real-time monitoring combines normal inbound callback requests and Second Chance requests together.

Reporting on Second Chance Callback interactions

As noted in the lists of advantages and drawbacks, reporting on Second Chance interactions varies depending on whether you use one or two Call Targets.

Reporting with separate Call Targets

On the Metrics, Executive Summary, and Call Detail screens, use the Call Target filter to view data only for the Second Chance Call Target. This will exclude any data from initial offers and callers that chose to hold. If you offer Second Chance for multiple lines of business, you can add all of your Second Chance Call Targets into a shared Reporting Category to view all Second Chance interactions.

On the Callback Status screen, review real-time statistics for the Second Chance Call Target or use the Category filter to limit the view to only Second Chance Call Targets.

Reporting with a single Call Target

When using a single Call Target, additional configuration is required and the reporting capabilities are limited.

Preparation:

  • Provision two Phone Numbers in the Mindful Callback user interface, and assign both Phone Numbers to the same Call Target.

example phone numbers

  • In your routing scripts, send normal inbound calls for callback treatment to the first Phone Number.
  • Send Second Chance calls for treatment to the second Phone Number.

Reporting:

  • On the Call Detail screen, export the reporting data to CSV. In the exported CSV file, the Call Target Phone Number to which each call was sent will be noted in the Source column.
  • In the CSV file, filter the Source column for all records matching the Second Chance phone number. The remaining data will include only Second Chance interactions.
Note:

When using a single Call Target, the Callback Status, Metrics, and Executive Summary screens will combine Second Chance interactions with initial offers and callers that chose to hold.

2) Configure your Mindful environment to receive calls from Talkdesk

{{snippet.Mindful Integrations - Mindful Config - PSTN}}

3) Create an Integration for Mindful API calls

In Talkdesk, an Integration serves as a container for Actions. The first Integration will contain an Action to check Call Target status via a Digital Callback Widget.

Use the following steps to create an Integration for Mindful Digital API calls to check Call Target status. This Integration will contain one Action (GetWidgetStatus) that will be covered in a later step.

  • Copy the Retrieve Widget Status URL from the Digital Callback Widget you configured in a previous step (Digital > Widgets > API Endpoints). The URL is shown in the URL field:

example API endpoint

The Solution Delivery team can assist with locating this URL or can provide the URL as needed. The URL will be in the format https://<Organization ID>.<domain>/api/widget/<Widget ID>.For example:

https://70f954b312c680c3.cbridgert.vhtcloud.com/api/widget/s0bnqp3eab34881fd3ce2c96f15fb342
  • On the Talkdesk Integrations page (Admin > Integrations), click Add integration.
  • In the list of available integrations, locate the Custom Integration box and click Add Integration within the box.
  • Configure the Integration as seen below, then save it.
example talkdesk configuration
  • Name and Description: Enter a name and description for the Integration. Remember that this Integration will be used for API calls to Mindful.
  • Base path: Enter the Retrieve Widget Status URL obtained in a previous step, without the Widget ID. See the example screenshot if you are unsure what the modified URL should look like.
  • Authentication type: Select No Authentication.

4) Create a new Action to retrieve Widget status via API

The first Action for the Mindful API Integration will submit a GET request to check the status of a Call Target in Mindful Callback. Digital Callback Widgets are each associated with a Call Target, so you can use the API endpoint for a Widget to check the status of the Call Target assigned to it. In the inbound Studio Flow (covered in a later step), this Action will be invoked before transferring calls to Mindful Callback, to ensure that the Call Target is ready to register callbacks.

Use the following steps to configure the Get Widget State Action.

  • In the Mindful API Integration created in a previous step (Admin > Integrations), open the Actions tab.
  • Click Add action.
  • Configure the Action as seen below, then save it as a draft.

Example Action

example talkdesk configuration
  • Name and Description: Enter a name and description for the Action. Remember that this Action will be used to check the status of a Call Target.
  • Relative path: Select GET and enter /{{call-target-id}} into the field.
  • Parameter Display Name: Enter a name of your choice, such as Call Target ID. This will allow you to pass the call-target-id variable from the inbound Studio Flow to this Action.
  • Parameter type: Select String.
  • Output Schema: Paste the following JSON schema into the field. Although the API will return multiple values in its response, you only need to capture the widget_state property to check the status.
{   "$schema": "http://json-schema.org/draft-07/schema",   "type": "object",   "title": "Output",   "required": [     "widget_state"  ],   "properties": {     "widget_state": {       "type": "string",       "title": "The widget state"    }  }}
  • Save the Action as a draft, but do not publish it before testing! Actions in Talkdesk cannot be edited after they have been published.
  • Click Test Action to open the Test configuration modal window.
  • Enter the relevant Widget ID into the Value field to assign the ID to the call-target-ID parameter for testing. You can obtain the Widget ID from the URL that you copied when creating the Integration for the Mindful API.
example talkdesk configuration
  • Click Execute and review the response. A successful response with a 200 status code should look like the example screenshot below.

Example Response

example talkdesk configuration

  • When you're satisfied with the test results, close the test page and publish the Action to make it available to the inbound Studio Flow.

Troubleshooting Tip

  • If you receive a 502 "upstream error" response, check the Number of Days Out to Schedule Widget Callbacks setting for the associated Call Target. If the Call Target allows scheduling more than 250 days out, the API call can fail with an "upstream error".

5) Create a new Integration for Datastore

The second Integration will contain two Actions for interacting with Mindful Datastore. One Action will store user data on the Mindful side for inbound calls and the other will retrieve user data for callbacks returned from Mindful to Talkdesk. The configuration is similar to the first Integration created for the Mindful API.

Note:

This section only applies if you use Mindful Datastore in your integration. If you choose to pass user data in another way, you will not need this Integration and it's related Actions.

  • On the Talkdesk Integrations page (Admin > Integrations), click Add integration.
  • In the list of available integrations, locate the Custom Integration box and click Add Integration within the box.
  • Configure the Integration as seen below, then save it.
example talkdesk configuration
  • Name and Description: Enter a name and description for the Integration. Remember that this Integration will be used for API calls to Datastore.
  • Base path: Enter datastore.mindfulcx.com
  • Authentication type: Select Http Api Key
  • Api Key Header Name: Enter authorization
  • Key value: Enter the API Token of the Data Set Template that you configured in Mindful Datastore in a previous step (Data Set Templates > Edit), prefixed with "Bearer" and a space.
    • For example, "Bearer bTFho2Coa//Pi7hks+i9V6zhxB/m19e8UzMuRs3NsBm="
  • Other settings: Add one header with the following details:
    • Header: content-type
    • Value: application/json

6) Create a new Action to send data to Mindful Datastore

The next Action will send user data to Mindful Datastore so that the data can be retrieved when the callback is returned from Mindful to Talkdesk. With the ability to store custom user data, you can add functionality for agent screen-pop, routing logic, reporting, or other purposes.

As an example, you may choose to store info on the ring group of the inbound call so that the callback can be queued to the same ring group. This would allow a single DID and Studio Flow to be used across all ring groups.

In a later step, the callback return Studio Flow will invoke this Action to retrieve data before queueing the callback to an agent.

Use the following steps to configure the Datastore Post Action.

  • In the Mindful Datastore Integration created in a previous step (Admin > Integrations), open the Actions tab.
  • Click Add action.
  • Configure the Action as seen below, then save it as a draft.

example talkdesk configuration

  • Name and Description: Enter a name and description for the Action. Remember that this Action will be used to store user data for inbound calls.
  • Relative path: Select POST and enter /api/v1/data_sets into the field.
  • Input Schema: Edit the following JSON schema to include all of the KVPs defined in your Data Set Template, then paste the customized schema into the field.

In the example Input Schema below, the customer_contact_number property is required and the following additional properties are only examples:

  • FirstName
  • LastName
  • AccNum
  • CallId

You can add any KVPs that you have defined in the Data Set Template into the schema.

Example Input Schema

{
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Input",
   "type": "object",
   "required": [
     "customer_contact_number",
     "data_values"
  ],
   "properties": {
     "customer_contact_number": {
       "title": "Customer_contact_number",
       "type": "string"
    },
    "data_values": {
       "title": "Data_values",
       "type": "object",
       "required": [
         "AccNum"
      ],
       "properties": {
         "FirstName": {
           "title": "Firstname",
           "type": "string"
        },
         "LastName": {
           "title": "Lastname",
           "type": "string"
        },
         "AccNum": {
           "title": "Accnum",
           "type": "string"
        },
         "Callid": {
           "title": "Callid",
           "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
   "additionalProperties": false
}
  • Save the Action as a draft, but do not publish it before testing! Actions in Talkdesk cannot be edited after they have been published.
  • Click Test Action to open the Test configuration modal window.
  • Enter a complete JSON object into the field, then click Execute. You can obtain an example JSON object fitting the required schema from the Mindful Datastore UI (Data Set Templates > Data Set API). See the example Datastore screenshot below, in which the JSON object for testing is highlighted. You can see this object pasted into the screenshot of the Test configuration window in Talkdesk here, as well.
example talkdesk configuration

example talkdesk configuration

  • When you're satisfied with the test results, close the test page and publish the Action to make it available to the inbound Studio Flow.

Troubleshooting Tips

Consult the table below for tips to resolve errors when testing the Action. The table lists several error responses that could be returned.

Status codeMessageTips
400Validation FailedCheck the format of the Input Schema or the JSON object provided in the test to ensure it is correct.
400Input field does not match Action Input SchemaCheck the JSON object provided in the test to ensure that it matches the configured Input Schema.
502Upstream ErrorCheck the base URL, relative path, and Datastore API Token to ensure they are correct.

7) Configure the Inbound Studio Flow in Talkdesk

With the function, Integrations, and Actions in place, the next step is to modify your existing inbound Studio Flow in Talkdesk. The following steps must be added to the inbound Flow for the integration with Mindful.

  • Fetch the EWT and turn it into a phrase to play back to the caller.
  • Check the EWT to make sure it is above a defined threshold before offering a callback.
  • Play the EWT phrase to provide the caller with information needed to make a decision.
  • Confirm that Mindful Callback is available and ready to process a callback request.
  • Offer the caller the option to request a callback instead of waiting on hold.
  • Post user data to Mindful Datastore.
  • Transfer the call to Mindful Callback for callback registration.

Inbound Flow

example talkdesk configuration

Quick access: (Talkdesk) Admin > Studio > Flows

Here are some of the key steps from a sample Inbound Studio flow in more detail:

Initial step

Initial step preferences

In the Initial step, assign the source_phone Step variable to a string variable (named ANI in our example integration). This variable will be used as the primary search key when posting user data to Mindful Datastore.If you intend to post the inbound Talkdesk Interaction ID to Datastore, then assign the interaction_id Step variable to a string variable as well (CallId in our example).

example talkdesk configuration

Initial step exits

Ok exit: Create a new Estimated waiting time block named GetEWT.

Get EWT (Estimated waiting time step)

This step returns the EWT (in seconds) of the target ring group and assigns that value to a number variable.

Estimated waiting time preferences

In our example, the EWT value (estimated_waiting_time_in_seconds) is assigned to variable named CallEWT.
example talkdesk configuration

Estimated waiting time exits

  • Successful exit: Create a new Conditional Statement block named EWT > Threshold?.
  • Indeterminate exit: Create a new Assignment and Dial block named Queue to Agents. This exit path will be taken if Talkdesk is unable to obtain an EWT for the associated ring group, meaning that no calls have been handled by the ring group in the past 10 minutes.
Note:

We chose to send calls directly to agents if no EWT can be obtained, but you may decide to handle calls differently in this scenario. For example, you might choose to continue with the callback offer in this case.

  • Error handling: Select Follow "Indeterminate exit" exit.

Estimated waiting time exits

example talkdesk configuration

Queue to Agents (Assignment and Dial step)

In addition to serving as the Indeterminate exit for the Estimated waiting time block, this Queue to Agents block will be used as the failure route for all subsequent blocks in the Flow. As you continue to build additional blocks, this block will remain at the bottom of the Studio Flow.

Assignment and dial preferences

In this step, set the priority at a level that will never be higher than the callback priority (which will be set in the callback return Flow later). Priority 1 is the highest priority in Talkdesk, so the priority for holding calls in the inbound Flow should always be lower (2 to 10). In our example integration, we have set the inbound priority to 5.

example talkdesk configuration

Assignment and dial exits

Set all exits to End Flow.

example talkdesk configuration

EWT > Threshold? (Conditional Statement step)

This step checks the estimated waiting time against a configured value to determine whether to offer a callback or send the customer to queue.

Tip:

We recommend setting a minimum offer threshold based on the current estimated wait time to ensure that callback offers are not made when wait times are very low. You may also wish to check agent availability prior to offering a callback.

Conditional Statement preferences

Select the default_output variable created previously (the output is not required).

example talkdesk configuration

Conditional Statement preferences

  • Condition #1: Select the CallEWT variable created in the previous Estimated waiting time step, then select Greater or Equal and enter a value (in seconds) to use as a threshold. In our example, if CallEWT >= 60 seconds, we will move to the next block.
  • Condition #1 exit: Create a new Execute Action block named Check Mindful Status.
  • No Match exit: Select the existing Assignment and Dial step (Queue to Agents).
  • Error handling: Select Follow "No Match" exit.

Conditional Statement exits

example talkdesk configuration

Check Mindful Status (Execute Action step)

This step executes the Action created in a previous step to check the status of a Call Target. Since all Digital Callback Widgets are associated with a single Call Target, you can use the Retrieve Widget Status API endpoint for a Widget to ensure the associated Call Target is ready to offer callbacks.

Execute Action preferences

Note that the call-target-id input will differ based on the Call Target / Widget you are targeting.

  • Connections: Select the Integration for the Mindful API created in a previous step.
  • Inputs: Enter the relevant Widget ID. You can obtain the Widget ID from the URL that you copied when creating an Integration for the Mindful API.
  • Outputs: Create a string variable to hold the value of the widget_state parameter. In our example, we named this variable mindful_status.
example talkdesk configuration

Execute Action exits

  • Ok exit: Create a new Conditional Statement step named Mindful Available?.
  • Execution error: Select the existing Assignment and Dial step (Queue to Agents).
  • Error handling: Select Follow "Execution error" exit.
example talkdesk configuration

Mindful Available? (Conditional Statement step)

This step uses the output variable of the previous block to determine whether Mindful Callback and the specified Call Target are ready to offer callbacks.

Conditional Statement preferences

The Step variable will not be used, but Talkdesk requires a value for the variable. Select or create a default_output variable to satisfy the requirement.

example talkdesk configuration
  • Condition #1
    • Matching: Select Any
    • Conditions: Create two conditions in the following format (note that mindful_status is the output variable from the previous step).
      • mindful_status Equals offer_asap_callback
      • mindful_status Equals offer_callback
    • Exit name: Enter a name that indicates Mindful Callback is available. In our example, we named the exit Mindful Available.
    • Send to: Create a new Run function block named ConvertEWT.
  • No Match exit and Error handling: Select the Queue to Agents step.

Conditional Statement exits

example talkdesk configuration

ConvertEWT (Run function step)

This step invokes the EWT Phrase function created in a previous step. The EWT Phrase function takes an EWT value (in seconds) and converts it into a phrase that can be spoken via text-to-speech.

Run function preferences

  • Function: Select the EWT Phrase function created in a previous step.
  • Inputs: For the EWT input, assign the output of the Estimated waiting time step in this Studio Flow. In our example, the output variable is named CallEWT.
  • Outputs:
    • statusCode: Create a string variable to hold the value of the statusCode output (to catch any errors from the function).
    • waitTime: Create a string variable to hold the EWT phrase returned from the function.
example talkdesk configuration

Run function exits

  • Ok exit: Create a new Play Audio block named Play EWT Phrase.
  • Execution error and Error handling: Select the Queue to Agents step.
example talkdesk configuration

PlayEWT (Play Audio step)

This step plays the EWT phrase returned by the previous Run function step.

Play Audio preferences

  • Type of message: Select Text to speech.
  • Text to speech: Enter the format %{current_flow.<variable name>}.(including the period after the closing bracket). In our example, we entered %{current_flow.waittime}. since waitTime is the variable holding the EWT phrase.

example talkdesk configuration

Play Audio exits

  • Ok exit: Create a new Input IVR step named OfferCallback.
  • Error handling: Select Use default behavior.
example talkdesk configuration

Offer Callback (Input IVR step)

This step prompts the caller to input DTMF digit 1 to accept the offer or digit 2 to wait on hold.

Input IVR preferences

  • Type of message: Select Text to speech.
  • Text to speech: Enter a phrase you would like the IVR to speak to customers to offer a callback. In our example, we entered "If you would like us to call you back, press 1. If you would rather remain on hold, press 2."
  • Maximum number of digits: Enter 1.
  • Ending keypress: Enter # (this will not be used since the input will end after a single digit).
  • Variables: Assign the digits Step variable to a new string variable (offer_digits in our example).
example talkdesk configuration

Input IVR exits

  • Ok exit: Create a new Conditional Statement step named Check Digits.
  • Timeout:
    • Time in seconds: Enter a number of seconds to wait before timing out and sending customers to the agent ring group. We used five seconds in our example integration.
    • Send to: Select the Queue to Agents step.
  • Error handling: Select Use default behavior to send the call to the same location as the Timeout exit.
example talkdesk configuration

Check Digits (Conditional Statement step)

This step checks the DTMF digit entered in the previous step to determine how to proceed.

  • Step variable: This will not be used but Talkdesk requires a value here. Select the default_output variable.
example talkdesk configuration

Conditional Statement exits

  • Condition #1
    • Matching: Select All.
    • Conditions: Create a single condition in the following format:
      • offer_digits Equals 1
    • Exit name: Enter a name that indicates the customer has chosen to receive a callback.
    • Send to: Create a new Execute Action step named Post to Datastore if you will use Datastore to store and retrieve user data. Otherwise, create a new Forward to External Number step named Transfer to Mindful instead.
  • No match exit and Error handling: Select the Queue to Agents Assignment and Dial step.
example talkdesk configuration

Post to Datastore (Execute Action step)

This step executes the Datastore Post action created in a previous step.

Execute Action preferences

  • Connections: Select the Integration created for Mindful Datastore.
  • Actions: Select the Datastore Post Action.
  • Inputs: A field will be displayed for each item in the Input Schema of the Action (including the required customer_contact_number field). Populate these fields with variables in the current Studio Flow as necessary, including the ANI variable that was set in the Initial Step block.
example talkdesk configuration

Execute Action exits

  • Ok exit: Create a new Forward to External Number step named Transfer to Mindful. Instructions for the Forward to External Number block will be provided in the next section, the Registering stage.
  • Execution error and Error handling: Select the Queue to Agents Assignment and Dial step.
example talkdesk configuration

This concludes the Connecting stage, and only one more step remains to complete the inbound Studio Flow.

Registering Stage

The inbound Studio Flow is almost complete, and the final step is related to the Registering stage. In this stage, customers will be transferred to Mindful Callback to provide basic information to register a callback.

The following steps continue where the previous stage left off, by finishing the inbound Studio Flow.

Transfer to Mindful (Forward to External Number)

This step will transfer the call to the appropriate Call Target in Mindful Callback for registration.

Forward to External Number preferences

  • Number to show during outbound: Select Contact Number. This will provide the caller's phone number to Mindful.
  • Max ringing time in seconds: Set this to your desired value. A short ringing time of three seconds should be fine, although we use 10 seconds in our example.

example talkdesk configuration

Forward to External Number exits

Select the Queue to Agents step for all exits.

example talkdesk configuration

When finished, save and publish the inbound Studio Flow.

Provision a number for return calls in Talkdesk

Mindful Callback requires a Call Center Phone Number to be configured for each Call Target to tell the Call Target where to send callbacks to connect with agents. Several steps are required to make this connection:

  • Provision a new phone number in Talkdesk (if needed).
  • Assign the new number to the return call Studio Flow in Talkdesk. This will be covered in a later step.
  • Configure the number as the Call Center Phone Number for the Call Target in Mindful. This will be covered in a later step.

If you do not have a number available in Talkdesk for return calls coming from Mindful, you can obtain a new one via the following steps.

Quick access: Admin > Numbers

  • On the Numbers page, click New Phone Number.
  • Fill in the provided fields to set search parameters for your desired number, then click Search for Numbers.
  • Select a number from the list of results, then click Buy.

You should now see the number available on the Numbers page. This new number will be assigned to the return-call Studio Flow and configured as the outbound Call Center Phone Number in Mindful Callback in later steps.

Create new Action to get data from Datastore

The final Action will retrieve the user data that was posted to Mindful Datastore during the inbound Studio Flow.

Use the following steps to configure the Datastore GET Action.

  • In the Mindful Datastore Integration created in a previous step (Admin > Integrations), open the Actions tab.
  • Click Add action.
  • Configure the Action as seen below, then save it as a draft.

Example Action

example talkdesk configuration
  • Name and Description: Enter a name and description for the Action. Remember that this Action will be used to retrieve user data for inbound calls.
  • Relative path: Select GET and enter /api/v1/data_sets/search?customer_contact_number={{customer_contact_number}} into the field.
  • Output Schema: Edit the following JSON schema to include all of the KVPs defined in your Data Set Template, then paste the customized schema into the field. Remember that the AccNum, FirstName, LastName, and CallId properties shown below are only examples.
{
         "$schema": "http://json-schema.org/draft-07/schema",
         "type": "object",
         "title": "Output",
         "properties": {
         "AccNum": {
         "type": "string",
         "title": "The AccNum"
         },
         "LastName": {
         "type": "string",
         "title": "The LastName "
         },
         "FirstName": {
         "type": "string",
         "title": "The FirstName "
         },
         "CallId": {
         "type": "string",
         "title": "The CallId "
         }
         }
        }
  • Save the Action as a draft, but do not publish it before testing! Actions in Talkdesk cannot be edited after they have been published.
  • Click Test Action to open the Test configuration modal window.
  • Enter a test value for the customer_contact_number parameter, then click Execute. You may need to re-run your test of the Datastore Post Action to make sure there is data available to be retrieved when testing the Datastore GET Action.
example talkdesk configuration
  • When you're satisfied with the test results, close the test page and publish the Action to make it available to the inbound Studio Flow.

Configure callback Flow to receive callbacks from Mindful

The callback Flow is used for calls returned from Mindful to Talkdesk.

When using the Customer First Callback Strategy, Mindful Callback will call customers first and wait for them to confirm they are ready to speak with an agent. Then, Mindful will call the phone number associated with the callback Flow in Talkdesk. When an agent answers the call, Mindful will connect both parties.

When using the Agent First Callback Strategy, the opposite path is taken. Mindful will call the number of the callback Flow first, wait for an agent to confirm, then call the customer.

In either scenario, the same callback Flow progresses through the following steps:

  • Fetch stored user data from Mindful Datastore.
  • Queue the call to the agent (ring group) at a higher priority than inbound calls.

Callback Flow

call flow diagram

Create a new Studio Flow (Admin > Studio > Flows > Create Flow), then add the blocks detailed below.

Initial Step

Initial Step Preferences

Just like the Initial step in the inbound Flow, this initial step should have the source_phone Step variable assigned to a string variable (such as ani). This variable will be used in the next step to retrieve user data from Mindful Datastore.

example talkdesk configuration

Initial Step exits

Ok exit: Add a new Execute Action block named GET from Datastore.

example talkdesk configuration

GET from Datastore (Execute Action step)

This step executes the Datastore GET Action created in a previous step. The customer_contact_number is the only required input. It is used as the primary search key to fetch the stored user data record from Mindful Datastore.

Note:

It is possible for a customer to request a callback to a different number than the one they captured in the inbound Flow and used to post user data to Datastore. If this happens, Mindful Callback will automatically update the matching Datastore record with the updated callback number and present this updated number to Talkdesk when the callback is delivered. This ensures that the Datastore GET Action will use the updated number to retrieve the correct data from Datastore.

Execute Action preferences

  • customer_contact_number: Select ani.
  • Outputs: Configure any outputs necessary to match the Output Schema of the Datastore GET Action. Assign each output to a new or existing variable.
example talkdesk configuration

Execute Action exits

  • Ok exit: Create a new Assignment and Dial block named Priority Queue to Agents.
  • Execution error exit: Nothing is required here, but in our example integration we created a Play Audio block to note that an error occurred.
example talkdesk configuration

Priority Queue to Agents (Assignment and Dial)

Assignment and Dial preferences

It is important to queue the call at a higher priority than inbound calls in this step, because the caller has already queued virtually while waiting for the callback. Priority 1 is the highest in Talkdesk, so if the callback priority is set to 1, make sure the priority in the inbound Studio Flow is a lower value (2 to 10).

example talkdesk configuration

Assignment and Dial exits

Select End for all exits.

example talkdesk configuration

When finished, save and publish the Flow.

Assign a phone number to the Flow and test it

After the Flow is published, you can assign the phone number provisioned in Talkdesk via the following steps:

Quick access: Admin > Studio > Flows

  • On the Flows page, click the ellipsis (...) in the appropriate row, then click Manage Numbers.
  • Select the check box next to your desired number, then click Save.

You should now see the number listed on the Flows page in the appropriate row. Mindful can now send calls to this number to enter the return-call flow.

To test the integration end-to-end, simply provision and assign a number to the inbound Flow, then place a call to that number. You should successfully pass through the inbound flow and out to Mindful for callback registration. You should then receive a callback from Mindful and be sent to the return-call Flow in Talkdesk, where you can transfer to an active agent to complete the test.

If your test calls take any failure routes in your Studio Flows, check a Studio Flow Execution Report (Reporting > Explore > Default Reports) for details of what occurred at each step of the Flow.

Manage Context Data

When a flow is opened for Editing in Talkdesk Studio, a Manage Context button, shown as two curly braces, will appear on the page. Click this button to open the Manage Context page. This page allows you to check the custom variables in the Flow to ensure they will appear on agents' call bars when calls arrive. This can be used in both inbound and callback Flows to show data to the agent, including data retrieved from Mindful Datastore.example talkdesk configuration

Configure the Call Target Phone Number in Mindful Callback

Quick access: Voice > Call Targets > Your Call Target > General tab > Dial Settings

Call Center Phone Number: Enter the number provisioned in Talkdesk for return calls. This will instruct the Call Target to send callbacks to the number assigned to the return call Studio Flow.

example talkdesk configuration

(Optional) Consolidate return-call destinations

Expand the content below to learn about best practices for return-call routing when the same group of agents are spread out among multiple queueing destinations.

This integration guide has assumed that each Call Target is configured with a Call Center Phone Number leading to a single group of agents in your call center. However, in some ACD environments, the same group of agents are spread out among multiple queueing destinations. Since a Call Target is intended to serve a particular agent group, there needs to be a way to deliver callbacks and return-to-hold calls to a single destination that can ultimate route calls throughout the entire agent group.

You can configure a Call Target to send calls to a Call Center Phone Number that leads to a shared disposition destination, then make further routing decisions based on data attached to the call. This form of queue consolidation allows you to route return calls among multiple destinations representing the same group of agents.

How it works

Using a consolidated callback destination requires custom data to be passed to Mindful Callback with inbound calls to identify their ultimate return destinations. This can be done in two ways:

  • Send the destination to Callback via SIP Headers. This requires that you configure additional Metadata Items for each affected Call Target. Or...
  • Post the destination to the Mindful Datastore application, using the customer's ANI as the data key. This method can be used even when calls are delivered via the PSTN rather than SIP.

In either case, Callback will re-attach the custom data to the return call (whether it is a callback or a customer returning to hold) and deliver the call to a single return-call disposition destination. From there, you can use the custom data to route the call to the appropriate agent groups.

Note:

We recommend using different universal return destinations for callbacks and callers who chose to hold. The choose-hold destination is only needed if the Callback Offer or the End of Day Handling > Return to Hold settings are enabled.

Example

Consider the following example. Let's say you have the same agent skill assigned to different queueing destinations labeled 111, 222, and 333. You have a single disposition destination for callbacks and another for return-to-hold calls. In this case, the routing path for a callback could look like this:

call flow diagram

  • You identify that a particular new inbound call should ultimately be delivered to 333, so you attach that destination number to the call as custom data when sending it to Callback for treatment.
  • When the time comes, Callback delivers the return call (a callback in this case) with the destination number still attached.
  • When the call arrives at the callback disposition destination on your ACD, additional routing logic ensures that the call ends up with agents at 333.
  • The appropriate priority is set, and the call is delivered to an agent.