Cisco UCCX and Mindful Integration Guide
- 24 Apr 2024
- 22 Minutes to read
- Print
- DarkLight
- PDF
Cisco UCCX and Mindful Integration Guide
- Updated on 24 Apr 2024
- 22 Minutes to read
- Print
- DarkLight
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
The Mindful Callback integration with the Cisco UCCX platform utilizes reliable SIP-based communication without the need for custom development. The example integration presented in this guide allows the UCCX platform to send inbound calls to the Mindful Callback application for a callback offer, while utilizing the Mindful Datastore application to store, update, and retrieve user data for each call.
In this guide, we present configuration requirements for the following processes and components.
- Configuring DIDs for the contact center and high-priority holding queue
- Call routing via UCCX scripts
- Establishing an offer threshold in Cisco UCCX based on the wait time
- Providing a callback offer in the Mindful Callback application.
- Retaining user data between Callback and UCCX
NOTES
- For further validation against additional integration options, please contact a Mindful representative.
- This article is not intended as a configuration guide for a Cisco UCCX environment. For help with UCCX deployments and configuration, consult the official Cisco documentation.
- Example UCCX scripts can be obtained in the Mindful Download Center at downloads.mindfulcx.com.
BEST PRACTICES
- When quoting the estimated wait time prior to offering a callback, it is a best practice to set an upper limit for the amount of time that can be quoted. For example, if the wait time exceeds 10 minutes, you might choose to say "...more than than 10 minutes from now" rather than quoting an exact time.
- We recommend setting a minimum offer threshold based on the current estimated wait time to ensure that callback offers are not made when wait times are very low. You may also wish to check agent availability prior to sending calls to Mindful Callback.
Overview
This integration guide covers the following topics:
- Components and architecture
- Step 1: Configure your Mindful account
- Step 2: Configure your SBC
- Step 3: Configure your UCCX environment
- Call flow diagram
- Optional: Consolidate return-call destinations
- Optional: Offer Second Chance Callback
Components and architecture
Expand the following content to to review the definitions of acronyms and terms used throughout this guide. You can also view a high-level overview of the components and architecture of the integration before getting started.
Definitions and acronyms
| Term | Definition |
|---|---|
| REST | Representational State Transfer is a set of rules used to create web services. |
| JSON | JavaScript Object Notation is a standard data interchange format. |
| ECC variables | Expanded Call Context variables are used by ICM to store and preserve contextual call data. |
Components and architecture
.png?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
| Mindful Callback component | Description |
|---|---|
| SIP Proxies | Send and receive SIP messaging |
| RTP Proxies | Establish and maintain RTP streams |
| Callback Application | Tracks callbacks and system configuration |
| Management Interface | Provides a user interface for administrators |
| UCCX component | Description |
|---|---|
| CUCM | Cisco Unified Communications Manager provides call control and session management features. |
| SBC | Avaya Session Border Controller for Enterprise is used as an edge device to control traffic in and out of the ACD environment. |
Step 1: Configure Your Mindful Account
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
- Callback Telephony Type: Select SIP.
- Callback Number: This will be configured in a later step.
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 SIP numbers as needed and assign a number to each Call Target in your Organization. This is the number to use when configuring the SIP endpoint to which to 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
- On the Data Set Templates page, click Add Data Set Template. This takes you to the New Data Set Template page.
- Name: Enter a name that will be recognizable to others in your organization.
- Description: Enter a description for the benefit of other Administrators.
- 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.
- 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.
- 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.
- Click in the Manually Enter Data Keys field.
- If your Mindful Datastore instance contains existing Data Keys, select one from the dropdown list that appears.
- If not, type the name of a new Data Key here.
- 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.
Mindful Datastore integration
Quick access: Call Targets > Your Call Target > General tab > Mindful Datastore Integration
Enable the Mindful Datastore integration for each Call Target to be used with the Datastore application, and select the Data Set Template that will be used. Enabling the Datastore integration for your Call Targets allows Mindful Callback to update your Datastore records for changes in the customer callback phone number and the scheduled callback time.
This step is essential to ensure that you are able to retrieve user data in the callback UCCX script that will be created in a later step.
Optional configuration
The Callback application supports SMS callback notifications, voice-to-messaging transitions, and proprietary drop-in web widgets to provide a digital callback offering.
To learn more about the many options available to configure your Call Target, see the Call Targets reference article.
Step 2: Configure Your SBC
Mindful Callback integrations can function with different Session Border Controller (SBC) products regardless of the ACD platform used in your environment. Click any of the links below for instructions on integrating your chosen SBC.
- Avaya Session Border Controller Enterprise (SBCE)
- Cisco Unified Border Element (CUBE)
- Audiocodes Mediant
- Ribbon SBC
- Oracle SBC
We plan to add integration guides for more SBC products over time. Check back here for updates or let us know if you would like us to cover a specific SBC!
Step 3: Configure Your UCCX Environment
Several additional steps are required to prepare the UCCX environment for the integration:
- Create a CUCM Route Pattern
- Create a Dial Peer on the Cisco SIP Proxy
- Configure UCCX scripts
- Final steps on the Script Managment and Application Management page
Create a CUCM Route Pattern
You will need a set up a Route Pattern in CUCM to allow dialing out from CUCM to your SBC. Use the following image as a guide when configuring the Route Pattern.
.jpg?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
- Route Pattern: Set the pattern to be identified for numbers that will use this route. In our example configuration, we are designating 11-digit numbers beginning with 91 to use this route.
- Gateway/Route List: Specify the destination of calls matching this Route Pattern. In our example, we are sending these calls to our Cisco gateway.
- Called Party Transformations > Discard Digits: Select the built-in PreDot Transformation, which will remove any digits prior to a dot (.) in the Route Pattern field. In our example, this Transformation removes the initial 9 in the Route Pattern field.
Create a Dial Peer on the Cisco SIP Proxy
Configure a Dial Peer to send calls from CUCM that begin with 1 and contain 11 digits to your SBC. In our example integration, we used a 3900E ISR as the SIP proxy.
Use the following example as a guide when creating the Dial Peer:
dial-peer voice 1 voip
destination-pattern 1.........
session protocol sipv2
session target ipv4:10.10.10.10:5060
session transport udp
incoming called-number 1.........
voice-class codec 12
voice-class sip early-offer forced
voice-class sip pass-thru headers unsupp
voice-class sip referto-passing
dtmf-relay rtp-nte
no supplementary-service sip refer- Destination pattern: 1...........
- session target: Specify ipv4 and enter the IP address of your SBC's internal signaling interface
- dtmf-relay: Specify rtp-nte to allow RFC2833 DTMF
Configure UCCX scripts
The integration presented in this guide uses the Mindful Datastore application to pass user data between UCCX routing scripts and Mindful Callback. The scripts will use REST API calls to Mindful Datastore to create records for each call's user data. Mindful Callback will then make updates to the Datastore records for any changes in callback phone numbers or scheduled callback times, and finally a second UCCX script will retrieve the data to re-attach to callbacks received from Mindful Callback.
An inbound/queueing UCCX script will send HTTP POST requests to Mindful Datastore, and a callback UCCX script will send HTTP GET requests to retrieve stored user data. Both scripts use a Make REST Call step to send the POST or GET requests. This method of handling user data can be especially effective when using unsecured SIP, or when any SIP devices in the signaling path might not handle custom SIP headers well.
Click both of the following tabs for instructions on creating the required UCCX scripts.
1. Inbound/queuing script
The inbound/queuing script will accomplish several tasks:
- Check to determine if the ANI begins with +1, and remove the +1 if so.
- Manage user data strings.
- Post user data to the mindful Datastore application.
- Send calls to the Mindful Callback application .
- Alternatively, send calls to a holding queue in case of failure.
Sample script and variables
The following images show a sample .aef script file and the definitions of variables used.
- When a call enters the inbound script, the script first retrieves the ANI to see if it begins with +1. If so, the script removes this leading prefix from the ANI.
- Next, the JSON string containing the user data to be sent to Datastore is concatenated together.
.jpg?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
IMPORTANT
- The ds_contenttype string must contain application/json.
- The ds_auth string must match the Authorization string from the HTTP POST, including the word Bearer. The following example shows where the Authorization string is located in the POST:
NOTE
Formatting for the string concatenation is strictly enforced.
- All double quotation marks must be escaped in single quotes with a backslash ('\"'), as seen in the following example.
- If you use separate SET lines to concatenate the ds_content string, remember to open and close the full string with curly brackets enclosed in double quotation marks ("{" and "}").
|  |
 |
If the Call Redirect block fails, the call will be queued as normal.
2. Callback script
The second UCCX script will be invoked when a callback arrives at the queuing route point. The callback UCCX script will perform two main functions:
- Check to determine if the ANI begins with +1, and remove the +1 if so.
- Concatenate a string for use in the HTTP GET request to the Mindful Datastore application.
- Send an HTTP GET request to Datastore to retrieve stored user data.
- Convert user data into JSON format.
- Prepare user data to be assigned to UCCX call variables.
- Assign user data to UCCX call variables for later use.
- Queue the call to an agent at high priority.
Sample script and variables
The following images show a sample .aef script file and the definitions of variables used.
NOTE
The Document variable (ds_result_json) used in our example script may not be supported in UCCX version 11.5 or earlier. If you are using an older version of UCCX, you may need to use Javascript as an alternative to manage this variable.
- When a call enters the inbound script, the script first retrieves the ANI to see if it begins with +1. If so, the script strips this leading prefix from the ANI.
- Next, the script concatenates a string to be used in the HTTP GET request to Mindful Datastore. The concatenated string should be in the format <Datastore URL>?customer_contact_number
|  |
 |
|  |
- Once all of the data has been parsed, a Set Enterprise Call Info block will assign the data to specific UCCX call variables (both Peripheral and ECC variables). These variables can then be used for agent screen-pop information (via Finesse) or other reporting purposes.
- With all user data handled, the script then queues the call to an agent at high priority.
Final steps to configure UCCX scripts
- Upload each of the scripts you created earlier into the UCCX Administration application on the Script Management page. Include both the inbound and outbound script.
- Create two new applications on the Application Management page. Create one for the inbound call script and another for the callback script.
- Create two new Triggers. Create one for the DN used for inbound calls and another for the DN of the route point for callbacks.
Call flow diagram
Callback Call Targets use a complete phone number for the inbound call transfer. Each Call Target represents a queue/skill/group, such as Sales or Billing.
(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.
Configure consolidated return-call destinations
This integration guide has assumed that each Call Target is configured with a Call Center Phone Number leading to a single group of agents in your call center. However, in some ACD environments, the same group of agents are spread out among multiple queueing destinations. Since a Call Target is intended to serve a particular agent group, there needs to be a way to deliver callbacks and return-to-hold calls to a single destination that can ultimate route calls throughout the entire agent group.
You can configure a Call Target to send calls to a Call Center Phone Number that leads to a shared disposition destination, then make further routing decisions based on data attached to the call. This form of queue consolidation allows you to route return calls among multiple destinations representing the same group of agents.
How it works
Using a consolidated callback destination requires custom data to be passed to Mindful Callback with inbound calls to identify their ultimate return destinations. This can be done in two ways:
- Send the destination to Callback via SIP Headers. This requires that you configure additional Metadata Items for each affected Call Target. Or...
- Post the destination to the Mindful Datastore application, using the customer's ANI as the data key. This method can be used even when calls are delivered via the PSTN rather than SIP.
In either case, Callback will re-attach the custom data to the return call (whether it is a callback or a customer returning to hold) and deliver the call to a single return-call disposition destination. From there, you can use the custom data to route the call to the appropriate agent groups.
NOTE
We recommend using different universal return destinations for callbacks and callers who chose to hold. The choose-hold destination is only needed if the Callback Offer or the End of Day Handling > Return to Hold settings are enabled.
EXAMPLE
Consider the following example. Let's say you have the same agent skill assigned to different queueing destinations labeled 111, 222, and 333. You have a single disposition destination for callbacks and another for return-to-hold calls. In this case, the routing path for a callback could look like this:
- You identify that a particular new inbound call should ultimately be delivered to 333, so you attach that destination number to the call as custom data when sending it to Callback for treatment.
- When the time comes, Callback delivers the return call (a callback in this case) with the destination number still attached.
- When the call arrives at the callback disposition destination on your ACD, additional routing logic ensures that the call ends up with agents at 333.
- The appropriate priority is set, and the call is delivered to an agent.
(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.
Configure Second Chance Callback
Second Chance Callback is a best-practice methodology that can increase the take-rate of callback offers and lower the abandon rate in your call center's holding queues. With a few updates to your routing logic, you can provide additional callback offers to customers waiting on hold who have already declined an initial offer.
There are a variety of reasons that customers might appreciate a second chance to accept an offer of a callback. For example, perhaps something has come up that requires their attention and they can no longer wait on hold. Perhaps the quoted wait time was low when they declined the first offer but queue conditions have quickly changed and resulted in a longer hold time. Regardless of the scenario, Second Chance Callback ensures that customers have the callback option available when they need it.
Benefits
Our research shows positive results for call centers offering Second Chance Callback, including:
- Keeping customers in control with additional options while holding.
- Reducing abandoned calls in the holding queue by offering an alternative option.
- Fully controlling Second Chance offers in your ACD with no integration constraints.
- Adding another tool to address unexpected increases in hold time.
- No additional requirements for customers. They are not required to respond to Second Chance prompts, but can instead simply continue to wait on hold if they choose.
ACD configuration
Most configuration for Second Chance Callback is done on your ACD platform, so the technical implementation will vary based on your integration. In all integrations, the following logic must be introduced to interact with customers in the holding queue.
- Whether offers are made in your ACD or in Mindful Callback, the process begins with the first offer. If the initial offer is accepted, then a callback is registered and no Second Chance offer is needed.
- If the initial offer is not accepted, callers are routed to a holding queue.
- A timer begins in the holding queue. When the specified time expires, another callback offer is made.
- If the customer declines the Second Chance offer, then the timer is reset, and another offer will be made when it expires again.
- If the customer accepts the Second Chance offer, the call is sent to Mindful Callback for treatment.
NOTE
You can add logic into the routing script to limit the total number of offers made per call.
THINGS YOU'LL NEED
If you wish to use a single Call Target for normal inbound calls and Second Chance calls, you will need:
- Two Phone Numbers provisioned for the same Call Target.
- The Return to Hold Call Target setting disabled. Offering a hold option in Mindful Callback after a customer has already chosen to leave the holding queue can negatively impact the customer experience.
If you wish to use separate Call Targets for normal inbound calls and Second Chance calls, you will need:
- Two Call Targets configured with the same Call Center Phone Number targeting the same group of agents.
- The Return to Hold setting disabled for the Second Chance Call Target. The setting can still be enabled for the normal inbound Call Target.
For either method, you will also need:
- The ability to capture DTMF input from customers in your holding queue.
- The ability to play audio prompts to customers in your holding queue based on a timer.
Mindful Callback configuration
There are two alternatives for preparing your Mindful Callback account for Second Chance Callback. Each alternative introduces its own advantages and drawbacks.
- Option 1 (best practice): Use separate Call Targets for normal inbound calls and Second Chance calls.
- Option 2: Use a single Call Target for both normal inbound calls and Second Chance calls.
Option 1 (best practice): Use separate Call Targets
This option uses the first Call Target to service normal inbound callback requests with a second Call Target dedicated to servicing Second Chance callback requests. For an initial offer, send the call to the first Call Target. For a Second Chance offer, send the call to the second Call Target. This option separates the two types of calls for ease of reporting and real-time analysis..png?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
| Advantages | Drawbacks |
|---|---|
| Call Detail reporting is more convenient. | ECBT is not combined between the two Call Targets. Therefore, ECBT on the normal inbound Call Target may be lower than it should be, since the call volume from the Second Chance Call Target is not included in the calculation. |
| Real-time monitoring clearly distinguishes the two call types. | |
| You can enable the Return to Hold option on the normal inbound Call Target while disabling it on the Second Chance Call Target. |
Option 2: Use a single Call Target
The second option uses a single Call Target to service both normal inbound callback requests and Second Chance requests. This method is easier to configure and maintain, but it introduces a few additional drawbacks to consider.
.png?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
| Advantages | Drawbacks |
|---|---|
| Configuration is simpler. | When a Second Chance ASAP callback is registered, it will be placed at the back of the virtual queue or waitlist. This can result in customers who accept Second Chance offers waiting longer than they would have if they remained in the holding queue. |
| Return to Hold should not be offered by the Call Target. This can affect your offer strategy for normal inbound calls, which may not be intended. | |
| Reporting on Second Chance interactions requires additional steps. | |
| Real-time monitoring combines normal inbound callback requests and Second Chance requests together. |
Reporting on Second Chance Callback interactions
As noted in the lists of advantages and drawbacks, reporting on Second Chance interactions varies depending on whether you use one or two Call Targets.
Reporting with separate Call Targets
On the Metrics, Executive Summary, and Call Detail pages, use the Call Target filter to view data only for the Second Chance Call Target. This will exclude any data from initial offers and callers that chose to hold. If you offer Second Chance for multiple lines of business, you can add all of your Second Chance Call Targets into a shared Reporting Category to view all Second Chance interactions.
On the Callback Status page, review real-time statistics for the Second Chance Call Target or use the Category filter to limit the view to only Second Chance Call Targets.
Reporting with a single Call Target
When using a single Call Target, additional configuration is required and the reporting capabilities are limited.
Preparation:
- Provision two Phone Numbers in the Mindful Callback user interface, and assign both Phone Numbers to the same Call Target.
.png?sv=2022-11-02&ss=b&srt=o&spr=https&st=2024-05-04T07%3A46%3A38Z&se=2024-05-04T07%3A56%3A38Z&sp=r&sig=yIKeQrl1Fw9e6Pxm2TpZuagKNGTw%2Fm0ZUYtoHKsFbwc%3D)
- In your routing scripts, send normal inbound calls for callback treatment to the first Phone Number.
- Send Second Chance calls for treatment to the second Phone Number.
Reporting:
- On the Call Detail page, export the reporting data to CSV. In the exported CSV file, the Call Target Phone Number to which each call was sent will be noted in the Source column.
- In the CSV file, filter the Source column for all records matching the Second Chance phone number. The remaining data will include only Second Chance interactions.
NOTE
When using a single Call Target, the Callback Status, Metrics, and Executive Summary pages will combine Second Chance interactions with initial offers and callers that chose to hold.
Was this article helpful?