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. 

Overview

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

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

1. 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
2. Registering stage
   • Complete the modifications to the inbound Flow
3. 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
4. Talking stage (no configuration needed for this stage)
5. Exit stage
   • (Optional) Transfer customers to a survey after speaking with an agent

Components and call flows

Before looking at configuration, you can expand the content below to review key terms and acronyms used throughout this guide.

Example call flows for inbound and callback interactions are included below. Click each of the following tabs to learn more.

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.

1. A customer places a call into a Talkdesk contact center.
2. The inbound DID is matched to an Inbound Studio Flow.
3. 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.
4. The call is transferred to the phone number provisioned for the relevant Call Target in Mindful Callback.
   1. 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.

1. Mindful Callback dials a customer callback number. The customer answers and presses 1 to speak with an agent.
2. Mindful Callback dials the Call Center Phone Number configured for the associated Call Target.
3. The DID of the call from Mindful Callback is matched to a call-return Studio Flow in Talkdesk.
4. 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.
5. 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: 

1. A customer call enters an inbound Studio Flow in Talkdesk.
2. The Studio Flow quotes the current EWT to the customer and provides options to request a callback or remain on hold.
3. If the customer chooses to hold, the Studio Flow queues the call to a ring group.
4. If the customer chooses to request a callback, the Flow checks the status of the appropriate Call Target in Mindful Callback.
   1. 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. 

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

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:

 {
    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
    };
};

Test the EWT phrase function before saving IMPORTANT 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.

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

2) Configure your Mindful environment to receive calls from Talkdesk

Before your ACD can send inbound calls to Mindful, there are a few items that must be configured on the Mindful side:

• At least one Call Target to register and dial callbacks
• One Scheduler Widget for each Call Target used in the integration
• A Data Set Template in Mindful Datastore (if you intend to use Datastore to store custom user data and context)

Call Target configuration

There are a few settings in Callback that must be adjusted to integrate with your ACD.

Registration

Quick access: Callback > Call Targets > Your Call Target > General tab > Registration

• Offer ASAP Callback: Select this checkbox to offer callbacks to be returned as soon as possible.
• Offer Scheduled Callback: Select one or both of these checkboxes (Voice and/or Widget/API) if you wish to offer callback scheduling for specific dates and times.

Contact Center

Quick access: Voice > Call Targets > Your Call Target > General tab > Contact Center

1. Callback Telephony Type: Select PSTN.
2. Callback Number: This will be configured in a later step.

Note for Government Users

Only SIP is available in the Government instance.

Callback Strategy

Quick access: Voice > Call Targets > Your Call Target > General tab > Callback Strategy

Most of the Callback Strategy settings are not relevant to the integration, and they can be set however you would like. However, there is one notable exception when using the Customer First Callback Strategy.

When using Customer First, enable Wait for live Agent. This will prompt agents to press a digit to accept a callback, which provides an Agent Answer event to Mindful. The Agent Answer events assist in calculating an accurate Estimated Callback Time (ECBT).

Phone Numbers

Quick access: Configuration > Phone Numbers

On the Phone Numbers page, provision as many PSTN numbers as needed and assign a number to each Call Target in your Organization. This is the number to which you will send inbound calls for callback treatment.

Scheduler Widget configuration

Each Call Target used in the integration will require a Scheduler Widget. These Widgets will provide API endpoints that will allow your ACD to check the status of a Call Target before forwarding an inbound call to Mindful. Important points for the Widgets used in this integration are listed below:

• Template: Select any Scheduler Template. Templates will not be used since this Widget will only be accessed via API, but Mindful Callback requires a Template to be assigned.
• Call Target: Select the appropriate Call Target. The ACD will check the status of this Call Target (via the Widget) to ensure it is ready to register callbacks before transferring inbound calls to Mindful.

For complete instructions on creating Widgets, see Getting Started with Scheduler Widgets.

Datastore configuration

Mindful Datastore allows you to store user data to maintain call context at critical points in an interaction. If you intend to use Datastore, you will need to perform the next few steps within the Datastore user interface.

A Data Set Template contains a collection of Data Keys that allows the Mindful Datastore to store customer data during the callback request process. This collection includes:

• The set's name and description
• How long you want to retain collected data submitted with this Data Set
• What information you want the set to collect (through configuration of Data Keys)
• The API token that is used to associate data submitted via POST requests and return information via GET requests

The Mindful Solution Delivery team can assist with setting up a Data Set Template, as well as a unique authentication token. To create one on your own, use the steps below.

Quick access: Datastore > Data Set Templates

1. On the Data Set Templates page, click Add Data Set Template. This takes you to the New Data Set Template page.

2. Name: Enter a name that will be recognizable to others in your organization.
3. Description: Enter a description for the benefit of other Administrators.
4. Data Retention Period (Hours): Manually enter or use the +/- buttons to customize your Data Retention Period. You can retain data for 1 hour, or for up to 48 hours.
5. API Token: The system automatically generates your API Token.

IMPORTANT

If your API Token is already plugged into your routing logic, regenerating the token here will break that link. To re-establish the link, update your host with the new API Token. Contact Mindful Support for assistance.

6. Template Data Keys: You can select from existing Data Keys in your system or add new keys. The selected keys will filter out any submitted data that does not correspond to one of the configured keys, and will only retain submitted data that matches the configured keys.

Add a Data Key

Click Add Template Data Key. This opens the New Template Data Key modal window.

1. Click in the Manually Enter Data Keys field. 
   1. If your Mindful Datastore instance contains existing Data Keys, select one from the dropdown list that appears.
   2. If not, type the name of a new Data Key here.
2. When finished, click Add.

Your key now appears in the Template Data Keys list.

EXAMPLE

In our example integration, we set up the following Data Keys for callbacks:

• FirstName
• LastName
• AccNum
• CallId

You can configure Data Keys in the same way for any user data that you need to maintain in your environment.

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.

1. 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:  

The VHT 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

2. On the Talkdesk Integrations page (Admin > Integrations), click Add integration. 
3. In the list of available integrations, locate the Custom Integration box and click Add Integration within the box.
4. Configure the Integration as seen below, then save it.

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.

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

Example Action

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

7. Click Execute and review the response. A successful response with a 200 status code should look like the example screenshot below.

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

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.

1. On the Talkdesk Integrations page (Admin > Integrations), click Add integration. 
2. In the list of available integrations, locate the Custom Integration box and click Add Integration within the box.
3. Configure the Integration as seen below, then save it.

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.

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

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

{
   "$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 JSON object fitting the required Input Schema

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

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

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

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

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.

Assignment and dial exits

Set all exits to End Flow.

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.

Conditional Statement preferences

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

Conditional Statement exits

• 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

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

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.

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.

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.

Conditional Statement exits

• 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

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.

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.

PlayEWT (Play Audio step)

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

Play Audio exits

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

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

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.

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.

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.

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.

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.

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

Registering

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 Connecting 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 exits

Select the Queue to Agents step for all exits.

When finished, save and publish the inbound Studio Flow.

Connecting

In the Connecting phase, we must provide a way for Mindful to return calls back to Talkdesk. On the Talkdesk side, we need a way to retrieve data from Mindful Datastore before sending calls to agents. The remainder of this section will walk through these requirements.

1) 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

1. On the Numbers page, click New Phone Number.
2. Fill in the provided fields to set search parameters for your desired number, then click Search for Numbers.
3. 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.

2) 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.

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

Example Action

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

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

3) 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:

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

Callback Flow

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.

Initial Step exits

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

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.

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.

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.

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

Assignment and Dial exits

Select End for all exits.

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

1. On the Flows page, click the ellipsis (...) in the appropriate row, then click Manage Numbers.
2. 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.

4) 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.

5) 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.

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

Exit

Content on the roadmap: Integrating post-call surveys!