Got an external KMS or CMS? Looking to take advantage of LivePerson AI (AI Search and/or intents) to find and retrieve matched articles? If you answered Yes to both, skip to the Integrating CMS or KMS section of the document. On the other hand, if you want to use the query and answer API of your KMS/CMS, skip to the External Knowledge Base section.
AI Search and/or Intents
When a consumer asks a question or makes an intentful statement, and you pass that query to a knowledge base to find an answer, the answer can be retrieved in one of two ways:
Neither search method makes use of Generative AI or an LLM, but you can do that too - to enrich the answer and make it more contextually aware and natural sounding.
AI Search
AI Search is KnowledgeAI™’s powerful, one-size-fits-all search method that’s based on the latest research in deep learning. Key characteristics of this search include the following:
- There’s no setup required: This is some of the best news. AI Search works right out of the box. Don’t want to invest the time in creating and tuning intents in Intent Manager? No problem. You don’t have to. Just add your content to the knowledge base. Then expose it via a bot integration (use the KnowledgeAI interaction), or set up the knowledge base for Conversation Assist as normal. That’s it.
- It gets to the intent: The AI Search isn’t a type of search that just looks at the words for matches found between the consumer query and the answer. The search also uses language embedding models to make a best attempt to determine the meaning behind those words: What is the consumer trying to convey?
- It’s context-aware: The search considers the whole of the consumer query (and nothing more at this time). So, for example, “I want to book a flight” is understood differently from “Can I borrow a second book at the library?” Homonyms like these are handled.
- It’s phrasing-agnostic: Synonyms are handled too: “I want to buy a ticket” and “I want to purchase a ticket” are understood similarly. Keep in mind that certain niche or archaic synonyms, especially abbreviations, might not be supported (unless you add them directly to the articles).
- It returns multiple answers: If more than one good answer is found, multiple answers can be returned. This means you can use the KnowledgeAI interaction to populate a “carousel” of good answers to the consumer, providing a better consumer experience.
Intent Match search
An Intent Match search is one that makes use of Natural Language Understanding or NLU to find the right answer to the consumer’s query. NLU leverages AI to identify various attributes of a message: meaning, sentiment, and more.
To use this type of search, you must add a set of intents in Intent Manager and tune them for optimal answer retrieval. Then, back in KnowledgeAI, you must tie your articles to the intents.
Like the AI Search, the Intent Match search is powerful and effective.
Choosing a search method
One common question we get is, “Which search method do I use: Intent Match or AI Search?” This is a good question, and our answer to this is to use them both if you can, and if it meets your needs. They are better together.
Benefits of AI Search
- Works right out of the box. No setup is required.
- Performs well when handling consumer queries that are similar to articles in knowledge bases. The broader the coverage, the higher the probability that there will be a match to the consumer query.
- Makes up for issues that can occur when using intents. Since intents are trained by humans, an intent model might have some flaws: There might be gaps in the coverage. There might be an overlap in the coverage. Or, an intent might not be trained well enough. In other words, there’s an article that could be returned, but the match to the input query doesn’t meet the threshold required to return the article. Using the AI Search as a fallback to the Intent Match search is a good, recommended strategy to address issues like these.
Benefits of Intent Match search
- Lets you manipulate outcomes by tuning the answer retrieval yourself. This gives you a layer of control.
- Can outperform AI Search. NLU is better at making predictions. So, if you take the time to tune an intent well, the intent will likely outperform the AI Search. (That said, there’s a tradeoff here, as it’s a fairly significant effort to add and tune intents. Keep in mind that the AI Search performs well on its own.)
- More suitable for specialized scenarios. Conversations that use a highly specific vocabulary do better when intents are used.
- Sometimes, only an Intent Match does the job. Scenarios can exist where the consumer query properly matches to an article that doesn’t have any content that relates to the query.
Search offerings
When you select an answer retrieval method in various parts of the UI, the following choices are offered:
- KnowledgeAI (recommended)
- Intent match only
- AI search only
Here’s an example:
ℹ️ The “Intent match only” and “AI search only” options are primarily intended for testing and for diagnosing issues during troubleshooting. In Production, we recommend that you use the “KnowledgeAI” offering.
“KnowledgeAI” option
The “KnowledgeAI” option is what’s used by the KnowledgeAI interaction in LivePerson Conversation Builder.
- Runs an exact match search.
- Runs the Intent Match search.
- Runs the AI Search.
“Intent match only” option
- Runs an exact match search.
- Runs the Intent Match search.
“AI search only” option
- Runs an exact match search.
- Runs the AI Search.
Search flow
Whether searching one knowledge base or several, the flow is the same:
- Using the specified search offering ("KnowledgeAI," "Intent match only," or "AI search only"), find the article matches in the knowledge bases.
- Aggregate the results, and keep only those in one of the following groups, listed in order of priority:
- Exact match
- Intent match
- AI Search match
- Sort the results in the group by match score.
- Return the top results based on the number of answers requested.
Match scores and thresholds
Match scores
Whenever a knowledge base is searched for an article match to a consumer query, the results receive scores. The score indicates the level of confidence in the match: VERY GOOD, GOOD, and so on.
AI Search assigns scores as follows:
- VERY GOOD: 85-100% match
- GOOD: 70-85% match
- FAIR PLUS: 65-70% match
- FAIR: 50-65% match
- POOR: 0-50% match
Intent Match search assigns scores using the scoring breakdown for the NLU engine used by the associated domain.
Thresholds
Other applications in the Conversational AI suite let you specify a threshold — that is, a minimum score — that a result must have for it to be returned as an answer.
- You might be sending answers to consumers in automated conversations with bots. In this case, you can specify a threshold in the KnowledgeAI interaction within the bot in Conversation Builder.
- Or, you might be recommending answers to agents inline in their conversations with consumers. And, in this case, you can likewise specify an answer threshold in Conversation Assist’s settings.
Regardless of the integration, if you lower the threshold, be sure to test whether the quality of the results meets your expectations. It's generally recommended to keep the quality above FAIR PLUS.
FAQs
Which search method do I use: Intent Match or AI Search?
Which search method is best depends on the use case, your requirements, and your resources. KnowledgeAI’s AI Search works very well on its own and requires no setup. But use them both if you can; they are better together.
AI Search isn’t performing as well as I’d like. What can I do?
If you have a consumer query for which there isn’t a relevant article to serve as the answer, just add that article.
While it’s unlikely that an existing, relevant article won’t yield results, it might happen. In this case, improve the article’s title and/or add tags to the article.
Is AI Search available for external knowledge bases?
AI Search isn't available for external knowledge bases that don't use LivePerson AI. Knowledge bases of this type use the CMS' query and answer API for article suggestions/answers.
How does AI Search work?
In the internal knowledge base, AI Search performs 3 steps to get results:
- Pre-processing: This includes a simple query classification process to remove small talk (chitchat) from the input query. It also includes splitting a long query with multiple sentences into single sentences.
- Retrieval: The input query is concurrently checked against:
- Title alone
- Summary, Detail, and any tags
- Title, Category, and any tags
- Post-processing: This includes the following:
- De-duplication: From the retrieved articles, duplicate articles or highly similar articles are removed.
- Re-ranking: The articles are reordered based on score and category.
- Score calibration: The internal scores of the articles are calibrated to VERY GOOD, GOOD, FAIR PLUS, etc.
How does the Intent Match search work?
In the internal knowledge base, the input query is checked against:
How does the exact match search work?
In the internal knowledge base, the input query is checked against:
Integrating a KMS or CMS
As a company or organization with a strong, online presence, it’s likely that you’ve invested heavily in a tool to manage your knowledge and content. This knowledge management system (KMS) or content management system (CMS) helps keep your content organized for easy updates. You’ve set up the system, trained your users on it, and socialized processes to make sure the content is complete, accurate, and follows your branding rules. So, it's naturally important to you that KnowledgeAI™ connect with this system, so you can leverage your vast knowledge and content in your Conversational AI solution. The good news is that all this is possible.
If your KMS or CMS has a public API for retrieving knowledge articles, you can integrate it with KnowledgeAI using LivePerson’s Integration Hub (iHub) application. iHub embeds Workato, a leading third-party enterprise automation platform, inside Conversational Cloud. What’s so special about Workato? Power. Flexibility. And a no-code/low-code approach to integration and automation.
In iHub, you can create a Workato recipe to sync the content in your external KMS/CMS into KnowledgeAI. Sync the content using a trigger, such as an automated schedule, or sync it on demand whenever you require it.
Terms and concepts
Internal knowledge bases
At LivePerson (and in this documentation), we classify a knowledge base that you integrate with an external KMS/CMS via a Workato integration in iHub as an “internal knowledge base.” This is because the content is stored internally within KnowledgeAI.
In the knowledge base’s settings, you’ll see “internal knowledge base” as the Knowledge base type.
The term “internal knowledge base” isn’t used elsewhere in the UI. However, because there is also such a thing as an external knowledge base, we use the term to make the documentation simpler and communication faster and easier.
Be aware that you can also create an internal knowledge base by importing Web pages, PDFs, a Google sheet, or a CSV file. Or, by adding articles manually within KnowledgeAI. These too are internal knowledge bases because the content is stored internally within KnowledgeAI.
Projects
In Workato, a project is a container for a set of related workflows, recipes, and automation tasks. Create a project to store assets related to your KnowledgeAI integration.
ℹ️ LivePerson recommends that you create one project to store all your KnowledgeAI-related assets. But it’s up to you. Organize things however is easiest for you.
Recipes
In Workato, a recipe is a pre-built automation workflow that connects different applications and systems to perform specific tasks or processes. It consists of triggers that initiate the workflow, actions that define what should happen, and conditions or logic to control the flow of data and information between connected applications.
Recipes simplify integration and automation by providing a structured way to create and manage workflows without the need for extensive coding or development expertise.
At a high level, to integrate your KMS/CMS with KnowledgeAI, you must create a recipe that:
- Retrieves the content from your KMS/CMS
- Maps it to our LivePerson data schema for articles
- Imports the content into a knowledge base in KnowledgeAI
Templates and customization
LivePerson offers both generic and vendor-specific templates to make integration with KnowledgeAI easier.
Take advantage of a template; don’t start from scratch. That said, feel free to customize and extend the recipe however you need. For example, you might want to alter it to send an email to an email address whenever a job fails.
To help you quickly understand how a template works, all of the templates are self-documenting. That is, they include comments that describe the various triggers and actions.
Watch the video
Check out our short video on integrating a Zendesk KMS in under 15 minutes.
ℹ️ While this video walks through the process of integrating a Zendesk KMS in specific, most (if not all steps) apply regardless of the vendor and KMS.
Integrate the KMS or CMS
Prerequisite steps
New to embedded Workato in the Integration Hub (iHub)? Get acquainted by reviewing the general user guide in our Knowledge Center.
Step 1: In KnowledgeAI, create the knowledge base
1. Open KnowledgeAI, and click Add knowledge base in the upper-right corner.
2. Fill out the form, and select “External KMS/CMS” for Content source.
3. Click Save.
4. In the window that appears, use the Copy icon to copy your account ID, the knowledge base ID, and the client secret to the clipboard. (The client secret is used by Workato to authenticate with KnowledgeAI.) Paste the info somewhere for easy reference. You'll need it later in this process.
5. Click Go to iHub.
Step 2: In iHub, activate embedded Workato
This is a step that you only perform once in iHub. It creates the Workato tenant for your account within the mult-tenancy Workato architecture. It also creates an admin user for your account. More users are created on the fly as needed. Learn more about all of this in the iHub Workato user guide in our Knowledge Center.
1. On the left navigation bar, click Manage > Integration Hub.
2. Click Workflows in the menu in the upper-left corner.
3. Click Activate to activate our embedded Workato workspace inside Conversational Cloud.
4. Review and accept the terms of service by clicking the available checkbox. Then click Accept.
5. Click Enter Workato.
Step 3: In iHub, create a project
ℹ️ LivePerson recommends that you create one project to store all your KnowledgeAI-related assets. But it’s up to you. Organize things however is easiest for you.
1. Under Workflows, select Assets.
2. Beside PROJECTS on the left, click the “ + “ sign.
3. Enter a name and description for the project.
4. Click Create project.
Step 5: In iHub, create the Workato recipe
In this step, you create the Workato recipe that imports content from your external KMS/CMS into the knowledge base that you created in KnowledgeAI.
1. Click Community Library on the menu bar.
2. Enter the search term "liveperson" to search for the KnowledgeAI recipe templates.
3. Select "LivePerson Knowledge Articles Import."
4. Select the recipe you need.
5. Click Use this recipe in the upper-right corner.
6. Select the project in which to copy the recipe, and click Copy and save.
7. Click Customize recipe to begin customization.
8. Before you get too far along with customization, change the recipe name to something descriptive and meaningful to your brand.
Key customization points
The comments in the elements in the recipe guide you through customization. However, the following are the key customization points. Vendor-specific recipes vary slightly.
Trigger - Specify a schedule
Below TRIGGER, click the “Trigger on a custom schedule” element. Edit it to specify the schedule on which to run the recipe.
Action - Get the content from the KMS/CMS
Below ACTIONS, locate and click the “Select an app and action” element (or similarly named element depending on the template). Edit the element:
- Select the application (KMS or CMS) to connect to.
- Select the action that retrieves the content from the KMS or CMS.
- Create the new connection to the KMS or CMS.
- Configure any extra settings as required.
Action - Map the content to the LivePerson article schema
Locate and click the “Add items to articles list” element (or similarly named element depending on the template). In the element, map the KMS/CMS article schema to the KnowledgeAI fields provided.
Action - Add the content to the knowledge base in KnowledgeAI
Locate and click the “Add all articles to LivePerson KnowledgeAI” element (or similarly named element depending on the template). This element binds the recipe to the content source in KnowledgeAI.
Edit the element to fill in all required info.
On the Connection tab, you’ll use the info that you recorded earlier when you created the knowledge base in KnowledgeAI. This takes care of:
- Brand/Account ID
- Knowledge Base ID
- Client Secret
Also on the Connection tab, specify the Workato recipe ID. You can get this from the URL in the browser window, like so:
Still in the same element, switch to the Setup tab:
On the Setup tab, there are three settings to take care of:
- deleteUnrepresentedArticlesFromKB: If you set this to "Yes," articles that exist in the knowledge base in KnowledgeAI—but are not represented (included) in the current import request from the external CMS/KMS—are deleted from the knowledge base in KnowledgeAI. So adds, updates, and deletes can all occur in the knowledge base. If you set this to "No," then those unrepresented articles remain, as is, in the knowledge base in KnowledgeAI.
- workatoUserId: To set this field, first click inside of it, and then get the ID from the recipe data like so:
- jobId: You set the job ID just like you set Workato recipe ID: Click in the field, and then get it from the properties in the recipe data.
The API enables all new articles, so ensure the content is suitable before the recipe is run.
Step 6: In iHub, test and debug the recipe
In the upper-right corner, click Test recipe to test the recipe.
The test performs an actual run of the recipe, so this results in updates to the knowledge base in KnowledgeAI.
If you don’t get a success message, debug the recipe and try again after fixing it.
Step 7: In KnowledgeAI, verify the articles
As a final step, go to the knowledge base in KnowledgeAI, and verify the articles are there and look as expected.
Payloads and status codes
Request payload
{
"articles": [
{
"title": "title",
"summary": "summary",
"deleteRequest": "true/false"
//....
}
],
"pruneNonIncludedArticles": "true/false",
"kbId" : "<<kbId>>",
"correlationId" : "<<workatoUserId::recipeId>>",
"jobId" : "<<recipe-jobId>>"
}
pruneNonIncludedArticles is a reference to the deleteUnrepresentedArticlesFromKB value/setting, described earlier.
Success response payload
{
"success": true,
"errorCode": "200",
"successResult": {
"status": "STARTED",
"correlationId" : "xxxxxxxxx"
}
}
Response statuses
There is no response body for non-200 status codes.
Status code | Description |
|---|
200 | Success response |
400 | Bad request; request validation failures |
401 | Not authorized to access the resource |
404 | Requested response not found; knowledge base data source is not found for the given ID; no content source of KMS type found for a given knowledge base ID; invalid recipe ID/Workato user ID/job ID |
429 | Too many requests |
500 | Internal server error |
Start or stop the recipe's schedule
To start a recipe so that it runs on its schedule, click the corresponding action button on the Sources page in KnowledgeAI:
You stop a recipe from running on its schedule in a similar way:
Manually run the recipe
You can run a recipe on demand at any time. To do so, click the recipe name link on the Sources page in the knowledge base in KnowledgeAI. This takes you directly to the recipe in iHub, where you can do this.
In iHub, the option to run the recipe manually (click "Test recipe" not "Start recipe") is available in several prominent spots, like this one below:
Delete content
On the Sources page in the knowledge base in KnowledgeAI, there's a Delete action available for deleting an individual content source.
Deleting a content source does two things:
- Deletes the articles associated with the recipe from the knowledge base.
- Disassociates the recipe from the knowledge base. That is, the content source is removed from the list on the page.
However, the recipe remains available in iHub.
On the other hand, if you first delete a recipe in iHub, you'll still see the content source (the recipe) listed on the Sources page within the knowledge base in KnowledgeAI. And you'll still see a corresponding Delete action available there too. In this case, it works the same: It deletes the associated articles and disassociates the recipe (which doesn't exist in iHub anymore).
Since two different applications are involved (KnowledgeAI and iHub), when performing deletes, ensure things are aligned across the applications as you expect. And take care because the operations aren't reversible.
Reporting
To check the results of jobs, use the Sources page in the knowledge base in KnowledgeAI:
If you encounter errors, scroll way to the right, and click the View errors link. This opens a window with info on the errors.
Finally, from the Sources page, you can quickly get to the recipe in iHub by clicking the recipe name. More detailed reporting on jobs is available in iHub.
Best practices
- KnowledgeAI can run only one recipe per knowledge base at a time. Set each recipe’s schedule accordingly.
- Strive for a “one recipe per knowledge base” approach.
- Don’t use one recipe to sync from multiple external KMS/CMS.
- Connections: Never reuse an existing connection. If you copy (clone) a recipe, in the copy always create and configure a new connection. This is necessary because the recipe ID is bound in the connection.
- Importing articles into KnowledgeAI: Always use the available “Add all articles to LivePerson KnowledgeAI” connector element; don't set up a custom HTTP request.
- Monitoring: Check the Sources page in KnowledgeAI on a regular basis to verify that your jobs are running successfully. It’s also a best practice to regularly verify that the content in KnowledgeAI looks as expected.
- Minor changes: Go ahead and make these directly in the relevant recipe.
- Major changes: To make these, we recommend that you clone the recipe, make the changes in the copy, and then replace the original recipe after testing has proven to be successful.
Troubleshooting
Within a recipe, use the Jobs page to drill down to errors that occurred:
On the Jobs page, click the error to navigate to the problematic element.
Then use the Input, Error, and Debug panels to help you understand and solve the problem.
If you're discussing an issue with us, provide us with the correlationId that was received in the response. We'll use that to check our internal logs.
External Knowledge Base
What's an external knowledge base?
An external knowledge base is a knowledge base whose content isn't stored internally within KnowledgeAI™.
An external knowledge base integrates with an external CMS and — importantly — it doesn't use LivePerson AI. Instead, it uses the CMS' query and answer API for article suggestions (answers). The consumer utterance or input phrase is simply passed on to the API.
Integrating with a CMS in this way lets your content creators use familiar tools and workflows. You can integrate with any CMS that has the capability, i.e., an API connector. Notable examples include Salesforce and Zendesk.
As an alternative, consider adding an internal knowledge base that likewise integrates with the KMS/CMS. Internal knowledge bases store the content within KnowledgeAI, so they can take advantage of AI Search and/or intent matching.
Getting started
Learn how to add an external knowledge base without LivePerson AI.
High-level workflow
- In KnowledgeAI™:
- Add the external knowledge base.
- Test the CMS integration using the Answer Tester tool.
- Expose the articles to agents by integrating KnowledgeAI into your Conversation Assist solution, or expose them to consumers by integrating KnowledgeAI into a LivePerson Conversation Builder bot.
Add an external KB without LivePerson AI
- Click Add Knowledge Base in the upper-right corner.
- In the window that appears, select the Other Connection tab, and then select External Knowledge Base without LivePerson AI.
- Specify the following:
- Knowledge Base Name: Enter a descriptive name, e.g., “Technical Support FAQs.”
- Content Provider: Select the name of the content provider. If the provider isn't listed, select "Other," and enter the name.
- Language: Select the language of the content. This setting is informational only and doesn't affect the behavior of the knowledge base.
- Click Next.
- The request should return the best article matches. Each article must contain a title and at least one of these content attributes: summary, detail, contentURL, imageURL, videoURL, or audioURL.
- Method: Select the type of HTTP request method.
- URL: Enter the request target, the URL.
- Credential: Select the credential to use for authorization if applicable.
- + Add Request Headers: Add any request headers to include in the request.
- + Add Request Parameters: Add any request parameters to pass in the URL’s query string.
- + Add Post Body: Enter the payload to send if applicable.
- Here, provide a Jolt transformation spec that can be used to "transform" the response into the LivePerson KnowledgeAI article schema. In other words, given the request, map the article suggestions/answers data model (schema) to the LivePerson KnowledgeAI data model.
- Click Save.
Test the CMS integration
After you've add an external knowledge base that doesn't use AI, you can test the integration with the Search tool. This involves entering a consumer utterance to see and evaluate the results that are retrieved from the CMS.
To test the CMS integration
- Open the knowledge base.
- Initially, the Articles page doesn’t show any metadata or content because, with this type of external knowledge base (one without LivePerson AI), only configuration information is stored within KnowledgeAI. The content remains in the CMS.
- This performs a search against the CMS.
- Answers are evaluated by your external CMS. When they're returned, they're always assumed to be a match.
Saving an incomplete knowledge base
Adding an external knowledge base can take some time, so the KnowledgeAI application gives you the option to save a knowledge base in an incomplete state. This lets you step away from the configuration work and come back to it at a later time.
Once you start the process of adding the knowledge base — i.e., you provide a name for the knowledge base — if you then click Cancel, you are prompted to choose whether to save your work:
Click Yes to save the knowledge base.
You can find your incomplete external knowledge bases listed along with your other knowledge bases on the dashboard. They're given an "Incomplete" status to indicate the configuration is incomplete.
A knowledge base is considered no longer "Incomplete" once all required fields are completed for the first time.
Keep in mind that completing the initial setup of a knowledge base, thereby moving out of "Incomplete" status, doesn't indicate a proper configuration. You must test the knowledge base to verify this. Additionally, be aware that a knowledge base never returns to "Incomplete" status if you subsequently remove or alter required information.
To delete an incomplete knowledge base, click the knowledge base's 3-dot icon (on the right), and select Delete.
Ready to move on? Click here to proceed.
