Modify the inbound sub script

In NICE CXOne, a sub script is used to create reusable components or functions within a main script. It allows you to define a set of actions or operations that can be called and executed from multiple places within the main script. The inbound sub script used to process inbound calls and queue them to an agent/skill group will need a few modifications. You will 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 Mindful Datastore.

• Transfer to Mindful with required and optional SIP headers.

Inbound sub script parameters

This sub script utilizes variables passed in from the inbound queuing script. When variables are passed in using the Runsub action, you can access them within the sub script using the new variable names {p[n]}, where [n] represents the parameter number. It is important to note that the parameter numbers in the sub script are slightly different than the numbering used in the Runsub action.

For example, consider the Runsub action described later in the inbound queuing script actions section, which invokes the Mindful Inbound sub script:

In this example, the first parameter [0] contains the value of the {firstName} variable. However, when using it inside the sub script, you can retrieve the value using the variable name {p1} because it is the first in the list. Similarly, parameter [1] in the Runsub action becomes {p2} inside the sub script, and so on. Keep this in mind as you follow this guide and refer to the parameters in this section.

Get wait time (Getqueue action)

The Getqueue action performs a lookup against the skill ID passed as parameter [3], represented here as variable {p4}. The metric used in this case is LongestWait, which refers to the longest waiting call. To capture this value, set a variable named waitTime alongside LongestWait. Set the Scope to Ahead, which ensures that only the longest wait for calls ahead of the current call is returned.

This step includes a ZeroQueued exit branch, which is taken when there are no calls currently queuing for the specified skill. In such cases, the call should not proceed with further Mindful logic. Instead, it should proceed to the Return action to exit the sub script and return to the queuing script for the appropriate skill.

Check wait time (If action)

The If action in this script compares the value of waitTime, obtained from the previous Getqueue action, to a configured threshold. If the value of waitTime is below this threshold, it indicates that the call should not proceed with any further Mindful logic. Instead, it should go to the Return action to exit the sub script and return to the queuing script for the appropriate skill.

On the other hand, if waitTime exceeds the configured threshold, the call will continue along the Mindful path within the sub script.

This mechanism is designed to prevent callers from being sent to Mindful when the wait time is low enough that they would spend more time registering and waiting for a callback than they would have waited in the skill queue to speak with an agent. In this example, a two-minute threshold is provided, but you can use a higher threshold if you prefer.

Set wait phrase (Snippet action)

The Snippet action defines the wait time phrase that will be played back to callers, setting their expectations before offering them the opportunity to opt for a callback.

To set the name of the action, right-click the action and enter the desired Caption value. Once that's done, double-click the Snippet action to define the snippet code.

See below for the complete code:

//Determines wait time prompt or phrase to play to caller
IF waitTime > 3600
{
  ASSIGN waitTimePhrase="Current wait time may be more than 1 hour"
}
ELSE
{
  //If wait time is greater than 1800 seconds, set over 30 mins phrase
  IF waitTime > 1800
  {
    ASSIGN waitTimePhrase="Current wait time may be more than 30 minutes"
  }
  ELSE
  {
    //If wait time is greater than 1200 seconds, set over 20 mins phrase
    IF waitTime > 1200
    {
      ASSIGN waitTimePhrase="Current wait time may be more than 20 minutes"
    }
    ELSE
    {
      //If wait time is greater than 900 seconds, set over 15 mins phrase
      IF waitTime > 900
      {
        ASSIGN waitTimePhrase="Current wait time may be more than 15 minutes"
      }
      ELSE
      {
        //If wait time is greater than 600 seconds, set over 10 mins phrase
        IF waitTime > 600
        {
          ASSIGN waitTimePhrase="Current wait time may be more than 10 minutes"
        }
        ELSE
        {
          //If wait time is greater than 300 seconds, set over 5 mins phrase
          IF waitTime > 300
          {
            ASSIGN waitTimePhrase="Current wait time may be more than 5 minutes"
          }
          ELSE
          {
            //If wait time is greater than 120 seconds, set over 2 mins phrase
            IF waitTime > 120
            {
              ASSIGN waitTimePhrase="Current wait time may be more than 2 minutes"
            }
            ELSE
            {
              //If wait time is under 2 minutes, set the minimum wait time phrase
              ASSIGN waitTimePhrase="Current wait time is less than 2 minutes"
            }
          }
        }
      }
    }
  }

In the example above, the code sets the wait time phrase to be used as text-to-speech (TTS) in the sample sub script. However, recorded prompts can also be used by assigning a prompt variable instead of using the waitTimePhrase variable. For instance, instead of:

ASSIGN waitTimePhrase="Current wait time may be more than 30 minutes"

you can use something like this:

ASSIGN waitTimePrompt="MoreThan30Mins.wav"

Feel free to customize the code snippet based on your specific requirements and preferences.

Get Mindful status (Rest API action)

This REST API Action performs an HTTPS GET against the Mindful Scheduler API. To do this, use a Mindful Scheduler widget created for the relevant Mindful Call Target. Mindful will return a set of parameters, including widget_status, which indicates whether the Call Target is ready to register callbacks or not.

To configure this Action, provide the following information:

• Caption — Set the name of the action.

• Widget URL — Pass the widget URL into the sub script as parameter [5], which becomes variable {p6}.

• Verb — Set the verb to GET for the secure HTTP GET method.

• Result Set — Store the results from the Mindful Scheduler API in a variable (named something like mindfulStatus).

Set widget state (Assign action)

The Assign action parses the value of widget_state from the result set obtained in the previous Rest API action. Configure the action as follows:

• Caption — Provide a name for the action, such as Set Widget State.

• Variable name — Assign a variable name to store the widget_state value. In our example, we use widgetState.

• Value — Enter the value {mindfulStatus.widget_state}. This references the variable assigned to the result set in the previous Rest API action (mindfulStatus) and specifies the value to parse (widget_state).

Check Mindful status (Case action)

The Case action checks the value of the previously assigned widgetState variable and determines the next course of action in the Mindful callback flow. Configure the action as follows:

• Variable — Set the variable to the name of the widget state variable assigned in the previous Assign action. For example, widgetState.

• Default branch — Set the default branch to the Return action. This action returns the call back to the inbound queuing script if there is no match.

• Custom cases — To add custom cases, click the Custom Cases (Branches) line, then click the ellipsis (...) on the right.

  • Click Add and set the condition to offer_callback.

  • The destination for this case will be set once the next action in the Mindful callback flow, the Offer Callback (Menu) action, is created.

• Create a second Case with the same destination, but this time with the condition offer_asap_callback.

  If either case returns true, we want to offer a callback.

• Click OK to complete the configuration of the Case action.

Offer a callback (Menu action)

Now that the script has determined that the wait time is above the configured threshold and the Mindful Get Offer API indicates that an offer should be made, it's time to offer a callback via a Menu action.

Configure the Menu action as follows:

• Max digits — Set the maximum digits to 1.

  This allows callers to input a single digit as their response.

• Timeout — Set a timeout that gives callers enough time to respond to the callback offer.

  In this example, the timeout is set to three seconds.

• Default result branch — Set the default result branch to exit the sub script and return to the inbound queuing script using the Return action. If you are using second chance callback (covered later in this guide), we recommend setting a disposition before returning to the inbound queuing script.

  For example, you could create an Assign action called Offer Not Accepted and direct the default branch there.

• Custom case — Click the Custom Cases line, then click the ellipsis (...) on the right to open the Collection Editor.

To add a custom case for the DTMF option presented to the caller:

• Click Add to create a new case.

• Set the condition to match the DTMF digit for the callback option. For example, if the digit is 1, set the condition to 1.

• Set the destination to the next action in the Mindful flow. This could be an action to set a custom SIP header, post to Mindful Datastore, or simply transfer to Mindful, depending on your requirements.

• Click OK to add the new custom case, then close the configuration page.

Double-click the Menu action to set the prompts that will be played to the caller:

In the example above, TTS is used for the prompts. However, if you are using recorded prompts instead, set the menu prompts accordingly. You can use the waitTimePrompt variable created earlier as an example.

For the TTS example used here, the waitTimePhrase variable is played first, followed by the text of the callback offer. The caller is prompted to press 1 to accept the callback offer or press 2 to continue waiting for an agent.

Set the routing token SIP header (SIPXFERPUTHD action)

Use the SIPXFERPUTHD action to set custom SIP headers to pass to Mindful and pass back to NICE CXOne with the callback. This action is designed to allow custom SIP headers to be set prior to a transfer, and should be used instead of SIPPUTHEADER, which may not work in this call flow. Unlike the actions we've seen so far, this action is not found in the Tools tab in Studio, but rather in Framework > Voice > SIP.

A routing token SIP header is required to validate and route SIP requests received by the Mindful SIP router. The routing token for your integration will be provided by the Mindful Solution Delivery team.

To configure this action, specify a name as the Caption parameter (such as Set Token SIP Header), then set the name of the SIP header as the headerName parameter.

Note that the SIP header should start with the X- prefix for transfers to Mindful. In this example, the SIP header X-Mindful-Routing-Token is being set, and the headerValue is the routing token provided by the Solution Delivery team.

You can set multiple SIP headers, using a separate SIPXFERPUTHD action for each. If you send custom SIP headers other than the Mindful routing token, you will need to configure SIP header Metadata Items for each relevant Mindful Call Target.

(Optional) Set Datastore variables (Snippet action)

This optional Snippet action is only required when using Mindful Datastore to pass data between the inbound call and the callback. Mindful Datastore can be used instead of SIP headers for this functionality and may be a better solution if a large number of KVPs need to be passed, or if the integration cannot use a SIP trunk to Mindful.

This action sets the body of the HTTPS POST to Mindful Datastore and formats the data into a JSON string that Datastore will save in the relevant Data Set Template.

To set the snippet, double-click the action to open the snippet text view:

Use the snippet to perform the following functions:

1. Create a DYNAMIC variable called dataValues.

2. Assign custom data into the new dataValues variable.

   Use key names that exactly match the Data Keys configured in your Data Set Template.

   The example includes First Name, Last Name, Account Number, and the CXone Call ID. You can use this same method to save any user data you would like.

3. Create a new variable called dataValuesJson using an asjson() function which takes the content of the dataValues variable and formats it as a JSON string in the new dataValuesJson variable.

4. Create a new DYNAMIC variable called postBody.

5. Assign the value of the call ANI variable passed into the sub script ({p5} in this example) to the postBody variable.

6. Assign the entire body text for the HTTPS post to the postBody variable using the following format:

   {{"customer_contact_number":{postBody.customer_number},"data_values":{dataValuesJson}}
   

7. Lastly, assign the body text to a non-dynamic variable (postBodyJson) to be used in the next Rest API action.

The full snippet text for this example is below:

DYNAMIC dataValues
ASSIGN dataValues.FirstName="{p1}"
ASSIGN dataValues.LastName="{p2}"
ASSIGN dataValues.AccNum="{p3}"
ASSIGN dataValues.CallId="{ContactId}"
ASSIGN dataValuesJson="{dataValues.asjson()}"
DYNAMIC postBody
ASSIGN postBody.customer_number='"{p5}"'
ASSIGN postBody.body="{{"customer_contact_number":{postBody.customer_number},"data_values":{dataValuesJson}}"
ASSIGN postBodyJson="{postBody.body}"

(Optional) Post to Datastore (REST API action)

This optional REST API action allows you to post the data set in the previous snippet action to Mindful Datastore.

Configure the action as follows:

• Caption — Set the name of the action (for example, Datastore Post).

• ServiceAddress — Enter the Datastore URL passed into the sub script by the inbound queuing script (represented as {p7} in this example).

• Headers: Add the two required headers for the HTTPS post to Datastore:

  • Content-Type — application/json

  • Authorization — Enter the authentication token associated with the Data Set Template in Mindful Datastore. This is passed into the sub script from the inbound queuing script, represented as {p8} in this example.

  • For both headers, use the format {Content-Type":"application/json","Authorization":"{p8}"}.

• Parameters — Use the postBodyJson variable set in the previous Snippet action.

• Verb: Set to POST.

Transfer to Mindful (Transfer action)

The Transfer action facilitates the caller's transfer to Mindful to finalize the callback registration.

Configure the action as follows:

• Caption — Name the action (for example, Xfer to Mindful).

• Parameters — Enter two parameters:

  • Destination — Set this to the provisioned SIP number for the relevant Mindful Call Target. When passed into the example sub script as parameter [8], it becomes variable {p9}.

  • CallIerID — Set this to the ANI of the caller, including the national prefix (such as 1 for North America). When passed into the example sub script as parameter [4], it becomes variable {p5}.

• Result Branches — Set all branches except the Default to return to the inbound queuing script.

  This ensures that any issues with the transfer to Mindful are handled correctly, and the caller will be queued to a skill instead.

  Leave the Default branch blank and ignore any warnings when saving the sub script.

Note:

Using a Transfer action will utilize two voice ports, because NICE CXone monitors the call while the caller confirms the callback registration in Mindful.

Alternatively, you can use a Blindxfer action (Tools > Voice Extra > Blindxfer) to perform a blind transfer to Mindful, which consumes no voice ports as the call leaves the NICE CXone platform. However, be aware that a Blind Transfer has less error handling, and issues with the transfer could result in customer disconnection.

Following is an example of a Blindxfer action used in place of the Transfer action shown above:

For more information on the differences between the Transfer and Blindxfer actions, refer to the official NICE CXone Studio documentation.

(Optional) Set disposition actions

The previous section showed that all Result branches from the actions within the sub script (where the caller is not transferred to Mindful) should exit the sub script directly via the Return action. However, it is worthwhile to consider setting a disposition value for each type of result. This allows you to differentiate various scenarios, such as when the Mindful status check fails, the EWT is under the configured threshold, or the caller declines the callback offer. A simple Assign action can be used for this purpose, as shown in the example below:

The example sets a variable named mindfulDisposition with a value that describes the reason the caller was not transferred to Mindful. In this case, the value indicates that the caller did not accept the offer. You can define different dispositions for various results, as illustrated in this example sub script following the logic described in this section:

These dispositions are returned to the inbound queuing script and can be used to make decisions in that script, for reporting purposes, or even for displaying information in a screen pop for the agent.

If you choose to assign dispositions, ensure that the return branches in each step shown in this section, which were previously going directly to the Return action, now point to the relevant Assign disposition action instead. For instance, in the Offer Callback menu action, the default branch should reference the Assign disposition action rather than the Return action:

Return to queue script (Return action)

The Return action serves to direct a call back to the script that initially invoked the current sub script. You only need to configure the ReturnValue parameter when passing data back from the sub script to the invoking script. This includes scenarios like the dispositions described in the previous optional Assign action. In the example below, the {mindfulDisposition} variable is set as the ReturnValue.

This completes the inbound sub script! In the next section, we will complete the inbound configuration by modifying the existing inbound queuing script.

Modify the inbound queuing script

This step typically involves modifying the existing queuing script used to process inbound calls and queue to an agent/skill group. It adds Mindful logic using the newly created sub script described in the previous section and can also add logic around the optional second chance callback flow (described later).

Set Mindful data (Snippet action)

Configure a Snippet action to assign variables with the data required for the Mindful sub script. To do this, add separate Assign lines within the Snippet. Double-click the action to open the Snippet properties text view.

The following shows example assignment logic:

Assign Caller First Name to {firstname} variable.
Assign Caller Last Name to {lastname} variable.
Assign Caller Account Number to {accountNumber} variable.
Assign Call ANI to "1{ANI}".
Assign Target Skill ID for this Call to {skillID} variable.
Assign Mindful Callback Transfer Number to {callbackNumber} variable.
Assign Mindful Scheduler Widget URL to {schedulerWidgetURL} variable.
Assign Mindful Datastore URL to {dsURL} variable.
Assign Mindful Datastore Auth Token to {dsAuthString} variable.

The callANI, dsURL, and dsAuthString variables are only required if you are using Mindful Datastore. You can find the widget and Datastore URLs, as well as the Datastore authentication token, in the Mindful platform UI.

If you are using Datastore, remember that the caller's ANI is used as the index key, and both Mindful Callback and Datastore use national numbers (such as 11 digits for North America). Since NICE CXone uses 10-digit numbers, you will need to concatenate the ANI with the national prefix and store it in a separate variable. Use {ANI} with a prefix of 1 for this purpose, as shown in the preceding example.

Invoke the Mindful sub script (Runsub action)

To invoke the Mindful sub script, configure a Runsub action as follows:

1. Click Choose Script at the top of the action window and select the sub script you would like to invoke.

2. Give the Runsub action a name using the Caption parameter (for example, subMindfulIn).

3. If needed, set a return variable.

   In this example, the data returned by the sub script is assigned to a variable called mindfulDisposition.

4. Select the parameters to be passed into the sub script. To do this, click the ellipsis (...) on the Parameters line, which will open the editor.

   

5. Add the variables to be passed into the sub script, one variable per line, then click OK.

   The variables will be listed in the order they were entered, with a parameter number starting with [0] (as the parameters are passed in an array).

In the sub script, these variables will be available using parameter variable names. Note that the variable names start with the number 1. For example, if you have firstName shown as [0] in the Runsub action, it becomes variable {p1} in the sub script. Similarly, lastName shown as [1] in the Runsub action becomes variable {p2} in the sub script, and so on.

(Optional) Set screen pop (Assign action)

To present variables to agents in a screen-pop window when they answer calls, follow the steps below:

1. Assign the desired variables with a ScreenPop value of True in an Assign action.

2. Click the Assign action to open the properties text view.

3. Set the variables you want to present in the screen pop by creating separate Assign lines within the action. For example:

   Assign callerInfo = {firstName} {lastName} - Account: {accNum}

In this example, the variables firstName, lastName, and accNum are assigned into the callerInfo variable, and the ScreenPop parameter is set to True. By setting the ScreenPop value to True for specific variables, you'll ensure that those variables are presented to the agent in a screen pop window when they answer a call.

Queue to a skill (Reqagent)

To prioritize callbacks returning from Mindful over regular queued calls, use a Reqagent action with a lower priority, as seen below:

1. Click the Reqagent action to open the properties text view.

2. Set the priority to a value lower than that of regular queued calls.

   In this example, we used a priority of 10.

3. Ensure that there is no acceleration set for the Reqagent action.

By giving the Reqagent action a lower priority than regular queued calls, you will ensure that callbacks will be placed at the front of the queue, as the callers have waited for a callback instead of waiting on hold. This prioritization can be achieved using custom priority management in CXone.

Create an Agent Answer API sub script

The next script (callback queuing) will invoke the Agent Answer API via a Connect Request action by invoking a sub script specifically designed for this purpose.

The sub script requires three actions:

• Connect Auth

• Snippet

• Connect Request

Follow the instructions below to configure the sub script.

Connect Auth action

The Connect Auth action will provide the authentication details for the connection configured in the Integration Hub. You only need to enter a ConnectName such as Mindful API in the Actions tab. The Variables tab will automatically assign variables based on the Snippet block configured in the next step.

Snippet action

The Snippet action allows you to assign variables for the API call. Configure the action with the following code:

ASSIGN bearerToken="{authbody.responseContent.access_token}"

DYNAMIC header
ASSIGN header.Authorization = "Bearer {bearerToken}"
ASSIGN header.ContentType = "application/json"
ASSIGN headerjson = "{header.asjson()}"
ASSIGN headerjson = "{headerjson.replace('ContentType','Content-Type')}"

DYNAMIC data
ASSIGN data.ani = "{P2}"
ASSIGN data.metadata.queueId = "{P3}"
ASSIGN data.metadata.agentId = "{P4}"
ASSIGN dataJson = "{data.asjson()}"

DYNAMIC hubPayload
ASSIGN hubPayload.URL = "{P1}"
ASSIGN hubPayload.httpMethod = "POST"
ASSIGN hubPayload.headers = "{headerjson}"
ASSIGN hubPayload.body = "{{"data": {dataJson}}"
ASSIGN hubPayloadjson = "{hubPayload.asjson()}"

Connect Request action

The Connect Request action is responsible for sending the API call, using the authentication credentials and variables configured in the previous blocks.

In the Actions tab, enter details for the first three properties:

• ConnectName — Enter a descriptive name such as Mindful API.

• RequestName — Enter the name of the Request created earlier for the Agent Answer API.

• RequestPayload — Enter the value {hubPayloadjson}.

Leave the other fields with their default values. The Variables tab will be populated automatically, using variables from the Snippet action.

Final step

For the final step, connect the Success path of the Connect Request action to a Wait action.

The sub script is now ready to invoke from the callback queuing script described in the next section.

Create a callback queuing script

The return-call (callback) 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, or...

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

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

Configure the actions in the script as shown below:

(Optional) Set Mindful variables (Snippet action)

This action is only required when using Mindful Datastore to pass data between NICE and Mindful. It sets the URL and auth token for the Datastore GET to retrieve the inbound data into the callback script.

To set the name of the action, right-click the action and configure the Caption with the action name. Close this, then double-click the Snippet action to define the actual snippet code to set the variables, as shown in this example:

(Optional) Get SIP headers (Sipgetheader action)

This action is only required when using SIP headers to pass data between the CXOne inbound/callback routing scripts and Mindful (as opposed to using Datastore). This example shows the value of the X-nice-skillid SIP header being set as variable skillId. This skill ID, set in the inbound script, can be used to target the skill used in the inbound call, so that only one callback script needs to be created, rather than one for every call type or skill.

(Optional) Get data from Datastore (Rest API action)

This Rest API action is used to retrieve data from Mindful Datastore if data has been passed to it during the inbound call. Consult the steps below to configure this action.

1. Give the action a name (such as Datastore Get).

2. Set the service address to be the two variables containing the Datastore URL and the call ANI set in the Snippet action earlier in this script ({dsURL}{callANI}).

3. Configure two headers for the Headers property:

   • One for the content type

   • One containing the authorization token (set in the Snippet action earlier in this script)

     The format will be: {"Content-Type":"application/json","Authorization":"{dsAuthString}"}, where dsAuthString is the name of the variable containing the Bearer token string that was set in the previous Snippet action.

4. Set a variable name for the resultSet (out) property (such as dsReturn).

   This will be used to assign the returned data items to variables in the next Assign step.

(Optional) Set caller info (Assign action)

This example Assign action shows how data retrieved from Mindful Datastore can be assigned to variables for further use.

Each data value can be assigned using the format dsReturn.<data field name>, where dsReturn is the name of the resultSet (out) variable set in the previous Rest API action, and the data field is the name of the field as it is configured in Mindful Datastore. For example, if the data field is called firstName, it can be retrieved using dsReturn.firstName. These can be assigned to individual variables for use in routing decision or agent screen pop.

Queue to a skill (Reqagent action)

After any optional inbound data has been retrieved via SIP headers or Datastore, queue the call to an agent skill. This example shows the target skill using the skillId variable passed from the inbound call, using a custom SIP header or a field from the Datastore GET request.

The callback script is now ready for testing and should look something like the following example:

This example shows data being retrieved using both custom SIP headers and Mindful Datastore. Typically one or the other would be used, not both.

Invoke the Agent Answer sub script after the OnAnswer event

To invoke the Mindful Agent Answer API after an agent has connected to the callback, you will need to attach a Snippet action and a Runsub action to the OnAnswer event, as seen below:

Configure the Snippet action as follows:

• Data — Enter the value shown below (note that our example shows the Skill ID being hard coded, while the ANI and Agent ID are variables):

  ASSIGN agentanswerURL="https://api.getmindful.com/v2/callback/agentAnswer"ASSIGN callANI="+1{ANI}"
  ASSIGN skillId="<SkillID>"
  ASSIGN agentId="{AGENTID}"

• Max String Size — Select the lowest limit ("Limit 2K").

Configure the Runsub action as follows:

• Script Name — Select the script created earlier to invoke the Agent Answer API (sub_Agent_Answer in our example).

• Return Variable — Enter the value RTN.

• Parameters — Configure the parameters noted below:

  0 {agentanswerURL}
  1 {callANI}
  2 {skillId}
  3 {agentId}

With this in place, the API will be automatically called when an agent connects to the call.