Best practices

Learn best practices for using KnowledgeAI.

Integrate with a KMS or CMS

Integrating with KMS or CMS is a great way to get content into a knowledge base in KnowledgeAI™ and manage it over time because this approach is very powerful.

Import content from a CSV file

When creating one knowledge base based off of another, don't reuse the same CSV file for a second knowledge base in the same hosted region. The article IDs must be unique within the region. In the file for the second knowledge base, clear the article IDs; the application will create article IDs for new articles.

Import CSV

  1. When you add the knowledge base, for Content source, select “CSV.” Then browse to and upload the CSV file. (For details on creating a CSV import file, see the section farther below in this article.)

    Add knowledge base dialog with a callout to the Import content from setting

  2. Click Save.

    If the system finds errors in the CSV file you are importing, you’re notified of this and offered a Download errors button. Use the button to download info on the errors that were found in the import file. Make sure your browser is configured to allow pop-ups, or you won’t be able to complete the download.

Import content from a Google sheet

To import content from a Google sheet, the sheet must be public, i.e., with no file restrictions in place.

When creating one knowledge base based off of another, don't reuse the same Google sheet for a second knowledge base in the same hosted region. The article IDs must be unique within the region. In the file for the second knowledge base, clear the article IDs; the application will create article IDs for new articles.

Import Google sheet

  1. When you add the knowledge base, for Content source, select “Google Sheet.” Then specify the Google sheet to upload. (For details on creating the import file, see the section farther below in this article.)

    Add knowledge base dialog with a callout to the Import content from setting

  2. Click Save.

Create an import file (CSV or Google sheet)

If you want to import a set of articles into a knowledge base when you add the knowledge base, you'll need to create the import file.

An example of a well-formed import file

The import file can contain a subset of HTML, and it should adhere to these limits. Additionally, as a best practice, ensure the file is saved as a UTF-8 encoded CSV file before you import it. This is particularly important if you need to support special language characters (e.g., ö, ü, ß).

To create an import file

  1. Create a new CSV file or Google sheet. A Google sheet must be public, i.e., with no file restrictions in place.
  2. Add the column headers listed below; use the order listed in the table below.
  3. Fill out the rows with your article data. It's recommended that you complete at least these columns: title, summary, detail, tags, and alternates (if using Knowledge Base intents) or intentName (if using Domain intents).

Column headers

Column header name Description
id A String; a unique ID assigned to an article.

This column isn't required when you initially create the knowledge base. However, if you're using a Google sheet that you plan to sync periodically, it does play a role then. Before performing a sync, update the Google sheet to include the "id" column and enter the IDs for all existing articles.

When creating one knowledge base based off of another, don't reuse the same CSV import file or Google sheet for a second knowledge base in the same hosted region. The article IDs must be unique within the region. In the file for the second knowledge base, clear the article IDs; the application will create article IDs for new articles.
tags A comma-separated list of relevant keywords. These highlight the key noun(s) or word(s) in the training phrases. For example, for an article about health insurance, the tags should be "health", “insurance”, “benefits”. These should be words, not sentences.
title The article title. This should be a complete sentence or question that the user might ask. Adhere to best practices. Learn about the limit for the number of characters.
summary A short response or message to be sent to the user. You can include web links, although depending on the channel they might not display correctly. For SMS/Messaging, you might need to show the URL by itself, not wrapped in HTML, since the HTML will be sent as plain text over these channels.

summary is a required field, so if you leave it empty, a truncated version of detail is populated in summary. The content is truncated to the nearest punctuation and character limit. Since the content of detail is merely truncated and used for summary, it might not be ideal. We recommend that you compose a well-written summary (see our best practices). Many brands use Generative AI to accomplish this task.
alternates Applicable if you're using Knowledge Base intents, not Domain intents. In the UI, these are called "intent qualifiers." Intent qualifiers are alternative ways that people ask for the article, i.e., alternative ways to communicate the same intent. Adhere to best practices.
detail A longer message to the user. For messaging, it's recommended that you keep the responses as brief as possible. Learn about the limit for the number of characters.
content_url The URL of a hyperlink. For info on usage, see this section.
image_url The URL of an image. For info on usage, see this section.
audio_url The URL of an audio file. For info on usage, see this section.
video_url The URL of a video file. For info on usage, see this section.
category Assigning a category lets you filter and find articles based on categories in the KnowledgeAI application. Additionally, during a search, AI Search checks the input query against the category. Use only alphanumeric and underscore characters in the category name; only these are permitted.
intentName Applicable if you're using Domain intents, not Knowledge Base intents. This is the intent associated with the article.
validFrom Specify the date and time on which the article becomes active in Epoch time in milliseconds.
validTo Specify the date and time on which the article becomes inactive in Epoch time in milliseconds.

Update content

When updating content in knowledge bases, be mindful that you can’t mix content types within a knowledge base.

Content type How updates are made
KMS or CMS Schedule updates automatically.
CSV file Perform updates manually within the knowledge base. Or, use the Source page to replace the CSV file.

Replacing the file means replacing all the content in the knowledge base with that in a different file. Articles will be added, updated, and deleted, all based on the contents in the new file. New articles are enabled by default, so ensure the content is suitable before you replace the CSV file.
Google sheet In the knowledge base, use the Source page to sync the knowledge base with the contents of the Google sheet, or to replace the sheet with another.

Syncing overwrites the content in the knowledge base with that in the sheet, so adds, updates, and deletes do occur. New articles are enabled by default, so ensure the content is suitable before you sync.

Replacing the sheet means replacing all the content with that in a different sheet. Articles will be added, updated, and deleted, all based on the contents in the new sheet. Here again, new articles are enabled by default, so ensure the content is suitable before you replace the sheet.

Delete content

You can delete a knowledge base's source at any time, but be aware that this permanently deletes all of the articles that were created using the source.

The Sources page within a knowledge base, with a callout to the Delete action link for a source

Integrating with an external CMS/KMS? Learn more about deleting content.