Set Up Autopilot Amelia with Knowledge Hub

You can use CXone Mpower Expert or a third-party knowledge source A knowledge management system that hosts knowledge articles. with your Autopilot Amelia virtual agent. The connection between Autopilot Amelia and your knowledge source is managed with CXone Mpower Knowledge Hub.

Before You Begin

Setting up the integration of Autopilot Amelia and Knowledge Hub involves two API calls from Autopilot Amelia to CXone Mpower. Before you can configure and test these calls, you must register an application with NiCE. Complete the following tasks to prepare for the integration:

Ensure that you have a Knowledge Hub knowledge base created and configured in your CXone Mpower system. This must be completed by your CXone Mpower Account Representative.
Ensure that you have Autopilot Amelia set up and working before starting the Knowledge Hub integration.
Complete the tasks described in the getting started guide for working with CXone Mpower APIs.
- The client ID and secret must be passed into the payload of the request to get a token. This is set up in tasks 2 and 4 of the getting started guide.
- Integrations with CXone Mpower APIs must consume the discovery service. URLs should not be hardcoded. This is covered in task 5.
- You need to discover the base URL for the API calls used in the integration. This is also covered in task 5. Best practice is to perform the discovery call before every API call you make. This allows you not to hard-code your base URL. For example, you could develop a Web Service Action that consumes the API discovery and passes the base URL on.

Set Up the Integration

Follow these steps to set up the integration of Autopilot Amelia and Knowledge Hub.

Generate a CXone Mpower Access Key

Generate an access key in CXone Mpower. Follow your organization's guidelines for which employee profile to use for access tokens. You can only access the secret key once, so save it in a secure location. You will use it in the next step.

Create a Web Service Action to Generate a Token

In Autopilot Amelia, create a Web Service Action to generate a token. You will configure the Web Service Action with the CXone Mpower access token and secret key you generated in the preceding task. The token that the Web Service Action generates will be used in API calls in the Authorization: Bearer [access token] header.

Give this Web Service Action a name such as Knowledge Hub Token Generation. Use the following information on the Web Service Action:

Request: Set the verb to POST and use the following API: [base URL]/auth/token.

Modify the URL by replacing [base URL] with the base URL for your CXone Mpower system. You can learn what it is by following instructions on the developer portal under API Discovery.
Headers: Add the following parameter:
- Key: Set to Content Type.
- Value: Set to application/x-www-form-urlencoded).
Body: On the Body tab, paste the following request and configure :
```
grant_type=password&username=[accessKeyId]&password=[accessKeySecret]&client_id=[clientId]&client_secret=[clientSecret]
```
In the request, configure the parameters like this:
- grant_type: Set to password.
- password: Set this to the CXone Mpower secret key you generated in the previous task. If you lost the secret key, you must delete the access key you generated and create a new one.
- username: Set this to the CXone Mpower access key you generated in the previous task.
- client ID: Set this to the client ID that you receive after registering the application with NiCE. This is Task 2 in the guide for getting started guide on the developer's portal.
- client secret: Set this to the client secret that you receive after registering the application with NiCE. This is Task 2 in the guide for getting started guide on the developer's portal.
An example of the body is:
```
grant_type=password&username=MZXXK3TPO5XW4ZLU&password=K5RWKZ3FNVXW4ZLUNFXG63TPOVXW4ZOVXW633D&client_id=f47ac10b-ab12-4372-cd34-0e02b2c3d479&client_secret=aGVsbG9E9PQaBc123%3D%3D 
```

Create a Web Service Action to Call Knowledge Hub

Create a second Web Service Action in Autopilot Amelia for the Knowledge Hub API call. Give it a name that shows it's for the Knowledge Hub integration. For example, Knowledge Hub v4.

Under Request, add the following information on the Web Service Action:

Verb: Select POST.
URL: [base URL]/eai-real-time-insight/v4/direct-query

Modify the URL by replacing [base URL] with the base URL for your CXone Mpower system.
Headers:
- Key: Authorization
  
  Value: Bearer [token], where you replace [token] with the appropriate variable to hold the token generated by the Web Service Action you created in the preceding step. For example, ${token}.
- Key: Content-Type
  
  Value: application/json

Body: On the Body tab, paste the following request:

View request body example

{
"schemaVersion": "1.0.0",
"timestamp": "2023-09-06T14:30:00Z",  //Required
"meta": {
  "tenantId": "11edde00-bdf5-9cf0-9890-0242ac110004",  //Required
  "busNumber": "600123244",  //Required
  "contactNumber ": "2678764",  //Required
  "interactionUid ": "123e4567-e89b-12d3-a456-426614174000",  //Required
  "agentUid": "cd447e02-4da7-4489-b918-59f1bf8883e5",  //Required
  "assistProfileId": "string",
  "agentContactUid": "GUID",
  "provider": "ECA",
  "customerId": "string"
},
"query": {
  "uid": "8469807a-d897-4a31-b42a-73c8b6f7669a",  //Required
  "text ": "${query_text}", //Required
  "persona": "I'm a rapper doing rap",
  "language": "en-us"
},
"kbFiltering": {
  "conversationContextRefId": "${conversationContextRefId}",  
  "filters ": {
    "in": {
	"key": "Tags",
	"value": [
	  "Amelia"
	 ]
	}
  }
},
"config": {
  "kbAnswers": {
      "answers": {
	    "enabled": true,
	    "maxWords": 100
      },
      "images": {
        "enabled": true,
	    "maxImages": 5
      },
      "links": {
        "enabled": true,
	    "maxLinks": 5
      }
    },
    "kbProcessSteps": {
      "enabled": true,
      "maxSteps": 5,
      "maxTitleWords": 8,
      "maxStepWords": 10
    },
    "awsBedrock": {
      "awsBedrockKbId": "TGDWK6YABS",  //Required
      "maxKernels": 5,
      "shareable": true
    }
  }
}

Ensure that all required values in the request body are correct. You may need to modify other values to customize the integration to the needs of your organization. You can learn about the fields in the request body and how to complete them.

Build Flows in Autopilot Amelia

The final step in setting up the integration is to build flows that use the Web Service Actions you created.

In your Autopilot Amelia console, create a flow to generate a token and connect it to the token generation Web Service Action you created.
Connect the Knowledge Hub integration Web Service Action you created to the appropriate flows to add it to your Autopilot Amelia conversations.

KB Answer Configuration

Autopilot Amelia provides responses with solutions to the contact's issue. These are based on your organization's knowledge base A knowledge management system that hosts knowledge articles. (KB). For example, if a contact says they're having trouble with Product A, the suggested response could be, "Try resetting Product A. Go to Settings and click Reset."

You can define a maximum word count for KB answers in the response body in Autopilot Amelia. You can also configure KB answers to include:

Process steps: Breaks down KB answers into individual steps. Autopilot Ameliacan send one step at a time to walk the contact through the process of solving their issue.
KB web links: Provides links to KB articles. Autopilot Amelia can send these links to the contact, who can open the articles in a new tab. You can limit the number of links that can be sent in each response.
KB images: Provides images from KB articles. Autopilot Amelia can send these images to contacts. You can limit the number of images that can be sent in each response.

In the response body, you must provide the AWS Bedrock ID for the knowledge base you want to use. You can obtain this ID from your CXone Mpower Account Representative.

Request Body Fields

The following drop-downs contain definitions of the fields in the request body.

Meta section

Field	Details
tenantID	Your unique tenant ID. Replace the default text with your tenant ID. This is a required field. You can obtain this ID from your CXone Mpower Account Representative.
busNumber	The business unit number for the CXone Mpower business unit where Knowledge Hub and Autopilot Amelia are set up. This is a required field. Use a variable for this field. This value should come from the Studio script.
contactNumber	The contact ID. This is a required field. Use a variable for this field. This value should come from the Studio script.
interactionUID	The unique ID for this session of the interaction. This is generated randomly with each interaction. This is a required field.
agentUID	The ID of the agent handling the interaction. This is a required field. Use a variable for this field. This value should come from the Studio script.
assistProfileID	The name of the assist configuration.
agentContactUID	The unique agent contact ID.
provider	The data source.
customer ID	The identifier for the contact's context. This ID ensures that Autopilot Amelia can maintain the same context throughout the conversation. When this property is empty, Autopilot Amelia generates a new ID. On subsequent requests in the same conversation, this property should use that ID to persist the context of that session. Use a variable for this field. This value should come from the Studio script.

Query section

Field	Details
uid	Generates a unique identifier for this specific query. This required field uses generateGUID().
text	Holds the contact's question or query text. This value is passed via the Studio script, so use the same variable used to hold the contact's utterance in that script. This is a required field.
persona	The persona or tone you want Autopilot Amelia to use for contextual interpretation. For example, You are an assistant that helps customers find answers to questions about their Classics, Inc. e-books and e-reader devices. You are warm, confident, and courteous.
language	The language of the query. For example, en-us. If your Autopilot Amelia virtual agent handles conversations in more than one language, use a variable for this field and pass the language value for each interaction from the Studio script.

kbFiltering section

Field	Details
conversationContextRefId	The ID that associates this query with a specific conversation context. This provides continuity across interactions. This ID is generated when Autopilot Amelia makes the initial request to search Knowledge Hub. To maintain context across subsequent interactions, you can include this ID as a parameter in future API requests.
filters.in.key	The filtering key that you want Knowledge Hub to use to narrow the results. For example, if you set this to Tags, only specified filter values found within the Tags key-value pair are applied to this search.
filters.in.value	The list of tags that are used to filter knowledge base results. Separate multiple tags with a comma. For example, "value": ["Tag1", "Tag3"].

Field

Details

conversationContextRefId

The ID that associates this query with a specific conversation context. This provides continuity across interactions.

This ID is generated when Autopilot Amelia makes the initial request to search Knowledge Hub. To maintain context across subsequent interactions, you can include this ID as a parameter in future API requests.

filters.in.key

The filtering key that you want Knowledge Hub to use to narrow the results. For example, if you set this to Tags, only specified filter values found within the Tags key-value pair are applied to this search.

filters.in.value

The list of tags that are used to filter knowledge base results. Separate multiple tags with a comma. For example, "value": ["Tag1", "Tag3"].

Config section

Field	Details
kbAnswers	Allows you to configure a maximum word count for returned responses, and whether responses can include images and links, as well as a maximum number of images and links. answers: Set enabled to true and change maxWords to the maximum number of words allowed in an answer response. The default is 100. images: Set enabled to true and change maxImages to the maximum number of images allowed in an answer response. The default is 5. links: Set enabled to true and change maxLinks to the maximum number of links allowed in an answer response. The default is 5.
kbProcessSteps	Allows you to configure how step-by-step responses are formed.
awsBedrock	Defines which Knowledge Hub knowledge base to use.
awsBedrockKbId	Enter the ID for your instance of Knowledge Hub. You can obtain this ID from your CXone Mpower Account Representative. This is a required field.
maxKernels	The maximum number of kernels to use. The default is 5.
shareable	A Boolean A data type that has two possible values: true and false. setting to indicate if the results are shareable. The default is true.