Gathering Historic Data: Overview and Enabling Procedure


Document Version History


Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

2 August 2022

Active



























Document Purpose 

This document has been developed for admins of various organizations that use Shelf’s Answer Insights solution embedded into portals built on the Genesys Cloud and Kustomer platforms. This document’s goal is to answer the following questions:

  • What is Historic Data?

  • How is Historic Data used by Shelf?

  • How is Historic Data collected by Shelf?

  • What needs to be done to enable the Historic Data collection?

As part of answering the last question, the document also details the steps necessary to create an API key that will allow Shelf to gather historical transcript data from Genesys Cloud and Kustomer.



What is Historic Data?

Historic Data mentioned in this document is transcripts of the conversations conducted by and between agents and customers via Genesys Cloud or Kustomer platforms plus the associated metadata.


How is Historic Data used by Shelf?

A Company is deploying Shelf Answer Insights inside of Genesys Cloud or Kustomer to increase efficiency of its agents.  Shelf Answer Insights utilizes Artificial Intelligence to offer suggestions on appropriate content based on the context of the Agent’s Interaction. Historical transcripts and wrap-codes are used to train Shelf AI models before a deployment to increase the accuracy of the initial suggestions offered to agents. This is essential for improving the Shelf service quality and calibrating AI that will assist in all areas of knowledge automation for the clients.


How is Historic Data collected by Shelf?

Shelf’s engineers have built an automated service that is expected to pull transcripts from the Company’s Genesys Cloud or Kustomer instances. This service requires an API key from Genesys Cloud or Kustomer with the appropriate permission applied.  Details on how to use the API for gathering Historic Data from Genesys and from Kustomer can be found in the respective sections below.

Required Data

Shelf needs the API token to work with API’s, both the Genesys API and the Kustomer API. Depending on the platform you need to gather the Historic Data from, this API token can be obtained as a result of one of the following procedures.

Genesys Cloud for chat Scenario

Using the API

The script for gathering Historic Data from Genesys is expected to leverage the following Genesys APIs:
  1. API to get the list of conversations 
  2. API to get messages from the conversation by ID
  3. API to get the list of wrap-up codes


Required Permissions

The API key needs to be created with the correct set of permissions which are as follows:
  1. agentConversationDetail >  View
  2. conversationDetail >  View
  3. conversationAggregate  View
  4. Recording >  View
  5. RecordingSegment  View
  6. Queue >  View
  7. Routing > Wrap-up Code > View (link)
  8. Conversation > Communication > View

The final list of permissions for Genesys Cloud must look like this:

Figure 1. Viewing the list of permissions for API key


Useful Links

How to create an API key?: This link contains details on how you can create an OAuth client on Genesys Cloud.



Enabling the Historic Data Collection

  1. Open Genesys Cloud Admin Panel and search for Roles there.

    Figure 2. Searching for Roles/Permissions in Genesys Cloud Admin Panel

  2. Click the Roles / Permissionslink button and then hit the Add Role button as shown in the figure below.

    Figure 3. Starting the new role addition

  3. In the respective fields, enter some title and description for the new role you are adding.

    Figure 4. Adding the name and description for the role

  4. Once done, go to the Permissions tab and in its window, select the All Permissionscheckbox.

    Figure 5. Selecting the needed permission type

  5. Using the search bar in the Permissions tab window, find and add all permissions from the list below one by one:
            analytics  agentConversationDetail  View
            analytics  conversationDetail  View
            analytics conversationAggregate View
            recording  Recording  View
Example:

Figure 6. Adding the permission

Once all the needed permissions have been added, their final list must have the following look

Figure 7. Viewing the list of added permissions


6. Click the Savebutton at the bottom of the table.

Figure 8. Saving the added permissions

7. The next thing to be done is to find the needed role in the roles list and then add yourself to the respective role.  To do so, click the More Actions menu icon next to the needed role and then select the Change Membershipoption in the popup list that appears.

Figure 9. Adding your user to a role

8. Open the Genesys Cloud Admin Panel and using the search bar there, find the OAuthfeature.

Figure 10. Searching for the OAuth feature in Genesys

9. Once found, click it and then, hit the Add client button.
10. Add a name - Shelf Message Synchronization in our case - for the credentials you are creating, and indicate their specific type by selecting the Client Credentials checkbox in the Grant Typesblock.

Figure 11. Indicating the type of credentials being created

11. Select the Roles tab to open the respective window, and then assign the Shelf Message Synchronization Role. 

Figure 12. Assigning a role

12. Once done, click the Savebutton at the bottom of the window to save the changes made. 

Figure 13. Saving the created and assigned role in Genesys


Once all the above steps are complete, you are able to see all the data of the Oauth tokens, such as Client ID, Client secret and actual Genesys domain, e.g. mypurecloud.de / mypurecloud.com / etc., which are needed for the integration. 

Figure 14. Viewing data required for syncing the messages from Genesys Cloud

Also, finishing the above steps means that you have successfully enabled the historic data gathering for Genesys and can start using the integration for your business needs with no need to make any other configurations to data collection.


Genesys Cloud for voice Scenario

Final list of required items

  1. OAuth tokens to process the data. In general, you would want to have 1 per 2-3 queues that you want to process. 
  2. List of queue ID’s that you would like to gather information from


Enabled voice transcription for the selected queues

Refer to this guide if you did not previously enable it:

How to enable voice transcriptions?


Required Permissions for tokens

The API key needs to be created with the correct set of permissions which are as follows:
  1. agentConversationDetail >  View
  2. conversationDetail >  View
  3. conversationAggregate  View
  4. Recording >  View
  5. RecordingSegment  View
  6. Queue >  View
  7. Routing > Wrap-up Code > View (link)
  8. Conversation > Communication > View


Useful Links

How to create an API key?: This link contains details on how you can create an OAuth client on Genesys Cloud.

Enabling the Historic Data Collection

  1. Open Genesys Cloud Admin Panel and search for Roles there.

    Figure 2. Searching for Roles/Permissions in Genesys Cloud Admin Panel

  2. Click the Roles / Permissionslink button and then hit the Add Role button as shown in the figure below.

    Figure 3. Starting the new role addition

  3. In the respective fields, enter some title and description for the new role you are adding.

    Figure 4. Adding the name and description for the role

  4. Once done, go to the Permissions tab and in its window, select the All Permissionscheckbox.

    Figure 5. Selecting the needed permission type

  5. Using the search bar in the Permissions tab window, find and add all permissions from the list below one by one:
            agentConversationDetail >  View
            conversationDetail >  View
conversationAggregate  View
Recording >  View
RecordingSegment  View
Queue >  View
Routing > Wrap-up Code > View (link)
Conversation > Communication > View
Example:

Figure 6. Adding the permission

Once all the needed permissions have been added, their final list must have the following look:

Figure 7. Viewing the list of added permissions

6. Click the Savebutton at the bottom of the table.

Figure 8. Saving the added permissions

7. The next thing to be done is to find the needed role in the roles list and then add yourself to the respective role.  To do so, click the More Actions menu icon next to the needed role and then select the Change Membershipoption in the popup list that appears.

Figure 9. Adding your user to a role

8. Open the Genesys Cloud Admin Panel and using the search bar there, find the OAuthfeature.

Figure 10. Searching for the OAuth feature in Genesys

9. Once found, click it and then, hit the Add client button.
10. Add a name - Shelf Message Synchronization in our case - for the credentials you are creating, and indicate their specific type by selecting the Client Credentials checkbox in the Grant Typesblock.

Figure 11. Indicating the type of credentials being created

11. Select the Roles tab to open the respective window, and then assign the Shelf Message Synchronization Role.  

Figure 12. Assigning a role

12. Once done, click the Savebutton at the bottom of the window to save the changes made. 

Figure 13. Saving the created and assigned role in Genesys


Once all the above steps are complete, you are able to see all the data of the Oauth tokens, such as Client ID, Client secret and actual Genesys domain, e.g. mypurecloud.de / mypurecloud.com / etc., which are needed for the integration. 

Figure 14. Viewing data required for syncing the messages from Genesys Cloud

Also, finishing the above steps means that you have successfully enabled the historic data gathering for Genesys and can start using the integration for your business needs with no need to make any other configurations for data collection. 
Repeat the steps above to create a few additional tokens by the formula 1 token per 3 queues that you want to process.


Kustomer Scenario

This chapter describes the Historic Data gathering for the Kustomer platform only and, therefore, is applicable to the Kustomer platform users only. 

Using the API

The script for gathering Historic Data from Kustomer, which is expected to leverage the Kustomer APIs, is currently under development and is expected to be provided once completed.


Required Permissions

The API key needs to be created with the correct set of permissions which are as follows:
  1. org.user.conversation.read
  2. org.user.message.read


Creating API Key for Historic Data Collection

In order to create the API key to be later used for gathering the needed Historic Data from Kustomer, perform the following steps.

  1. Once logged in to the Kustomer platform under admin credentials, go to the Admin Panel and navigate to the Security section of the sidebar panel there. Click the expand icon and then select the API Keysoption from the expanded list.

    Figure 15. Accessing the API Keys window on Kustomer

  2. In the API Keys window that appears, find and click the Add API Key button in the upper right part of the window as shown in the figure above.
  3. In the form that is displayed on the screen, fill in the required fields as shown in the figure below.

    Figure 16. Adding the new API Key on Kustomer

 

The Add API Key Form Fields and Their Details:

  1. Name: Enter any desired or needed name for your new Kustomer API Key.
  2. Roles: Enter the required roles to read conversations and their messages on Kustomer. Make sure to comply with the Required Permissions section above.
  3. Expires (in days): Select the needed duration of your new Kustomer API Key using the dropdown field. Recommended value is 90 days.
  4. CIDR IP Restriction: In this field, enter the set of IP addresses that are permitted to use your new Kustomer API Key.
4. Once you have entered all the needed values in the respective fields, click the Create button to create and save your new Kustomer API Key. 

After you have successfully walked through any of the above procedures - depending on the platform from which the Historic Data needs to be gathered, Shelf becomes able to gather this data for improving the Artificial Intelligence operation, streamline suggestions offered to your organization’s agents, and, respectively, increase their - agents’ - productivity and service quality. This all together can result in the increased value of your organization’s service and, respectively, a higher level of your customer satisfaction and retention.