Modify the inbound IVR script

The inbound IVR script used to process inbound calls and queue them to an agent/skill group will need a few modifications. You'll need to add functionality for the following steps:

• Fetch the EWT and turn it into a phrase to play back to callers.

• Check the EWT to make sure it is above a defined threshold before offering a callback.

• Check Mindful status to ensure it is available and ready to process requests.

• Play the EWT phrase and offer a callback.

• (Optional) Post data to the Mindful Datastore.

• Transfer the call to Mindful with optional SIP headers.

Create the EWT phrase function

The EWT step in the inbound IVR script provides the EWT in seconds. To convert the EWT into a phrase that can be played back using TTS (such as "Current Wait Time is 15 minutes"), a function needs to be created in the inbound IVR script within Five9 VCC Administrator.

To create the function, follow these steps:

1. Open the inbound IVR script.

2. Select "Script" and then "Functions" from the menu to open the Functions window.

   

3. Click Add to create a new function.

   

4. Provide a name for the function, such as convertEWT.

   Set the type to STRING, as the output will be a string containing the EWT phrase.

   Add a single function argument named EWT with the type set to Integer, as the input will be the EWT in seconds.

5. For the JavaScript code, you can use the following sample code as a template. Paste it directly into the "Function implementation (JavaScript)" section.

   When copying and pasting code between applications, the formatting or syntax may change, so it is important to review the code for any formatting or syntax errors after pasting it into the function.

   {
   
       var oldestCallWaiting = EWT;
       var waitTime = "";
   
       if(oldestCallWaiting<60) {
   
           waitTime = "Current wait time is less than 1 minute."
   
       } else if(oldestCallWaiting>7200) {
   
   	waitTime = "Current wait time may be 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;
   
       }
   
       return waitTime;
   
   };

   In the sample code provided above, you can customize the phrasing within the lines that set the waitTime variable. There are three lines that handle this:

   • One line sets the minimum announced time. For example, if EWT is less than 120 (two minutes), then waitTime is set to "Current wait time is less than two minutes".

   • Another line sets the maximum announced time. For example, if EWT is greater than 7200 (two hours), then waitTime is set to "Current wait time is more than two hours".

   • A third line sets the announced EWT if it falls between the minimum and maximum values. For example, if EWT is 5400 seconds, then waitTime is set to "Current wait time is approximately one hour, 30 minutes".

6. Use the test button to ensure the function returns the expected output values based on different inputs.

7. Click OK to save the new function, then again to close the Functions window.

Add custom variables

Our example inbound IVR script uses custom variables created directly within the script. You can add custom variables within the IVR script editor (Script > Variables). Below is a list of the variables referenced in this section, which we will define along the way:

Set variables (Set Variable module)

Start with a Set Variable module to assign variables containing data that will be sent to Mindful. This data can be retrieved in the callback IVR script either by posting it to the Mindful Datastore or by setting it into custom SIP headers included in the SIP INVITE during the transfer of the inbound call to Mindful.

One useful scenario for transferring data between the inbound call and the callback is when using a single callback IVR script and DNIS for all call types. In the example screenshot below, the skillName variable is set. This variable can be sent to Mindful when the caller is transferred. When the customer is called back and transferred to the queue, the callback script will receive the skillName variable and can target it in the Skill Transfer module.

If you choose to use the Mindful Datastore, the caller's ANI will be used as the index key. It's important to note that Mindful Callback and Mindful Datastore use national numbers (such as 11 digits for North America), while Five9 uses 10-digit numbers. To accommodate this, concatenate the number with the national prefix and store the value in a separate variable, referred to as callANI.

Here's an example of the ANI concatenation process:

Get EWT (System Info module)

Next, you will need a System Info module to retrieve the Estimated Wait Time in seconds from the Skill Transfer module specified in the Lookup Condition field. The returned parameter is assigned to an integer variable (in this example, named EWT).

Check EWT (Case module)

Use a Case Module to check the EWT value returned by the previous System Info module. If the EWT exceeds the configured threshold (120 seconds in this example), continue with the Mindful logic. If the EWT does not exceed this threshold, do not present the caller with the callback offer and instead queue the call to a skill.

Set EWT phrase (Set Variable module)

Set a string variable with the EWT phrase to speak to the caller in the Set Variables module. Pass the EWT (seconds) into the function created earlier, which will return the phrase.

Build Get Offer URL (Set Variable module)

You will need a Set Variable module to build the full URL of the Mindful Get Offer API endpoint, by inserting the Call Target ID in the middle of the URL and appending a query string to the end.

Follow the steps below to build the URL within the Set Variable module:

1. First, assign a constant value containing everything in the URL up to the Call Target ID (https://api.getmindful.com/v2/callback/callTargets/) to the getOfferURL variable:

   

   The value of getOfferURL at this point will be https://api.getmindful.com/v2/callback/callTargets/.

2. Next, use the CONCAT(STRING, STRING) function to append the Call Target ID (via the call_target variable) to the end of the URL. Pass in the getOfferURL variable as the first argument and the call_target variable as the second argument:

   

   The value of getOfferURL at this point will be https://api.getmindful.com/v2/callback/callTargets/<Your Call Target ID>.

3. Lastly, use the CONCAT(STRING, STRING) function again to append the final part of the URL (/offerDecision plus the query string ?sourceType=voice) to the end. Pass the getOfferURL variable as the first argument and a constant value of /offerDecision?sourceType=voice as the second argument:

   

   The final value of getOfferURL will be https://api.getmindful.com/v2/callback/callTargets/<Your Call Target ID>/offerDecision?sourceType=voice.

Get offer decision via API (Query module)

Next, add a Query module to send a request to the Get Offer API endpoint and parse the results to be used in a routing decision in the IVR script. The API response will contain a variable indicating whether the Mindful Call Target is ready to offer callbacks.

1. On the General tab, assign getOfferURL as the URL Part:

   

2. On the Request tab, add an HTTP header named Content-Type and assign it a value of application/json.

3. In the Authorization Profile section, select the Auth Profile created earlier for Mindful OAuth credentials:

   

4. On the Responses tab, use the following Regular Expression in a RegEx function to parse the value of the shouldOffer attribute returned by the API into the mindfulShouldOffer variable created earlier in Five9:

   \"shouldOffer\"\s*:\s*(true|false)

   

Check getOffer results (Case module)

Add a Case module to analyze the result of the mindfulShouldOffer variable obtained in the previous step. If the result is true, send the call to the next step to offer a callback with a Menu module. For any other result, send the call to queue.

Offer a callback (Menu module)

In this Menu module, the caller will first hear the EWT phrase and then be presented with the choice to receive a callback or wait for the next available agent.

The configuration takes place in the General tab, where you can set up the choices and their corresponding actions based on the DTMF digits provided by callers. These actions should be linked to branches defined in the Branches tab.

Configure two branches (Callback and Queue), with a default No Match branch in case of no matching input.

In the Prompts tab, play the EWT phrase and callback offer. To add the prompts, click Add.

For the EWT phrase, use TTS prompts. Configure the prompt to play the EWT phrase stored in the ewtPhrase variable. Enable the Interruptible setting to allow callers to provide input without listening to the entire prompt set.

For the callback offer, create another set of TTS prompts. Customize the prompt to convey the callback offer, like so:

Once all the prompts are added and configured, click OK to save the module configuration.

Set SIP headers (Set Variable module)

To facilitate data exchange between Five9 and Mindful using custom SIP headers, you can use a Set Variable module. Passing SIP headers serves as an alternative to the Mindful Datastore. In this example, the KVList variable toMindful is populated with three custom SIP headers (one required, two custom):

• (Required header) X-Mindful-Routing-Token — This header plays a vital role for the Mindful SIP Router. It ensures the validation and accurate routing of the SIP request from Five9 to Mindful.

• Custom headers — The example above shows two custom headers used to pass specific user data. One contains the skill name and another contains the Five9 Call ID. You can add any other custom headers the same way.

To assign values to the KVList:

• Click Add to create a new variable assignment.

• Use the PUT(KVLIST, STRING, STRING) function, as demonstrated in the following example:

In this assignment, the variable dropdown is not critical, but a variable must be selected. The built-in __BUFFER __ variable can be chosen for this purpose.

• Select "Function" for the Assigned Value.

• Use the PUT(KVLIST,STRING,STRING) function. Under function arguments, add three entries:

  • toMindful (Variable) — This specifies the KVList to store the custom SIP header.

  • X-Mindful-Routing-Token (Constant) — This is the name of the custom SIP header. It is advisable to use the "X-" prefix when adding custom SIP headers.

  • Call.Call_id (Variable) — This represents the value of the custom SIP header. In this example, the X-Mindful-Routing-Token SIP header is being populated with the Mindful routing token provided by the Mindful Solution Delivery team.

(Optional) Post to Datastore (Query module)

To transfer user data between Five9 and Mindful, you can send and retrieve data to and from Mindful Datastore rather than SIP headers. This method is suitable when dealing with a substantial amount of data, preventing potential issues that may arise from an excessive number of custom headers in the SIP packets.

To send data to Mindful Datastore, follow the steps below:

1. Add a Query Module and provide it with a name (such as dsPost).

2. Enter the Mindful Datastore URL.

   To learn how to obtain the Datastore URL and your API token, see Mindful Datastore.

3. Set the Method to "POST".

4. On the Request tab, add a new HTTP header named Authorization and include your Mindful Datastore API token, including the "Bearer" string.

5. In the body section, select "raw" and set the Content type to JSON (application/json). This will generate a new HTTP header in the top section.

   

   The body should start with {"customer_contact_number": followed by the ANI variable "&&callANI&&". The data_values section should contain the data corresponding to the keys in your Mindful Data Set Template.

   For example, if your template includes the keys FirstName, LastName, AccNum, CallId, and SkillName, the complete text should be:

   {"customer_contact_number":"&&callANI&&","data_values":{"FirstName":"&&Contact.first_name&&","LastName":"&&Contact.last_name&&","AccNum":"&&Contact.acc_num&&","CallId":"&&Call.call_id&&","SkillName":"&&skillName&&"}}

   Ensure that the format remains the same, but with the appropriate data items inside the data_values section. Each data value should consist of the Mindful Datastore key name (such as FirstName) and the variable that contains the corresponding data (such as &&Contact.first_name&&).

   On the Response tab, add a single entry for HTTP status code 200. You do not need to add anything other than the HTTP code (to/from 200).

   

6. Save the Query module when finished.

Transfer to Mindful (3rd Party Transfer module)

To transfer the call to Mindful, add a Transfer module and provide the number assigned to the relevant Call Target in Mindful. It's important to note that the numbers used for transferring calls to Mindful should be registered with Five9 to utilize the TLS SIP trunk for the transfer.

Follow the steps below to enable the transfer of the Mindful Routing Token SIP header (along with any optional custom SIP headers):

1. Select the Return After 3rd Party Call checkbox.

2. Select the Send Data to 3rd Party checkbox.

3. In the dropdown menu next to the checkbox, choose the KVList variable that contains the custom SIP headers. In this case, it would be the toMindful variable mentioned earlier in this guide.

   

4. Save the configuration of the 3rd Party Transfer module when finished.

Queue to skill (Skill Transfer module)

Upon reaching the Third Party Transfer module, there are two possible exits:

If the transfer to Mindful is successful, the call will conclude after the caller completes the callback registration. In cases where the call cannot be transferred to Mindful, issues may arise within the flow, resulting in a failed transfer to Mindful. This can happen in a few scenarios:

• The EWT falls below the configured threshold.

• The Mindful Call Target is unable to register callbacks.

• The caller declines the callback offer.

In such instances, the call should be directed to queue for an agent skill. The call's priority in this scenario should be set as the standard priority for an inbound call to the respective skill, while being lower than the priority assigned to Mindful return calls.

With these modules in place, you can now successfully test an offer threshold, announce the EWT, offer callbacks to customers in the IVR, and transfer calls to Mindful to register a callback. In the next section, we will detail the required modules for the other side of the interaction — the returned callback.

Create a callback IVR script

The return-call (callback) IVR script is typically a new script created to queue return calls from Mindful to an agent/skill group. The key functionality is to:

• (Optional) Retrieve any inbound call data via custom SIP headers from Mindful.

• (Optional) Get inbound call data from the Mindful Datastore.

• Queue to an agent skill at a priority higher than inbound calls for the same skill.

The remainder of this section details the configuration needed for each step.

Set variables

In this section, we will discuss the custom variables used in this sample callback IVR script. To add custom variables, follow these steps:

1. Open the IVR script editor.

2. Select the Script menu.

3. Click Variables to access the variable management section.

Now, let's take a look at the list of variables referenced in this script:

(Optional) Get SIP headers (Set Variable module)

In this section, we will focus on the retrieval of custom SIP headers from Mindful using the Set Variable module. These custom SIP headers are sent to Mindful during the inbound call transfer from the inbound IVR script.

Let's take a look at an example of how this is done using a KVList variable called mindfulSIPHeaders and the TOKVLIST(STRING) function:

• Assign the mindfulSIPHeaders KVList as the variable to populate.

• Use the TOKVLIST(STRING) function as the assigned value.

The function argument is a variable called UUI-XHeaders, which is a built-in Five9 variable responsible for retrieving any custom headers starting with the X- prefix.

(Optional) Set ANI (Set Variable module)

If you plan to use the Mindful Datastore to transfer data between the inbound call and the callback, you will need to include this optional Set Variable module. The purpose of this module is to accommodate the different phone number formats used by Mindful Datastore and Five9 IVR scripts.

This module populates a string variable called callANI with the Five9 call ANI concatenated to the national prefix. The national prefix includes the necessary digits (such as 1 for North America) to ensure compatibility with Mindful Datastore's phone number format.

This step is crucial because Five9 IVR scripts typically use numbers without the national code (such as a 10-digit number in North America) while Mindful Datastore requires the full number with the national prefix (which would require an 11-digit number in North America).

(Optional) Request data from Datastore (Query module)

If you intend to use the Mindful Datastore for transferring data between the inbound call and the callback, you will need to include a Query module configured as follows:

• General tab — Provide a name for the module and enter the URL for the GET method specific to your Mindful Datastore integration.

  The URL may differ from the example provided, so it's essential to verify it on the Data Set API page (Datastore > Data Set Templates > Data Set API) of the Mindful platform.

  The URL should include a parameter named customer_contact_number, which will be assigned the value of the ANI variable set in the previous Set Variable module.

• Method — Select "GET".

• Request tab — Configure the Request tab as you see below:

• HTTP Headers — Add two HTTP headers:

  • The first header should contain the Authorization token from the relevant Mindful Data Set Template. This token should be the same token (including "Bearer") used in the Datastore Post Query module in the inbound IVR script.

  • The second header should have the name Content-type and the value application/json.

• Responses Tab — See the example below:

  

• Parsing the response — The response should be parsed into a function. Choose a valid KVList variable name, such as DS_DataValues, and set the Function Name to TOKVLIST(STRING).

  This will store all the data from the Datastore lookup in the KVList variable, ready to be used in the IVR script for routing, screen-pop, or any other use.

  

• Once you have configured the General, Request, and Responses tabs, click Save.

(Optional) Look up contact record (Lookup Contact Record module)

You can use this module to search the local contact list based on the caller's ANI. If a matching contact is found, you can add any additional contact or custom data from the data passed in SIP headers or the Mindful Datastore to that contact. This allows you to enrich the contact's information with relevant data if it already exists in the local contact list.

(Optional) Set contact variables (Set Variables module)

This Set Variables module is used to populate contact and call information based on the data received from Mindful during the inbound call. The data includes contact information, which can be written to the local contact record, as well as call information such as the inbound Call ID and the skill into which to queue the callback.

Here is an example of how to assign the inboundCallId string variable with the value of the X-five9callid SIP header retrieved in the getSIPHeaders module:

• Assign the value of the X-five9callid SIP header to the inboundCallId variable using the GET(KVLIST,STRING) function, extracting the value from the mindfulSIPHeaders KVList variable.

• Similarly, the Contact.first_name contact variable can be populated with a data value from the Mindful Datastore.

• Assign the value of the FirstName data field (as an example) from the DS_DataValues KVList variable to the Contact.first_name contact variable using the GET(KVLIST,STRING) function.

These assignments allow you to capture and use relevant information for further processing in the IVR script. You can capture any additional information you need in this way.

(Optional) Update contact record (Contact Update module)

This module is responsible for writing the updated contact record data, such as Contact.first_name, into the local contact record. This step ensures that the contact information is available for display on the agent's desktop or any other relevant systems.

By executing this module, the modified contact data will be saved and synchronized with the local contact record. This allows agents to access up-to-date contact information during interactions, enhancing the overall customer experience and facilitating efficient communication.

Queue to a skill (Skill Transfer module)

This module leverages the skillName variable, which was populated earlier using data passed to Mindful during the inbound call. The skillName variable is crucial in determining the appropriate skill to target for each callback.

Callbacks should be queued to the skill at a higher priority than any inbound calls for the same skill. This priority setting ensures that customers who requested a callback are prioritized and connected with the next available agent promptly.

In the example above, a priority value of 20 is assigned to the callback, while inbound calls for the same skill have a priority of 10. This prioritization scheme ensures efficient handling of callbacks and provides a seamless experience for both customers and agents.