Skip to main content

Let chatters search your Zendesk or Salesforce knowledge base content


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.


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 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!


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.



      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.


  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.


    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:

      • Public Knowledgebase (Pkb)

      • Customer Portal (Csp)

      • Partner Portal (Prm)

      If articles are only visible in the Internal Salesforce Knowledge application (App), you can't import them into your bot using the Salesforce integration. If you need to import them into your bot anyway, consider using Ada's Knowledge API for those articles.

      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.


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.


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, not

    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.


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

After you've imported your articles, they appear on the Knowledge page, 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

Filtering provides a quick way to see articles that have similar traits, such as articles in the same language, or with the same activation state, or articles from the same source if you have connected multiple knowledge bases.

  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, State, or Source.

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

  4. In the Value list, choose one of the languages, states, or sources available, depending on what you set as your filter type.


    The 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

By default, when you connect your knowledge base to Ada, all of the articles in your knowledge base are active as suggestions to your bot. If necessary, you can exclude articles from appearing in your bot's suggestions.

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

  2. To exclude an individual article from your AI Agent's suggestions, turn off the Active toggle. Your AI Agent only suggests active articles to customers.

    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 change article status in bulk, select the relevant check boxes to the left of the article name.

    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 Set as inactive or Set as active, depending on the change that you wish to make. Your adjustments to article status are now in effect.

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.


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 .