Components and architecture

Review the definitions of acronyms and terms used throughout this guide before getting started. You can also view a high-level overview of the components and architecture of the integration below.

Mindful configuration

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)

Registration

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

Voice > Call Targets > Your Call Target > General tab > Contact Center

• Callback Telephony Type — Select "PSTN".

  Note: For government users — Only SIP is available in the Government instance.

• Callback Number — This will be configured in a later step.

Callback Strategy

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. This can be done via the Agent Answer API, as well. The Agent Answer events assist in calculating an accurate Estimated Callback Time (ECBT).

Phone Numbers

Configuration > Phone Numbers

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

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 steps in this section.

A Data Set Template contains a collection of Data Keys that allows 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 returned 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.

1. On the Data Set Templates page (Datastore > Data Set Templates), click Add Data Set Template.

   

   This takes you to the New Data Set Template page.

   

2. Configure Template Data Keys for the new template.

   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.

   • 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 between 1 and 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

   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.

Lambda functions and permissions

You will need several Lambda functions in Amazon Connect to invoke Mindful APIs and convert the EWT to a playable phrase.

In order to leverage AWS Lambda functionality in your Amazon Connect instance, you must first set the appropriate permissions in your Connect account.

Use the steps below to set the necessary permissions.

• Open the Contact Flows submenu (AWS Console > Your Connect instance > Contact flows).

  

• Use the Function dropdown menu to select the "Call-VHT-Datastore-API" and "connect-time-convert-phrase" functions, or click Add Lambda Function to create them now.

  

connect-agent-answer-node Lambda function

Create a Lambda function in your preferred AWS lambda runtime environment to invoke the Agent Answer API. This API sends an acknowledgement to Mindful that an agent has answered a callback, allowing Mindful to more accurately calculate performance metrics.

In our example, we named the function connect-agent-answer-node. Following is an example script that retrieves the required OAuth token and sends a request to the Invoke an Agent Answer API endpoint:

Deploy the function and create a new test configuration to assign values to the required variables. The test data may look similar to the following:

Note:

For testing, you will need to temporarily change the value being set for dataset.data.ani to use Temp_Tel. A successful result should look like the one below. The 404 error is expected, since there will not be a call in Mindful at the time:

18T15:15:46.530Z 4de90c15-4b17-4501-9c97-09aff837377b INFO {"errors":[{"code":"404","detail":"Request failed with status code 404"}]}

Whisper Flow

You will need a Whisper Flow to invoke the connect-agent-answer-node Lambda function as part of the callback-return Contact Flow. Follow the steps below to configure the new Whisper Flow.

1. In Amazon Connect, open the Flows page from the sidebar menu.

2. In the Flows tab, open the Create Flow menu and select "Create customer whisper flow".

   

3. Configure the Whisper Flow with three blocks:

   

   • Start with an entry point.

   • Next, add an Invoke AWS Lambda Function block configured as shown below:

     

     • Function ARN — Select "Set manually", then enter the name of the Agent Answer Lambda function created earlier.

     • Function input parameters — Enter the following function input parameters:

       • Token_URL — Enter the URL of the Mindful API's OAuth authentication endpoint.

       • Client_ID — Enter the Client ID of a Mindful Application Client.

       • Secret_Num — Enter the Client Secret of a Mindful Application Client.

       • API_URL — Enter the URL of the Invoke a Call Answer API endpoint.

       • (Optional) Queue_ID — Assign a value representing the queue in which the call was handled.

       • (Optional) Agent_ID — Assign a value representing the agent who handled the call.

   • Finish with an End Flow / Resume block

Contact Flows

Contact Flows contain routing logic and other operations to manage calls entering and leaving the Amazon Connect platform. In our example configuration we used three separate Contact Flows:

• One for normal inbound calls

• One for inbound calls intended for Mindful

• One for callbacks coming from Mindful into Amazon Connect

Normal inbound calls

The first Contact Flow handles inbound calls. This flow can either pass calls onward to receive Amazon Connect's native callback treatment or send calls to Mindful for a callback offer. The following image shows how this flow is configured in our example integration:

1. Set Voice — Sets the voice to be used

2. Get queue metrics — Obtains the queue from which metrics will be pulled for the life of the call

3. Set contact attributes — Stores the customer's phone number to the ANI variable

4. Get customer input — Simulates a main menu with conditional branching

5. Get customer input > Pressed 1 — Sends the call to a Transfer to Flow block that passes the call to a Contact Flow offering Amazon Connect's native callback feature

6. Get customer input > Pressed 2 — Sends the call to a Transfer to Flow block that sends the call to the Contact Flow leading to Mindful

Inbound calls intended for Mindful

The second Contact Flow provides options to send KVPs to Mindful Datastore while sending calls to the Mindful, or to simply send calls to a holding queue.

When Amazon Connect receives a callback via the PSTN later, it can use the customer phone number to retrieve the KVPs from Mindful Datastore and re-attach the data to the call.

1. Set Voice — Sets the voice to be used

2. Get queue metrics — Obtains the queue from which metrics will be pulled for the life of the call

3. Invoke AWS Lambda function — Invokes the connect-time-convert-phrase function.

   1. The connect-time-convert-phrase function parses the OCW variable ("OCW":"<Integer>") into a phrase that can be spoken via the TTS engine.

   2. It then passes the full KVP back with the full phrase set as the value. For example, "OCW":"Less than one minute".

      

   Note:

   All KVPs returned from a Lambda function are stored as External Variables and can be referenced as $External.variable_name. The following example shows a TTS string invoking the OCW variable with $.External.OCW:

   You have reached the billing department. The current hold time is $.External.OCW. To receive a callback, press 1. To remain on hold, press 2.

   
4. Get customer input — Announces the wait time by calling the OCW variable, then presents customers with the choice to request a callback or wait on hold.

   • Pressed 1 — Invokes the Call-VHT-Datastore-API Lambda function to pass all KVPs to Mindful Datastore. The function will either send a POST request to push data to Mindful Datastore or a GET request to retrieve data. The method used depends on the parameters passed to the Lambda function.

   • Pressed 2 — Transfers the call to a holding queue

   Example

   The following example shows a complete KVP list provided to the Call-Mindful-Datastore-API Lambda function. The value of the method variable indicates that this example will use the POST method to send data to Mindful Datastore.

   "contact_id": "(System attribute - Contact id)", "customer_contact_number": "(System attribute - Customer callback number)", "last_name": "John", "first_name": "Smith", "queue_name": "(Queue Metrics - Queue ARN)", "token": "sadjf;l+eyg=", "method": "POST"

   Note that the contact_id and customer_contact_number variables are provided by the native API call from Amazon Connect to Lambda. However, you can define them on your own if you do not wish to use the values provided.

   Important:

   If Mindful uses Twilio trunks to receive inbound calls (default configuration), then the ANI of the call sent from the ACD environment to Mindful must be in e164 format. The ANI must be prefaced with +1. If a custom range of DNs is used instead, e164 format is not required.

5. Transfer to phone number — Sends the call to the Call Target phone number. Calls sent here will be able to register a callback with Mindful.

Callbacks coming from Mindful into Amazon Connect

This Contact Flow is used for callbacks sent from Mindful to Amazon Connect. The Call Target will send callbacks to the Call Center Phone Number configured in Mindful . That number should be provisioned in Amazon Connect and pointed at the callback-return Flow.

Below are the steps involved in this flow:

1. Change routing priority / age — Elevates the priority level of the call

2. Invoke AWS Lambda Function — Uses the Call-VHT-Datastore-API Lambda function to retrieve call data

3. Set working queue — Sets the working queue via the queue_name variable returned in the previous step

4. Set Whisper Flow — Sets the Whisper Flow created earlier for the connect-agent-answer-node Lambda function to provide an Answer event

   

5. Transfer to queue — Transfers the call to queue with its newly elevated priority and External Attributes

   Example

   The following example shows the KVP list configured in the Call-VHT-Datastore-API Lambda function and a response from Mindful Datastore:

   KVP list

   "customer_contact_number": "(System attribute - Customer callback number)", "token": "sadjfhasfhasfhasdfhsakjdfkljafkhkasdjf;l+eyg=", "method": "GET"

   Example Response

   { "customer_contact_number": "13209071234", "interaction_id": "68a7ff09-c2ca-49d7-9e66-63a2a92049ba", "ani": "13209071234", "contact_id": "68a7ff09-c2ca-49d7-9e66-63a2a92049ba", "last_name": "Smith", "first_name": "John", "queue_name": "arn:aws:connect:us-east-1:XXXXXXXXXX:instance/XXXXXX-bf14-4b7f-b4d9-XXXXXXXXXX/queue/XXXXXXXX-592b-4162-887c-XXXXXXXXXX", }
   Note:

   • Our example configuration allows a single DID provisioned in Amazon Connect to send calls to multiple different queues. In order for this to work, the customer phone number and the correct method (GET) must be passed to the Lambda function. These two items are necessary for the function to retrieve data associated with the call fromMindful Datastore.
   • The retrieved data can be used by other applications or for any purpose you would like. In our example configuration, we use the data to route calls appropriately with context.

Phone numbers

In our example configuration, we provisioned two phone numbers in Amazon Connect:

• One pointed at the BasicQueue - Inbound Contact Flow for calls coming into the Amazon Connect environment
• One pointed at the BasicQueue - VHT CBC Return Contact Flow flow for calls coming back to Amazon Connect from Mindful.

Optional enhancements

Several optional enhancements are available for the integration:

• Consolidate return-call destinations — Enhanced return-call routing when the same group of agents are spread out among multiple queuing destinations

• Offer second chance callbacks — Make additional callback offers in your holding queue after a customer has declined the initial offer.

For complete instructions on configuring these enhancements, see Optional enhancements.