OAuth-related Integrations

Two OAuth client Integrations are needed for different Actions — one for Genesys Cloud authentication and another for Mindful authentication.

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.

1. On the OAuth page (Admin > Integrations > OAuth), click Add Client.

   

2. On the Client Details tab, enter an App Name.

3. Select "Client Credentials" in the Grant Types section.

   

   The Roles tab will appear after selecting this option.

4. On the Roles tab, 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.

   

Create an OAuth Client for the Mindful API

You will need an OAuth integration to use Mindful APIs, such as Agent Answer and Get Offer.

1. On the Integrations page (Admin > Integrations > Integrations), click + Integrations.

2. Locate the Web Services Data Actions tile, then click Install.

   

3. On the configuration page that appears, enter a name on the Details tab, then open the Configuration tab.

4. In the Configuration tab, open the Credentials sub-tab, then click Configure.

   

5. Configure credentials as shown below:

   

   • Credential Type — Select "User Defined (OAuth)".

   • Credential Fields — Add the four fields listed below:

     • LoginUrl — Enter the Authentication endpoint for the Mindful API.

     • clientId — Enter a Client ID from a Mindful Application Client.

     • clientSecret — Enter a Client Secret from a Mindful Application Client.

     • scope — Enter mindful-api/callback.metric.read mindful-api/callback.status.read.

       The scope is needed for the Get Offer API endpoint only.

   Click OK when finished.

6. Back on the Integrations page, toggle the Active/Inactive switch to "Active".

Integration for Genesys Cloud

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

1. On the Integrations page (Admin > Integrations > Integrations), click + Integrations.

2. Locate the Genesys Cloud Data Actions tile, then click Install. 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, open the Credentials sub-tab and make sure the OAuth client you created previously is selected.

   

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

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.

Integration for Mindful

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

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.

Get Access Token Action

This Action will send a request to the Mindful OAuth credentials API endpoint to obtain a temporary (one hour) access token for subsequent API requests.

1. On the Integrations page, open the Actions tab.

2. Click Add Action.

3. When prompted, select the Integration created earlier for Mindful OAuth credentials, enter a name such as "Get Access Token", then click Add.

   

4. Open the Setup tab and add a string variable named "access_token" in the Output Contract section.

   

5. Open the Configuration sub-tab and verify that "Raw Request (string)" is shown under Available Inputs and "access_token (string)" is shown under Available Outputs.

   

6. Open the Test sub-tab, then click Run Action to send a test request.

   If a token is returned and assigned to the access_token variable, the test has succeeded.

   

7. Click Save & Publish when complete.

   On the Integrations page, the Action should now show "Published" in the Status column.

Get Offer Decision Action

Next, you'll need an Action to send a request to the Retrieve callback offer decision attributes API endpoint.

1. Click Add Action on the Actions tab of the Integrations page to begin.

2. In the Integration Name field, select the Integration used for other Mindful-related Actions, as described in the main Genesys Cloud integration guide.

3. Enter a name for the Action, then click Add.

4. Open the new Action, then open the Setup tab.

5. Add the following two strings to the Input Contract Schema:

   • CallTarget_URL

   • AuthToken

   

6. In the Output Contract, add the following nested Object as the Response:

   { "title": "OfferResponse", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "shouldOffer": { "type": "boolean" }, "isEndOfDay": { "type": "boolean" }, "afterHours": { "type": "boolean" }, "registrationEnabled": { "type": "boolean" }, "offeringAsap": { "type": "boolean" }, "offeringScheduleVoice": { "type": "boolean" }, "offeringScheduleWidget": { "type": "boolean" }, "offeringChooseHold": { "type": "boolean" }, "offeringTextIntercept": { "type": "boolean" }, "offeringNextDay": { "type": "boolean" }, "availableTimeslots": { "type": "boolean" }, "estimatedCallbackTime": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }

7. Verify that the Output Contract contains all of the properties included in the JSON object, as shown below:

   

8. Open the Configuration sub-tab, still within the Setup tab.

9. On the right side of the page, verify that the expected inputs are available:

   • Available Inputs:
     • CallTarget_URL (string)
     • AuthToken (string)
     • Raw Request (string)
   • Available Outputs:
     • data (object)
   

10. Open a new browser tab and run a new test of the Token Retrieval Action, then copy the token that is returned.

11. Back on the Get Offer Action, open the Test sub-tab and paste the new token into the AuthToken field.

12. Enter the Offer Decision endpoint URL in the CallTarget_URL field, including your Call Target ID.

    Note: To obtain your Call Target ID, see the documentation for the Retrieve all Call Targets endpoint. To obtain the Get Offer endpoint URL, see the documentation for the Retrieve callback offer decision attributes endpoint.

13. Execute the test after entering the required information.

    

14. Verify that the results contain all of the return values expected for the offer-decision API endpoint:

    

15. Click Save & Publish after a successful test.

16. Lastly, verify that the newly created Action shows "Published" in the Status column of the Actions tab.

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.

1. Open Admin > Integrations > Actions.

2. Click Add Action to begin.

3. In the modal window that appears, enter a name for the Action (such as Datastore POST).

4. Select the Integration for Mindful created earlier.

   

5. Click Add to create the new Action.

6. In the Setup tab for the Action, open the Input Contract.

7. 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.

   

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

   

9. 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.

     The structure of the Request Body Template string must be precise. You can copy a template of the required object for a particular Data Set Template in the Mindful Datastore UI at Data Set Templates > Data Set API, as seen below:

     

     Alternatively, you can copy the example object below and make changes as needed for your particular data set.

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

Test the Action

Follow the steps below to test the new Action:

1. Open the Test tab.

2. Enter test values for each field, then click Run Action. You should receive a 200 response if the POST was successful.

3. 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.

Troubleshooting

Below are common errors you may receive when testing the Datastore Post Action, along with potential remedies.

Agent Answer Action

This Action will invoke an answer event in Mindful, which provides a critical data point for calculating performance metrics.

Follow the steps below to configure this Action.

1. On the Integrations page, open the Actions tab.

2. Click Add Action.

3. When prompted, select the Integration created earlier for Mindful Data Actions (not the OAuth Integration), enter a name such as "Send Agent Answer", then click Add.

   

4. Open the Setup tab and add the following string variables as properties of the base object in the Input Contract section:

   

   • ani — Not Required

   • Authentication — Required

   • queueId — Not Required

   • agentId — Not Required

5. Open the Configuration sub-tab and configure the provided fields as shown below:

   

   • HTTP Method — Select "POST".

   • Request URL Template — Enter the Agent Answer API endpoint URL.

     See Mindful API v2 or contact the Mindful team for the URL.

   • Header — Add two headers:

     • Authorization = "$input.Authentication"

     • content-type = "application/json"

   • Request Body Template — Enter the following JSON template:

     { "data": { "ani": "${input.ani}", "metadata": { "queueId": "${input.queueId}", "agentId": "${input.agentId}" } } }

6. Obtain a new Mindful OAuth access token for testing.

7. Open the Test sub-tab of the Agent Answer Action.

8. Enter a valid E.164 phone number and the new access token in the fields provided, then click Run Test.
   Note: Since the phone number is not currently registered for a callback, you will receive a 404 error response, which indicates success at this point. A 404 response indicates that the API request was sent and a response received.

9. Click Save & Publish when finished.

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:

1. Open Admin > Integrations > Actions.

2. Click Add Action to begin.

3. In the modal window that appears, enter a name for the Action (such as Datastore Get).

4. Select the Integration for Mindful created earlier.

5. Click Add to create the new Action.

6. In the Setup tab for the Action, open the Input Contract.

7. 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.

8. Next, open the Output Contract.

9. Add all of the fields configured in your Data Set Template in Datastore, exactly as they are defined.

10. Once added, click Configuration on the left to open the Action configuration page.

    

11. 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.