Skip to main content

Let chatters search your Zendesk or Salesforce knowledge base content

info

This feature used to be called Smart Search.

Ada’s suggested articles feature automates knowledge base search for Zendesk Guide and Salesforce Knowledge. If you use either of these tools, follow the guide below.

For other tools, see Let chatters search your knowledge base content to search through your knowledge base using API requests instead.

Overview

With suggested articles, your bot can use your knowledge base as a backup when it doesn't have a trained Answer for a question. If it finds any article matches in your knowledge base, your bot shares links to those articles with the chatter - and on the knowledge hub page, you can control which articles your bot suggests.

This is a great way to enhance the chatter experience by ensuring they get the information they're looking for!

note

This feature may not be included with your organization's subscription package. For more information, see Ada's Pricing page, or contact your Ada team.

To get started, your organization must have a public-facing knowledge base (not restricted behind a login) in either Zendesk Guide or Salesforce Knowledge.

Additionally, the URLs in your knowledge base must have the default structure that Zendesk Guide or Salesforce Knowledge automatically provide. If your knowledge base URLs have been modified, after your bot has scraped the contents of your knowledge base, the links won't work.

How suggested articles work

Once you connect suggested articles to your knowledge base, your bot ingests the articles in it. Then, your bot can search the content of these articles to find the best match for any questions it doesn't have an Answer for. It serves up to three article links in order of relevance, depending on how many are a good match.

  • When does my bot search for articles?

    Your bot searches for articles if no trained Answers match the chatter's question, and when the chatter's question also contains at least four words, each of which is longer than one character.

    Note that the question word and character minimums don't apply to questions written in Chinese, Japanese, Korean, Tagalog, or Thai.

  • How does my bot find articles?

    Ada uses its search logic on your knowledge base, and looks at both the article title and body content to find a match. It doesn't use labels or other search relevance data. Additionally, Ada only searches your knowledge base for queries that are four words or longer, excluding common words such as "and," "the," etc.

  • What if there are no article matches?

    Chatters only see suggested articles if there is at least one relevant article match to their question. If there are no article matches, your bot responds with the Not Understood Answer.

Configure suggested articles

Suggested articles configuration requirements vary, depending on the platform you are connecting. In this section, you'll find the instructions for setting up each of the supported platforms.

Suggested articles are currently available for the following knowledge base platforms:

For both platforms, each article must be smaller than 5MB to be uploaded into your bot.

Configure suggested articles for Salesforce Knowledge

Before you connect your Salesforce knowledge base with your Ada dashboard, configure the following in your Salesforce instance:

  1. Create a connected app. Salesforce allows external applications, like suggested articles, to connect to their platform using a special framework they call a connected app. You must create a connected app in Salesforce before you connect your knowledge base with Ada. To learn how, see Create a new connected app in Salesforce.

  2. Use rich text fields. Suggested articles require that your Salesforce knowledge base articles use rich text fields. For more information, see Rich Text Fields in Knowledge Articles in Salesforce's documentation.

  3. Take advantage of multilingual support. Ada can suggest articles in your chatter's language. Be sure to enable your supported languages in both your Salesforce knowledge base and in your Ada bot.

After you have everything ready to go in your Salesforce instance, you can finish the configuration process for your bot:

  1. On the Ada dashboard, go to Settings > Integrations.

  2. Under Knowledge Base Integrations, beside Salesforce, click Configure. The Connect Salesforce Knowledge dialog box appears.

  3. Under Help Center URL and Instance URL, enter the URLs that pertain to your Salesforce instance. Depending on your configuration, these might be the same. For more information, read the Salesforce guide View instance information for your Salesforce Organization.

    • Help Center URL: The public URL for your Salesforce knowledge base and community site. This is the URL your bot uses to search and display articles.

      Example: https://_YourKBDomain_.salesforce.com

      note

      If you have more than one URL for your setup, you can only use one at a time for suggested articles.

    • Instance URL: The URL for your Salesforce account. Ada uses this to authenticate the connection.

      Example: https://_YourDomain_.my.salesforce.com

  4. Under Consumer Key and Consumer Secret, enter the values that Salesforce automatically generated when you created your connected app.

    • Consumer Key: The Salesforce name for the OAuth 2.0 client_id.

    • Consumer Secret: The Salesforce name for the OAuth 2.0 client_secret. You can think of this as the password that allows your bot to connect to Salesforce through your connected app.

    tip

    Need to retrieve your Consumer Key and Consumer Secret? On the Salesforce dashboard, go to Setup > App Manager, locate your app in the list, click the drop-down arrow on the right, then click View to open your app details. You'll find your credentials under the API section.

  5. By default, your bot indexes all fields from your knowledge base that are mapped to the field name Text Area (Rich). However, you can enter your own field name under Custom Content Field Name to index a different field configured in your Salesforce instance. This might be useful if you want to reduce the amount of content that appears for each search result.

  6. Under Show only specific articles, choose which Salesforce articles you want your bot to suggest.

    • Select Show all articles to allow your bot to suggest any of the articles in your knowledge base, regardless of their intended audience.

    • Select Show only articles from a specific channel to restrict suggested articles to a particular channel. Then, select the appropriate channels. You can select any combination of:

      • Internal Salesforce Knowledge application (App)

      • Public Knowledgebase (Pkb)

      • Customer Portal (Csp)

      • Partner Portal (Prm)

      For more information on the above, including how the abbreviations in parentheses work with Salesforce's API, see Articles List in Salesforce's documentation.

  7. In the Connect Salesforce Knowledge dialog, copy the Ada Callback URL, then paste it in the Salesforce connected app's Callback URL field.

  8. Click Authenticate. A new browser window opens displaying the Salesforce login page.

  9. Log in to your Salesforce account. Then, in the Allow Access dialog box, click Allow to grant your bot access to your Salesforce knowledge base API. The Allow Access dialog box closes automatically.

The connection between your bot and Salesforce Knowledge is complete. After successfully connecting, you'll find a new locked Answer, Suggest Relevant Articles, that lets chatters know the bot is about to share knowledge base articles with them. Use Ada's default message or customize the content as you see fit.

note

Once connected, it may take a few minutes for your bot to complete the initial sync with your knowledge base. Your bot won't suggest articles from your knowledge base until that sync is complete.

Reconnect your knowledge base if your access permissions were revoked

If you see an error message that says your bot can no longer sync with your knowledge base, it's likely a problem with access permissions related to your Salesforce account's Refresh Token expiring. To fix this, disconnect your Salesforce Knowledge integration and reconnect it again with the same credentials.

You may also want to update your refresh token policy; for information on how, see Manage OAuth Access Policies for a Connected App at Salesforce Help.

Configure suggested articles for Zendesk Guide

To connect Ada to your Zendesk knowledge base, you need to enter your Zendesk subdomain into your bot.

info

Your Zendesk knowledge base needs to be publicly facing for Ada to consume its content. If your users have to log in to read your articles, Ada can't integrate it with your bot.

To change this setting, follow the instructions in Restricting help center access to signed-in end users at Zendesk's Help Center, and turn off the Require sign in setting.

Be sure you use your actual Zendesk subdomain, and not a custom domain name if you have one.

  1. On the Ada dashboard, go to Settings > Integrations.

  2. Under Knowledge Base Integrations, beside Zendesk Guide, click Configure. The Connect Zendesk Guide dialog appears.

  3. In the Subdomain field, enter your Zendesk subdomain, then click Connect.

    Find your Zendesk subdomain if you're using a custom domain

    If your organization uses a custom domain name for your knowledge base URL and not the default Zendesk subdomain, you'll need to find your actual subdomain to complete the suggested article configuration steps.

    Zendesk has some tips for finding your subdomain. Alternatively, you can also use Google's DNS lookup tool:

    1. Go to the Google Dig tool.

    2. In the Name field, enter your knowledge base's custom domain name. Include only the domain elements. Don't include the https://, or any pathways, slashes, etc.

      Example: Enter help.acustomdomain.com, not https://help.acustomdomain.com/

    3. In the list of options below the Name field, click CNAME. In the results field that appears, under Target, you'll find your full Zendesk URL containing your actual subdomain.

  4. A confirmation message displays in the dialog to indicate a successful connection.

  5. After successfully connecting, you'll find a new locked Answer, Suggest Relevant Articles, which lets chatters know the bot is about to share knowledge base articles with them. Use Ada's default message or customize the content as you see fit.

The connection between your bot and Zendesk Guide is complete. Now your bot can leverage your knowledge base to make sure your chatters get the information they need.

note

Once connected, it may take a few minutes for your bot to complete the initial sync with your knowledge base. Your bot won't suggest articles from your knowledge base until that sync is complete.

Manage suggested article settings and your articles in knowledge hub

After you've imported your articles, they appear in the knowledge hub, sorted so the articles that were most recently updated in your knowledge base appear first. From there, you control whether your bot sends suggested articles to chatters, or manage individual articles.

Turn suggested articles on or off

By default, after connecting your knowledge base to Ada, suggested articles are automatically turned on. However, you can turn them off at any time. When they're off, if a chatter types a message that doesn't match any of the bot's training, the bot serves the Not Understood Answer.

  1. On the Ada dashboard, go to Build > Knowledge.

  2. Beside Suggest relevant articles, turn the toggle on or off.

Filter articles by language

If your bot supports multiple languages, you can filter the articles in your knowledge base by language.

  1. On the Ada dashboard, go to Build > Knowledge.

  2. Under Articles, click the Filter drop-down. Then, in the Select filter type list, click Language.

  3. In the Operator list, choose Is or Is Not.

  4. In the Value list, choose one of the languages supported in your bot.

    info

    This list contains the languages that you have enabled in your bot. This list of languages might be different from the list of languages in your knowledge base. If you need to change these languages, go into your multilingual settings and update the languages your bot supports.

  5. Click Apply. The list of articles updates to match your filters.

Control whether your bot can suggest individual articles

If necessary, you can exclude articles from appearing in your bot's suggestions.

  1. On the Ada dashboard, go to Build > Knowledge.

  2. Under Articles, click either the Enabled or Disabled tabs to display the articles in each category. Your bot only suggests articles on the Enabled tab to chatters.

    If you want to see any of your articles in more detail, you can click an article's name to open it in a new tab.

  3. To move articles to the other category, select them using the checkboxes beside their names. At the bottom of the list of articles, you can also change how many articles to display at a time, or move between pages. Even if you scroll through different pages onscreen, the dashboard remembers the articles you've already selected.

  4. At the bottom of the page, click either Disable articles or Enable articles, depending on which tab you're on. The articles then appear in the other tab of the Articles list.

Chatter experience

When asked a question for which the bot doesn't have an answer, but for which there are relevant knowledge base articles, the bot presents the chatter with a list of the articles that best relate to the question. The chatter can then select the article they think is the best match. The article opens in its own frame within the main Ada chat window.

note

Your bot only suggests articles if a chatter's question is composed of a minimum of four words, each of two letters or more.

  1. The chatter asks a question.

  2. The bot responds with the text in your bot's Suggest Relevant Articles Answer. This text should indicate that the bot doesn't know the answer to the question directly, but has some articles that may be relevant.

  3. The bot suggests up to three articles which best match the chatter's question.

  4. The chatter clicks the link to the article of their choice.

  5. The article opens within the Ada chat window.

  6. Once done with the article, the chatter closes the article by clicking the X.

  7. The article window closes, and can select another article, or continue chatting with your bot.


Have any questions? Contact your Ada team—or email us at .