Genesys Cloud and Mindful Integration Guide

The Mindful Callback integration with the Genesys Cloud platform utilizes reliable SIP-based communication without the need for custom development.

In this guide, we present configuration requirements for the following processes and components.

• Configuring DIDs for the contact center and high-priority holding queue
• Routing for inbound calls, choose-hold calls, and callbacks
• Establishing an offer threshold in Genesys Cloud based on wait time
• Providing a callback offer on the Mindful platform
• Retaining user data between Callback and Genesys via Mindful Datastore
• Transferring callers to a Mindful Feedback survey before disconnecting

Overview

This guide covers the following steps to set up your Genesys Cloud integration with Mindful:

• Mindful 
  • Configure a Call Target
  • Provision a phone number for the Call Target
  • Configure a Scheduler Widget
  • Configure a Data Set Template
• Genesys Cloud
  • Create a BYOC PBX SIP trunk to Mindful Callback
  • Modify Number Plans and Outbound Routes for calls out to Mindful Callback
  • Create an Integration and Action to fetch the EWT from the Inbound Architect Flow:
    • Create an Oauth client
    • Create a Genesys Data Actions Integration
    • Verify the Get Estimated Wait Time Action
  • Create an Integration and Actions for Mindful API calls:
    • Create a Web Services Data Action Integration
    • Create a Mindful Retrieve Widget Status Action
    • (Optional) Create Mindful Datastore POST Action
    • (Optional) Create Mindful Datastore GET Action
  • Modify the Inbound call flow in Architect to use Mindful Callback integration logic:
    • Check the EWT
    • Check Mindful Callback status
    • Play an EWT Announcement
    • (Optional) Post data to Mindful Datastore
    • Transfer callers to Mindful Callback
  • Create Choose-Hold flow:
    • (Optional) Retrieve data from Mindful Datastore
    • Send calls to queue at normal Inbound Priority
  • (Optional) Create / Modify In-Queue flow in Architect for Second Chance Callback:
    1. Loop the flow to play queue treatment (music/announcements) every x minutes
    2. After treatment, offer callers a callback instead of continuing to wait
    3. If a caller accepts, transfer the call to Mindful Callback (Call Target for Second Chance Callback)
  • Create a callback flow:
    • (Optional) Retrieve data from Mindful Datastore
    • Send calls to queue at higher priority
• Mindful Feedback
  • (Optional) Transfer customers to a survey after speaking with an agent

Components and call flows

Before looking at configuration, 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.

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

1. Callback Telephony Type: Select SIP.
2. 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

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.

Create a BYOC PBX SIP Trunk for Mindful

Next, we will move out of the Mindful ecosystem and configure the Genesys Cloud environment. We will come back to the Mindful world near the end of this guide to configure the ability to transfer customers to a Mindful Feedback survey.

A typical Genesys Cloud organization may contain configuration of one or more carrier trunks, but to send calls to Mindful Callback, and to route both customer and agent legs of a callback, you will need a new External SIP Trunk.

Use the following steps to configure the new BYOC PBX Trunk.

Quick access: Admin > Telephony > Trunks > External Trunks tab

1. On the External Trunks tab, click Create New.
2. Enter a name for the trunk.
3. Select BYOC PBX > Generic BYOC PBX in the Type dropdown menu. Additional settings will appear on the page.

4. Configure the trunk settings as shown:
   • Trunk State: Make sure this is set to In Service (it should be by default).
   • Protocol: Make sure UDP is selected (it should be by default).
   • Inbound SIP Termination Identifier: Enter a name to be used as an identifier in the SIP domain for inbound requests. This can be any name you would like.

At this point, you should see the Inbound Request-URI Reference box populated with an example URI. Write down the value of the FQDN Method for later use when configuring Mindful Callback (Call Center Number field).

SIP Servers or Proxies: Add the Mindful Callback SIP proxy address (FQDN) and port. Contact the Mindful Solution Delivery team for assistance in obtaining the proxy address. SIP Access Control: Enter the Mindful Callback SIP proxy IP addresses. Contact the Mindful Solution Delivery team for assistance in obtaining the proxy IPs. Note that you do not need to add the RTP proxy IPs here; only SIP. PBX Passthrough: Set the switch to Enabled. The PBX Passthrough setting is the primary reason for configuring the trunk as BYOC PBX and not BYOC Carrier. This setting allows the customer leg of a callback returned from Mindful to come into Genesys Cloud to be forwarded to the customer. When Mindful routes the customer leg of a callback to Genesys, the customer phone number will not match any DID within the Genesys Cloud organization. Thus, the call will be sent out the carrier trunk by matching the customer’s number to the Number Plan in Genesys Cloud.

• External Trunk Configuration > Identity: Disable the Address Omit + Prefix setting in the Called section. If you are using PSTN instead of the the standard SIP integration detailed in this guide, you will need to leave this setting enabled (SIP = disabled, PSTN = enabled).
• External Trunk Configuration > Media: Set audio/PCMU as the top item in the Preferred Codec List. This is needed since Mindful Callback uses the G711 ulaw codec for media.

External Trunk Configuration > Protocol:  Enable the Take Back and Transfer setting. This allows Mindful to transfer callers who choose to hold back to the Genesys environment during an inbound interaction. Add a custom SIP header named X-Mindful-Routing-Token, with a value provided by the Mindful team. This will result in Genesys Cloud passing the header in any INVITE requests to Mindful Callback, which is required by the Mindful SIP Router.

5. Save your changes when finished.

Modify the Site configuration (Number Plan and Outbound Route)

You will need a Number Plan and Outbound Route to utilize the SIP trunk created earlier. Together, the Number Plan and Outbound Route will ensure that calls exit through the trunk created earlier on their way out to Mindful.

New Number Plan

The Number Plan will simply define a range of numbers to be identified and used in later steps. Use the following steps to configure a new Number Plan.

Quick access: Admin > Telephony > Sites > Your Site

1. Select the Number Plans tab and click New Number Plan.

2. Configure the Number Plan as seen in the screenshot above:
   • Number Plan Name: Enter your desired name (such as To-Mindful-Callback).
   • Match Type: Select Number List, then enter the range of SIP numbers provided by the Mindful Solution Delivery team. You should have one number for each Mindful Call Target. In our example integration, we have entered a range of 285140002 to 285140009.
   • Classification: Enter a new value here (for example, MindfulCallback) to be referenced in the Outbound Route.
3. Move the new Number Plan to the top of the list (but still lower than Emergency) to ensure that Mindful calls exit through the correct trunk.
4. Save your changes when finished.

New Outbound Route

The Outbound Route will allow calls to be sent out the Mindful Callback Trunk. Use the following steps to configure a new Outbound Route.

Quick access: Admin > Telephony > Sites > Your Site

1. Select the Outbound Routes tab and click New Outbound Route.

2. Configure the Outbound Route as shown in the screenshot above:
   • Name: Provide a descriptive name for the Outbound Route (such as Mindful Callback).
   • State: Set to Enabled.
   • Classifications: Select the classification you created for the Number Plan earlier.
   • External Trunks: Select the new Mindful Callback Trunk created earlier.
3. Save your changes when finished.

Test the configuration 

Before moving on, you can test the configuration up to this point while still on the Sites page:

1. Select the Simulate Call tab.
2. Enter a SIP number from the range of numbers provided by the Mindful Solution Delivery team.
3. Click Simulate Call.

The results should show the number using the new Number Plan, classification, Outbound Route and External Trunk created in this section. 

Create Integrations & Actions in Genesys Cloud

In Genesys Cloud, you will need two Integrations, which you can think of as containers to hold Actions. The Actions within the Integrations will allow you to interact with data from the Mindful and Genesys environments in several ways:

• by checking the EWT in Genesys Cloud
• by checking the status of a Call Target in Mindful (via a Digital Callback widget)
• by posting and retrieving user data from Mindful Datastore

This section will describe the process of setting up an Integration for Genesys-related Actions and another Integration for Mindful-related Actions. This section also describes the two required Actions and two optional Actions to be saved within the Integrations.

See below for more details on the Actions:

• Get EWT queries the Genesys public API using OAuth credentials to retrieve the Estimated Wait Time for the specified queue.
• Get Call Target Status (GetWidgetStatus) sends a Retrieve Widget Status API request (HTTPS GET) to the Mindful Callback widget associated with a Call Target. This Action will be used in the inbound Architect Flow to validate that both Mindful Callback and the Call Target are in a state in which they can receive calls.
• Post to Datastore is invoked by the inbound Architect Flow to send user data to Mindful Datastore via HTTPS POST.
• Retrieve from Datastore is used by the Choose Hold and Callback Architect Flows to retrieve the user data from Mindful Datastore via HTTPS GET.

Integration and Action for Genesys Cloud

The inbound Architect Flow will check the Estimated Wait Time to ensure that calls are only sent to Mindful if the wait time reaches a minimum threshold. This also allows the flow to play back an EWT phrase to the caller to allow them to make an informed choice. For this, the inbound Flow will need to invoke an Action within an Integration, so you will need to configure those first.

1) Create an OAuth Client for the Genesys Cloud Integration

For an Integration and the Actions within it to use the Genesys Cloud APIs, the Integration must have the necessary permissions. To grant those permissions, you must first create an OAuth client.

Quick access: Admin > Integrations > OAuth

On the OAuth page, click Add Client.

On the Client Details tab, enter an App Name.

Select Client Credentials in the Grant Types section. The Roles tab will appear after selecting this option.

Open the Roles tab, then assign a role that provides the permissions that will be required by the Integration/Action for Genesys Cloud. The Routing > Queue > View permission is required to query the Estimated Wait Time, and this permission is only granted to the Master Admin role by default. 

You can apply the Master Admin role to the OAuth client or add the required permission to another role you wish to use.

2) Create the Integration for Genesys Cloud

Remember that this Integration will serve as a container to hold the Action that will retrieve EWT from Genesys Cloud.

Quick access: Admin > Integrations

1. On the Integrations page, click the + Integrations button near the top right of the page.
2. Find the tile named Genesys Cloud Data Actions, then click Install in that tile. After installation, you should see the configuration page shown below:

3. On the Details tab, enter a name for the Integration in the Name field.
4. On the Configuration tab, select Credentials and then make sure the OAuth client you created previously is selected.

5. Save your changes and set the Integration to Active when finished.

3) Verify the Get Estimated Wait Time Action exists

When a new Genesys Cloud Data Action Integration is created, default Data Actions are created for that Integration automatically. One of the default Actions is Get Estimated Wait Time, which will be used in the inbound Architect Flow. 

To verify this Action is present in the new Integration, open the Actions page and look for Get Estimated Wait Time. Click the name of the Action to open it:

There should be no need to change anything in this Action. Once published, it will be ready for use by the inbound Flow. 

Mindful Integration & Actions

The Mindful platform provides a set of APIs that can be used to interact with Mindful services. The Genesys Cloud integration calls an API method for a Digital Callback widget to ensure that the Call Target connected to it is available to register callbacks. The integration also uses API methods to post and retrieve user data to and from Mindful Datastore.

This section describes those API requests and how to configure them as Actions in Genesys Cloud.

1) Create the Mindful Integration

Just as you did for Genesys Cloud Actions, you will first need to create an Integration to hold Actions related to Mindful.

Quick access: Admin > Integrations

1. On the Integrations page, click the + Integrations button near the top right of the page.
2. Find the tile named Web Services Data Actions, then click Install in that tile. After installation, you should see the configuration page shown below:

3. On the Details tab, enter a name for the Integration in the Name field.
4. Save your changes and set the Integration to Active when finished.

2) Create the Retrieve Widget Status Action

Before transferring a call from Genesys Cloud to Mindful Callback, you should verify that Mindful Callback is available and that the Call Target is in a state that allows callbacks. To do that, you will need to configure an Action to perform a Retrieve Widget Status request to the Digital Callback API.

Quick access: Admin > Integrations > Actions

1. Click Add Action to get started 
2. Select the Integration for Mindful created in the previous step.
3. Enter a name (such as GetWidgetState) in the Action Name field.
4. Click Add to create the new Action.
5. In the Setup tab for the Action, open the Input Contract.

6. Enter a name for the schema, then click the plus (+) icon on the schema object to add a new item in that schema. 
7. Name the new item widget_url and set the type to String. This item will allow you to specify a URL to send the API request via an input field in the Call Data Action block in the inbound Architect Flow later. 
8. Open Output Contract next.

9. Enter a name for the schema, then add a new item within. 
10. Name the new item widget_state and set the type to String. This item will contain the one property in the API response that will be relevant in the inbound Flow.
11. Open the Configuration tab in the sidebar (still under the Setup tab).

12. Configure the Request section as follows: 
    • Set the Request type to GET. 
    • Click within the Request URL Template field, then click the widget_url (string) variable from the Available Inputs list on the right side of the page. You should see the variable ${input.widget_url} populated in the Request URL Template field. This means that the URL used for this request will be the widget_url input string provided by the Architect flow.

Test the Action

13. To test the new Action after configuring it, open the Test tab.

14. Enter a complete widget URL in the Input section. You can obtain a URL from the Mindful Callback UI at Digital > Widgets > API Endpoints > Retrieve Widget Status > URL.
15. Click Run Action. If successful, a green box will appear in the Output section with the returned value of widget_state. The widget_state variable should either return offer_callback or offer_asap_callback.

Save and publish the Action when finished.

3) Create the Datastore Post Action

The Datastore Post Action will define the fields that are populated from the inbound Flow. These include mandatory fields used for the HTTPS POST (the Mindful Datastore URL and Dataset Template API Token). You can include additional fields to pass custom data from the initial inbound call to the return call (account number, original call ID, etc.) as well.

After defining the necessary fields, the Action will send a POST to the Datastore API to store user data for each call.

Follow the instructions below to Create the Datastore Post Action.

Quick access: Admin > Integrations > Actions

1. Click Add Action to begin.
2. In the modal window that appears, enter a name for the Action (such as Datastore POST). 
3. Select the Integration for Mindful created earlier.

4. Click Add to create the new Action.
5. In the Setup tab for the Action, open the Input Contract.
6. Create an object (named PostData in the example) and add the necessary data fields within it. These fields will appear in the Architect Flow to pass values into the Action.  

The example below shows the three mandatory fields DS_URL, DS_Auth, and DS_ContactNumber. The example also includes several custom data fields, each of which match a field in the Data Set Template in Mindful Datastore.

7. Next, open the Configuration tab in the sidebar (still in the Setup tab).

8. Configure this tab as seen in the example:
   • Request type: Select POST.
   • Request URL Template: Enter the name of the datastore URL field configured on the Contracts page (in the format ${input.<fieldname>}). In our example, we use ${input.DS_URL}.
   • Add two entries in the Headers section:
     • Authorization: Enter the name of the datastore Authorization field configured on the Contracts page (in the format ${input.<fieldname>}). In our example, we use ${input.DS_Auth}.
     • Content-type: Enter application/json.
   • Request Body Template: Enter a JSON object containing the variables that will be mapped to the required fields in the Data Set Template.

{"customer_contact_number":"${input.DS_ContactNumber}","data_values":{"FirstName":"${input.DS_FirstName}","LastName":"${input.DS_LastName}","AccNum":"${input.DS_AccNUm}","Callid":"${input.DS_Callid}"}}

9. To test the new Action after configuring it, open the Test tab.
10. Enter test values for each field, then click Run Action. You should receive a 200 response if the POST was successful.
11. If you receive a successful response, look up the data in the Mindful Datastore UI by using the customer contact number as the search key. If all of your test data is present, the Action is working as expected.

Save and publish the Action when finished.

4) Create the Datastore Get Action

The Datastore Get Action will retrieve data in the callback-return or choose-hold Flows that was posted for an interaction in the inbound Flow.

This Action defines the fields to expect in the response from Mindful Datastore. These fields include the required parameters (Datastore URL and Auth Token), as well as any custom fields included in your Data Set Template.

Use the following steps to configure the Get Action:

Quick access: Admin > Integrations > Actions

1. Click Add Action to begin.
2. In the modal window that appears, enter a name for the Action (such as Datastore Get). 
3. Select the Integration for Mindful created earlier.
4. Click Add to create the new Action.
5. In the Setup tab for the Action, open the Input Contract.
6. Create an object and add the necessary data fields (DS_URL and DS_Auth) within it. These fields will appear in the Architect Flow to pass values into the Action.  
7. Next, open the Output Contract.
8. Add all of the fields configured in your Data Set Template in Datastore, exactly as they are defined.
9. Once added, click Configuration on the left to open the Action configuration page.

Configure the Action as shown:

• Request type: Select GET.
• Request URL Template: Enter the name of the datastore URL variable configured in the previous Contracts page. This should be in the format ${input.<fieldname>}.
• Add one entry in the Headers section:
  • Authorization: Enter the name of the datastore Authorization field configured on the Contracts page (in the format ${input.<fieldname>}). In our example, we use ${input.DS_Auth}.

Unlike the POST action, no body text is required for the Get Action.

Again this can be tested using the Test page, entering some test data into the fields that match a data set previously posted to Mindful Datastore. Once satisfied with the configuration, save and publish the Action.

Modify the inbound Architect Flow

The inbound Architect Flow for Mindful Callback is typically a modification to the existing Flow used to process inbound calls.   In the existing inbound Flow, you will need to add several steps to:

• 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 the callback option.
• Play the EWT phrase to provide callers with an expectation to help them make their decision.
• Verify that Mindful Callback is available and ready to process callback requests.
• (Optional) Post data to Mindful Datastore.
• Transfer the call to Mindful Callback

Quick access: Admin > Architect

Open your existing Inbound Architect Flow. If you are starting a new Flow, first select Inbound Call on the Flows tab, then click Add. Add the blocks listed below and follow the steps to configure the inbound Flow.

1) Find Queue

The Find Queue block populates a special Queue-type variable containing the queue name and queue ID. The queue name and ID will be used later in the Flow to retrieve the Estimated Wait Time. The variable will also be used to send calls to the agent queue when needed.

Configure the Find Queue block as shown:

• Queue Name: Enter the name of the agent queue to be used for this Flow, and select the Literal mode to the right of the input field. Alternatively, you could use a variable here and use the Expression mode.
• Queue Result: Enter the variable Task.QueueName.

2) Update User Data

Add an Update Data block to create variables to be used when posting user data to Mindful Datastore.

For each piece of user data that will be posted to Datastore, click Add update statement and select the String type.

The following three items are required:

• The URL of the Submit Data Request endpoint of the Mindful Datastore API: You can retrieve this in the Datastore UI at Data Set Templates > Data Set API (plug icon), as seen in the example below.
• The Datastore API token: Copy the API token (including the word "Bearer") from the same API example page, as seen below. You can also copy the API token from the Data Set Template page and add the word "Bearer" yourself.

• The caller's ANI (ContactNumber): Use an expression to make sure the ANI is formatted correctly when using it as a key in Mindful Datastore. The example shows the right-most 11 digits of the system variable Call.Ani assigned to the ContactNumber variable with the expression Right(Call.Ani, 11). This format can vary according to your regional numbering system.

You can use this Update Data block to set values for any other data that should be passed to Datastore and passed back on the return call (Queue ID, Interaction ID, agent name, etc.).  

3) Call Data Action (Get Estimated Wait Time)

Next, use a Call Data Action block to invoke the Get Estimated Wait Time Action created earlier.

Configure this block as shown in the example:

• Category: Select the Integration for Genesys Cloud that you created in a previous step.
• Data Action: Select the Get Estimated Wait Time Action.
• Inputs > Queue_ID: Refer to the queue name variable configured in the initial FindQueue block by using the format Task.<QueueName>.id, as seen below. This will pass the queue id (which is required for the EWT query rather than the queue name) to the Data Action.  

• Inputs > MEDIA_TYPE: Enter a literal value of call.
• Success Outputs > Estimate Wait Time in Seconds: Enter the variable Task.EWT.

4) Switch (check EWT value)

The next block (Switch) will check the EWT value obtained in the previous block. It will then route the call down different paths based on the value of the EWT.

You can configure the cases however you would like. In our example, we use three cases:

• Case 1: The value of the EWT variable (divided by 60 for minutes) is less than 1 (so EWT is less than one minute).
• Case 2: The value of the EWT variable is greater than 120 (so EWT is greater than two hours).
• Default Case: Neither Case 1 nor Case 2 are true (EWT is between one minute and two hours).

For Case 1 and Case 2, add Play Audio blocks to inform callers that the wait time is less than one minute (for Case 1) or more than two hours (for Case 2):

To ensure that the EWT is spoken in hours and minutes, use the built-in MakeDuration and ToDuration functions as seen in the example below. To apply the function, click the Play button in the Audio field, then click Add Expression. 

You can copy the code directly from here, if needed:

ToDuration(MakeDuration(0, 0,ToInt(Task.EWT / 60),0))

If the call follows the paths for Case 2 or the Default Case, it proceeds to the next block to continue with Mindful logic. For Case 1, the call is transferred to an agent queue to wait on hold.

5) Call Data Action (Get Widget State)

The prior Call Data Action block was used to check the EWT in the Genesys environment. This second Call Data Action block will be used to verify that the Mindful environment is ready to register new callbacks.

Use the example above as a guide to configure this block:

• Category: Select the Integration for Mindful created earlier.
• Data Action: Select the GetWidgetState Action.
• Inputs > widget_url: Enter the URL of the Retrieve Widget Status API endpoint from the Mindful UI (Digital > Widgets > API Endpoints > Retrieve Widget Status section). You can find the URL in the URL field: 

• Success Outputs: Enter an expression referencing the widget_state variable in the format Task.widget_state.

6) Decision (evaluate widget_state)

Add a Decision block to evaluate the widget_state variable and determine the next step of the Flow. If Mindful is ready to register callbacks (meaning widget_state returned offer_callback or offer_asap_callback), the next step will continue with Mindful logic. If not, the call should queue to agents.

Add the following line into the Expression field:

Task.widget_state == “offer_callback” OR Task.widget_state == “offer_asap_callback”

7) (Optional) Call Data Action (Datastore Post)

After preparing user data in a previous step, you will need a third and final Call Data Action block to post user data to Mindful Datastore.

Configure this block as seen in the example. 

• Category: Select the Integration for Mindful created earlier.
• Data Action: Select the Datastore POST Action.
• Inputs: Add entries for all items configured in your Data Set Template in Mindful Datastore. Remember that only DS_URL, DS_Auth, and DS_ContactNumber are required. All other fields shown here are examples. For each input, provide an existing variable or literal value.

8) Transfer to Number (to Mindful)

Add a Transfer to Number block to send calls to the SIP number associated with the relevant Mindful Call Target. This number should match the number range in the Number Plan configured previously.

This is the final block for a successful route through the Flow to Mindful. The final block to configure will catch instances in which a call needs to be routed directly to an agent queue rather than being sent to Mindful.

9) Transfer to ACD block (at normal priority)

Two blocks should contain exits leading to a Transfer to ACD block:

• The Case 1 path from the Switch block (meaning the EWT is under one minute)
• The No path from the Decision block (meaning Mindful is not available)

In both of these cases, calls should be transferred to agents rather than Mindful Callback. Note in the example below that the priority should be set at a low value to ensure that returned callbacks have higher priority.

Configure the choose-hold return call Flow

This Architect Flow is used if the caller declines the callback offer after being sent to Mindful Callback. In this case, Mindful sends a SIP REFER to Genesys Cloud, and the numeric portion of the SIP URI configured in the Choose Hold Phone Number field in the Mindful UI is passed in the SIP refer-to header. 

Configure a DID entry (typically a virtual number) in Genesys Cloud to match the Choose Hold Phone Number.

Assign the DID entry to a Call Route:

 Finally, assign the Call Route to the Choose Hold Architect Flow:

Example Choose Hold Flow

The example Choose Hold Architect Flow contains three primary steps, shown below. You could add more steps based on your requirements, but these three must be included if you utilize Mindful Datastore.

1) (Optional) Update Data (set Datastore variables)

This block is used to retrieve any user data that was posted to Datastore in the inbound Flow, using the customer ANI as the search key.

Add two Update Statements:

• Update Statement 1
  • Variable Name 1: Enter the variable corresponding to the Datastore URL (Task.DS_URL in our example).
  • Value To Assign 1: Select the Literal type and enter the following expression. This is used as the full HTTPS GET URL in the Datastore GET Action. Notice that the expression uses the Call.Ani variable to append the caller's ANI onto the URL with the expected number of digits.

Append("https://datastore.mindfulcx.com/api/v1/data_sets/search?customer_contact_number=",ToString(Right(Call.Ani, 11)))

• Update Statement 2
  • Variable Name 2: Enter the variable corresponding to the Datastore API Token (Task.DS_Auth in our example). 
  • Value to Assign 2: Enter the API token (including the word "Bearer") of your Data Set Template from the API example page (Data Set Templates > Data Set API (plug icon)), just as you did for the inbound Architect Flow. You can also copy the API token from the Data Set Template page and add the word "Bearer" yourself.

2) (Optional) Call Data Action (Datastore Get)

This Call Data Action block retrieves the data passed to Datastore during the initial inbound call. It then assigns the returned data back to variables that can be used for call routing decisions, agent screen-pop, or other uses.

Consult the example above when configuring this block:

• Category: Select the Integration for Mindful created earlier.
• Action: Select the Datastore GET Action.
• Inputs > DS_URL: Enter an expression containing the variable used to store the Datastore URL in the first block (Task.DS_URL).
• Inputs > DS_Auth: Enter an expression containing the variable used for the Datastore API Token (DS_Auth).

Configure additional inputs as needed, based on the data expected by your Data Set Template.

3) Transfer to ACD (send to agent queue)

This block sends the call to queue at the normal inbound queueing priority. Note that this should not be the highest priority (highest priority is 5 full stars = priority 10) so that callbacks can queue at a higher priority.

Example Callback Architect Flow

The sample Callback Flow is almost identical to the Choose Hold flow, except for the priority of the Send to ACD block. 

Like the Choose Hold flow, a virtual DID number should be configured in Genesys Cloud and assigned to a Call Route that routes to the Callback Flow. The virtual number should then be configured in the Call Center Phone Number field in the Mindful Call Target configuration.

To configure this Flow, follow the same steps listed in this guide for the Choose Hold Flow, but increase the priority in the Transfer to ACD block to a level higher than normal inbound calls. This does not have to be the highest priority (five stars). It only needs to be higher than the priority of inbound calls to the same agent queue.

With this final Flow in place, your Mindful Callback integration should be complete, and you should be ready for end-to-end testing! Continue to the next section to learn more about integrating with Mindful Feedback to gather survey input from your customers.

Integrate with Mindful Feedback for surveys

The Mindful Feedback integration with Genesys Cloud includes several ways to deliver surveys to customers, including via SIP call transfers by agents and automatic embedding into Genesys Cloud web chat windows. In this guide, we will focus solely on creating a button in an agent script to allow agents to transfer customers to a voice survey after an interaction. For more information on other integration points, see the Mindful Feedback documentation.

In addition to the items listed above, you will need to create:

• A Secure Call Flow in Genesys Architect to set UUI data and transfer calls to Mindful Feedback
• An Agent Script to provide a button for agents to transfer calls to the Secure Call Flow

Use the steps in this article to complete the required configuration.

1. Acquire a SIP Survey Token

To configure the Secure Call Flow, you will need the SIP Survey Token for the survey you wish to play after transferring a call to Mindful Feedback. You can find this token in the Mindful Feedback user interface at Surveys > Your survey > Advanced tab:

2. Configure a Secure Call Flow

Create a new Secure Call Flow to accomplish two tasks:

1. Set UUI data on the call before transferring (blind) to Mindful Feedback.
2. Transfer the call to Mindful Feedback with the UUI data attached.

Use the following steps to create the Secure Call Flow.

Set UUI Data block

In Genesys Cloud Architect, add a new Secure Call Flow.

Within the new call flow, add a Set UUI Data for Transfer block and configure it with an expression in the following format:

"SDX-survey_sip_token:<sipsurveytoken>;SDX-external_ref:" + Call.ConversationId + ";SDX-respondent_language:en-US"

UUI parameters

Mindful Feedback expects the UUI Data string to contain attributes with a prefix of SDX-, which it will parse when the call arrives. The required and optional attributes are explained in the following table:

EXAMPLE

The following example shows a complete expression with SDX-survey_sip_token, SDX-external_ref, and SDX-respondent_language parameters:

NOTE

If you want to play a different survey for a different queue, you can set the SIP Survey Token in the call flow to a variable and append the value to the UUI Data string. You can see this method being used with the Call.ConversationId variable in the example UUI expression in this article.

The same process would apply for setting the required language or other attributes.

Transfer to Number block

After the Set UUI Data block, add a Transfer to Number block to transfer the caller to the SDX SIP endpoint via the configured number. The example call-flow screenshot above shows 10000 as the SIP endpoint.

3. Configure an agent script

Create a new agent script, or edit an existing script, to enable agents to transfer callers to the survey by clicking a button. In the script, add a button and set the button's action to Invoke Secure Flow with the following configuration:

• Secure Flow: Select the call flow configured in the earlier steps.
• Flow Data Field: You can select any field here. It is required but not used.
• Button > Text: Add a descriptive label for the button, such as "Transfer to Survey" or "End Call".

Enable the button for inbound or outbound calls as needed, then add it as a Screen Pop block in the appropriate Architect Flow just before transferring to an agent.

That's it for the SIP transfer from Genesys Cloud to Mindful! Your agents should now be able to click a button to transfer customers to SDX for survey treatment when a conversation ends.

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

1. 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. 
2. When the time comes, Callback delivers the return call (a callback in this case) with the destination number still attached.
3. 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. 
4. The appropriate priority is set, and the call is delivered to an agent.

(Optional) Offer Second Chance Callback

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