> This page is for version Generative (default).
> 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.

# Knowledge integration

Ready to start serving knowledge to your customers? You can start by connecting your knowledge base with your AI Agent.

The method you use to connect your knowledge base depends on the tools you use to author and publish your knowledge base:

* If you use Zendesk or Salesforce, you can follow the instructions below to use Ada's existing integrations with those tools.
* If you use different authoring tools, you can contact your Ada team, so they can use a custom integration that collects information in your knowledge base and uploads it into your AI Agent using the [Knowledge API](https://developers.ada.cx/reference/overview-knowledge-api).

After you have uploaded your knowledge base content into your AI Agent, you can [manage your knowledge content](/generative/docs/knowledge/article-management) to include or exclude information from individual articles in your AI Agent's responses.

## Prepare your knowledge base content\[#kb-prep]

Good knowledge base content is structured logically, so both humans and AIs can get appropriate context and understand the information it contains. Take a look at [Prepare your knowledge base as a source for AI generated content](/generative/docs/knowledge/agent-logic/knowledge-setup) to make sure you're following best practices on making a knowledge base usable for both human and AI readers.

## Provide knowledge base content written in multiple languages\[#kb-langs]

Your AI Agent can provide customers with content sourced from knowledge bases written in languages other than English. To enable this feature, contact your Ada team.

Your AI Agent can use knowledge base content written in the following languages:

* English
* Arabic
* Chinese
* Dutch
* French
* German
* Italian
* Portuguese
* Spanish

> **Info**
>
> Make sure that any languages in your knowledge base content are enabled in your language settings. For more information, see [Support multiple languages in the same AI Agent](/generative/docs/setup/languages/about-multilingual-support).

Here's how your AI Agent generates responses from non-English knowledge bases:

* When a customer asks your AI Agent a question, your AI Agent looks for content from articles written in the same language the customer asked in. If articles are available in that language, it uses them to generate responses in the customer's language.

  If it can't find content in the knowledge base for that language, it doesn't look in knowledge base content written in any other languages, and asks the customer for a different question.

* If a customer asks your AI Agent a question in any language you don't have knowledge base content written in, but the language is enabled in your language settings, your AI Agent automatically translates knowledge content written in English to generate responses. It never translates knowledge content from any other languages.

If you're adding content in a new language using a Zendesk or Salesforce integration, note that it can take up to 15 minutes for your articles to appear on the Knowledge page.

## Connect your Zendesk or Salesforce knowledge base\[#zd-sf]

### Before you begin\[#before]

Before connecting your knowledge base with your AI Agent, check to make sure you're set up for success. If you're using a Zendesk or Salesforce knowledge base, make sure it meets the following criteria:

* Your knowledge base must be public-facing (i.e., not restricted behind a login).
* 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 AI Agent has scraped the contents of your knowledge base, the links won't work.
* Each article must be smaller than 5MB to get uploaded into your AI Agent.

Additionally, you should know that your AI Agent will sync automatically with your knowledge base every 15 minutes.

### Connect your knowledge base\[#zd-sf-connect]

Open an expander to learn how to connect your knowledge base, depending on the tool you're using.

#### Import articles from Zendesk Guide

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

1. If your Zendesk knowledge base is restricted behind a paywall, remove that restriction. To do so, 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.

2. On the Ada dashboard, go to **Training** > **Knowledge**. Then, at the top of the page, click **Add source**, then click **Zendesk**. The Connect Zendesk Guide window appears.

3. Under **Zendesk Subdomain**, enter your subdomain, then click
   **Connect**. A confirmation message displays in the window to indicate a
   successful connection.

   ![](/_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 article import
   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:
   3. Go to the [Google Dig tool](https://toolbox.googleapps.com/apps/dig/).
   4. 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/`
   5. 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)

> **Note**
>
> Once connected, it may take a few minutes for your AI Agent to complete the
> initial sync with your knowledge base. Your AI Agent won't use articles
> from your knowledge base until that sync is complete.

#### Import articles from 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 Ada, 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](/generative/docs/handoffs/salesforce/salesforce-chat/ada-glass-configuration#create-a-new-connected-app-in-salesforce).

2. **Use rich text fields**. Imported 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 generate responses using articles
   in your customer's language. Be sure to enable your supported
   languages in both your Salesforce knowledge base and in your
   AI Agent.

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

1. On the Ada dashboard, go to **Training** > **Knowledge**. Then, at the top of the page, click **Add source**, then click **Salesforce**. The Connect Salesforce Knowledge window appears.

2. 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 AI Agent 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 importing articles.

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

     **Example**: https\://`YourDomain`.my.salesforce.com

3. 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 AI Agent 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.

4. By default, your AI Agent 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.

5. Under **Show only specific articles**, choose which Salesforce
   articles you want your AI Agent to use to generate responses.

   * Select **Show all articles** to allow your AI Agent to use any of
     the articles in your knowledge base, regardless of their intended
     audience.

   * Select **Show only articles from a specific channel** to restrict
     articles used in generating responses 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 AI Agent using the Salesforce integration. If you need to import them into your AI Agent anyway, consider using Ada's [Knowledge API](https://developers.ada.cx/reference/overview-knowledge-api) for those articles.

     For more information on importing articles, 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.

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

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

8. Log in to your Salesforce account. Then, in the Allow Access window, click **Allow** to grant your AI Agent access to your Salesforce
   knowledge base API. The Allow Access window closes
   automatically.

> **Note**
>
> Once connected, it may take a few minutes for your AI Agent to complete the
> initial sync with your knowledge base. Your AI Agent won't use articles
> from your knowledge base until that sync is complete.

#### Reconnect your knowledge base if your access permissions were revoked\[#sf-reconnect]

If you see an error message that says your AI Agent 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.

#### Import articles from Contentful

To connect Ada to your Contentful knowledge base:

1. On the **Ada dashboard**, go to **Training > Knowledge**, then click **Add source**.

2. Select **Contentful** from the menu and the Contentful landing page will appear.

3. Click **Connect**. The Contentful window opens.

4. Provide the following details:

   * **Connection Name**: Enter a unique name for this connection.

   * **Contentful Space ID**: Enter the unique ID of your Contentful space.

     > **Tip**
     >
     > To find your **Space ID** in Contentful, check the **URL** in your browser or navigate to **Settings** (⚙️ in the top-right corner) > **General Settings**, then copy your **Space ID**.

   * **Top-Level Content Types**: Specify which content types should be imported as top-level articles.

     > **Tip**
     >
     > To find your **Content Type** in Contentful, navigate to **🔧 Content model**, click on the **Name** of the content type you are interested in, and select **Copy ID** at the top of the page.

   * **Excluded Content Types**: List any content types that should not be imported.

   * **Contentful Delivery API Token**: Required to retrieve published content.

   * **Contentful Preview API Token**: Used by the webhook to fetch top-level content, including references to unpublished or deleted content.

     > **Tip**
     >
     > Both the **Delivery API Token** and **Preview API Token** can be found in **⚙️ Settings** > **API Keys**.

   * **Content Languages** – Enter the language codes for the content you want to import.\
     *Example:* For English, enter `en-us` and for French, enter `fr-ca`.

   * **Include Tags**: Select if you want to import and use Contentful tags.

     > **Note**
     >
     > Selecting **Include Tags** imports all tags in your Contentful instance, whether they are related to your top-level content or not.

5. Click **Connect**. A window will appear, requesting access to Contentful for your AI Agent. Click **Allow**.

6. If successful, a new **Source** appears in the **Knowledge** section, and your articles will begin syncing.

### Update your content in real-time

To keep your Contentful knowledge base in sync with Ada, configure a webhook:

1. In Contentful, navigate to: **Settings** (⚙️ in the top-right corner) > **Webhooks**.
2. Click **Add a new Webhook**.
3. Name the webhook (e.g. Ada Knowledge Sync).
4. Make sure to set the **URL** to the following and ensure the **HTTP method** is set to **POST**.

   * **AI Agents in the US region:**
     ```
     https://solutions.ada.support/kb_apps/contentful/webhook/update_articles
     ```
   * **AI Agents in the EU region:**
     ```
     https://solutions.eu.ada.support/kb_apps/contentful/webhook/update_articles
     ```
5. Under **Triggers**, find the **Entry** row in the table and check **Publish** and **Unpublish**.
6. Under **Headers**, add a custom header with the following:
   * **Key:** `X-Ada-Authorization`
   * **Value:** Your **Installation ID**. Follow these steps to locate it.

     1. On the Ada dashboard, go to **Training** > **Knowledge**, then go to the **Sources** tab.
     2. Beside your knowledge base setting, click **Settings**. You are directed to the Contentful landing page showing your Connections.
     3. Click the three dots **⋮** next to your installation and select **Settings**.
     4. In the Connect to Contentful window, find the last ID value in the URL:
     ```
     <your-ai-agent-handle>/platform/integrations/67993c61d8dd73984a6c7297/connections/<your_installation_id>/edit
     ```
     6. Copy your **Installation ID** in the webhook **Headers**.
     7. Click **Save** to complete the setup.

     > **Note**
     >
     > You can add multiple installation IDs under a single webhook using a comma separator (e.g., `id_1, id_2`).

## Add more Contentful spaces

If you need to connect another Contentful space, add a new connection and set up a webhook for that space.

1. On the **Ada dashboard**, go to **Training > Knowledge**.
2. At the top of the page, click **Add Connection**. The Connect to Contentful window appears.
3. Enter the required details and complete the setup.

> **Note**
>
> Each Contentful space requires its own webhook. However, if you have multiple installations under the same space, you can use one webhook and list all **Installation IDs** in the **X-Ada-Authorization** header.

## Disconnecting your Contentful Knowledge Base

To disconnect Contentful from Ada:

1. On the Ada dashboard, go to **Training** > **Knowledge**, then select the **Sources** tab.
2. Beside your knowledge base setting, click **Settings** to open the Contentful landing page showing your Connections.
3. Click the three dots **⋮** next to your installation and select **Delete Connection**.
4. Once deleted, the **Source** and associated articles will be removed from Ada’s Knowledge section.

#### Import articles from other integrations

If you have created additional knowledge integrations beyond Zendesk and Salesforce, they will also be available for import. Simply select the integration from the **Add source** list to import articles from that source.

Developers can create custom knowledge integrations with Ada. To learn more, review our [Integration documentation](https://developers.ada.cx/reference/integrations/overview).

### Manage your knowledge base connection\[#kb-manage]

After you connect your Zendesk or Salesforce knowledge base with your AI Agent, you can go back to edit your connection settings.

1. On the Ada dashboard, go to **Training** > **Knowledge**, then go to the **External sources** tab.
2. Beside your knowledge base setting, click **Settings**. There, you can modify your knowledge base connection settings, or disconnect it.

## Connect your knowledge base through the Knowledge API\[#kb-api]

To use a knowledge base that you maintain with tools other than Zendesk or Salesforce, you have to use a custom integration that works with the tools you use to extract your data and upload it into the Knowledge API. Depending on your integration, the frequency of how often your AI Agent gets updated content from your knowledge base may vary.

To learn more about the Knowledge API, including limits on article and request size, see [Knowledge API](https://developers.ada.cx/reference/overview-knowledge-api) at Ada's developer documentation.

---

Have any questions? Contact your Ada team, or email us at [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).