> This page is for version Scripted.
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# 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](/scripted/docs/use-ada-with-your-website/serve-your-website-information-in-chat/let-chatters-search-your-knowledge-base-content) to search
> through your knowledge base using API requests instead.

## Overview\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FY7R3V3P0NNDEE457T2RTECS]

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!

> **Note**
>
> This feature may not be included with your organization's subscription
> package. For more information, see Ada's
> [Pricing](https://www.ada.cx/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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FKK64AFPDMP1BZXNZ2P4JS3A]

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.

![](/_fern-files/developers.ada.cx/e50d06f92ec8d59f32ffb10edeed88136139097d937e28d439c39dd0f8f070ef/ada.docs.buildwithfern.com/2025-05-28T19:49:52.708Z/versions/assets/image/uuid-4a34dbc3-5c0e-a5d4-8883-225931742ecf.gif)

* **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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FKENY93M63YC3AZ9ARCWMC6P]

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:

* [Salesforce Knowledge](#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FY28077ZD3G941SCBTE0RNNA)

* [Zendesk Guide](#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FY7J2EVCC55FNMGZF71V950Y)

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

### Configure suggested articles for Salesforce Knowledge\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FY28077ZD3G941SCBTE0RNNA]

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](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-salesforce/configure-ada-glass-for-salesforce#UUID-4e98e7ce-9e40-c729-c977-ea4718efc0d7_id_360023137073_id_h_01FZ1KMQZXM4KX3NHHCD576H7M).

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](https://help.salesforce.com/s/articleView?id=sf.knowledge_rich_text_considerations.htm\&type=5)
   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](https://help.salesforce.com/s/articleView?id=000322728\&type=1).

   * **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:

     * 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](https://developers.ada.cx/reference/overview-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](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_knowledge_support_artlist.htm)
     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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_section-idm4562916293075233735566344165]

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](https://help.salesforce.com/s/articleView?id=sf.connected_app_manage_oauth.htm)
at Salesforce Help.

### Configure suggested articles for Zendesk Guide\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FY7J2EVCC55FNMGZF71V950Y]

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](https://support.zendesk.com/hc/en-us/articles/4408842656154-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**.

   ![](/_fern-files/_img/dd964653e513fa82bb159e191330be69426797a42fa0dbde31dfb04161404e77.webp)

   #### 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](https://support.zendesk.com/hc/en-us/articles/4409381383578-Where-can-I-find-my-Zendesk-subdomain-).
   Alternatively, you can also use Google's DNS lookup tool:

   1. Go to the [Google Dig tool](https://toolbox.googleapps.com/apps/dig/).
   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/`
   4. 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.
   ![](/_fern-files/_img/1d1871cbf596be4fe102c9cf082489dec9b731dd0a3512c7a2d157fde5bbf486.webp)

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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_section-idm454964160715363371131427001]

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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FKK6557QY96RGWZE3DD6J0QZ]

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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_section-idm4506418719580833661325224649]

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.

   > **Info**
   >
   > 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](/scripted/docs/build-and-maintain-your-bot/personalize-conversations/support-multiple-languages-in-the-same-bot)
   > 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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_section-idm4609094356200033654136920186]

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\[#UUID-de1421b8-6696-51ae-f833-217d430c0434_id_4409280872595_id_h_01FKK65NGQ9DHR4GQCFPS3YH69]

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 [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).