Docs

Integrations / Knowledge

Freshservice Knowledge Base

Index and search Freshservice knowledge articles in Risotto

Connect your Freshservice workspace to Risotto to make your Solutions articles searchable through the AI assistant.

Prerequisites

Before setting up the Freshservice Knowledge Base integration, ensure you have:

  1. API Key: a Freshservice API key. The account that owns the key needs an agent role in the workspace, with the access level Across the workspace. An admin role alone cannot read Solutions articles. See Choose the account for the API key.
  2. The Freshservice URL: the URL for your Freshservice instance (e.g. https://mycompany.freshservice.com)
  3. Workspace ID: the number of the workspace that contains the articles. Use the number, not the workspace name.

Setup Process

Step 1: Get Freshservice API Key

  1. Go to your Freshservice instance.

  2. Go to your Profile settings

    Click your profile picture (top-left) and choose Profile settings.

  3. Copy your API Key

    Find Your API Key on the right side. Reveal it, copy it, and store it securely.

  4. Copy your Workspace ID

    In Freshservice, go to Admin → Manage Workspaces and click the workspace from the list. The URL will look like https://mycompany.freshservice.com/a/admin/workspaces/2/edit. The ID in this example is 2. Enter this number, not the workspace name.

Step 2: Configure Integration in Risotto

  1. Open Freshservice's page

    Go to Settings → Integrations → Freshservice and open the Knowledge tab. In the Knowledge base section, click Add workspace. If nothing is connected yet, click Index a workspace on the Freshservice workspaces row. The Index a knowledge base dialog opens.

  2. Configure the Index

    Enter the following required information:

    • Site URL: Your Freshservice instance URL (e.g. https://mycompany.freshservice.com). Risotto fills it in from your Freshservice connection when there is one. Start it with https://.
    • Workspace ID: The Workspace ID (e.g. 2)
    • API key: A vault credential that holds your Freshservice API key
    • Excluded categories (Optional): A comma-separated list of Solutions category IDs that Risotto does not index. To find a category ID, open the category on the Solutions page and copy the number after /categories/ in the URL. When left empty, Risotto indexes the articles in every category of the workspace.
    • Department and Audience: Choose who gets answers from this index. See Indexes.

    Risotto names the index after the workspace ID.

  3. Create and Monitor Index

    Click Index articles. The workspace's card on the Knowledge tab shows the progress, and so does the Indexing Jobs panel on Knowledge > Indexes.

Create index on Knowledge > Indexes still adds a Freshservice index with the same details plus an Index name. It is the only place to set Profile filters.

Content Considerations

  • Risotto indexes the title and the text of each published article in the workspace's Solutions folders, including the articles in sub-folders. It does not index attachments.
  • Risotto does not index draft articles. Publish the article in Freshservice, then click Reindex. A reindex also removes a draft that an earlier run indexed.
  • Risotto skips the categories in Excluded categories. If you exclude every category, the index fails.
  • A reindex gets the current version of each article.

Reindexing Content

To pull in article updates:

  1. Navigate to Knowledge → Indexes
  2. Find your Freshservice Knowledge Base index
  3. Click the row's ⋮ menu (Index actions), then click Reindex

Troubleshooting

The index fails with "No documents found"

Risotto found no articles in the workspace. Make sure that the Workspace ID is the ID of the workspace that contains your Solutions articles.

The index fails with "Server error while getting workspace"

Freshservice refused a request from Risotto. Risotto shows this message for every refused request, also when the cause is a wrong setting. Do not retry with the same settings. Check these causes:

  • The Workspace ID is the workspace name (for example, My Team) or a number that does not exist. Enter the number from the workspace URL.
  • The account that owns the API key has no agent role in the workspace. Freshservice then refuses to show Solutions articles. Add an agent role with the access level Across the workspace. See Choose the account for the API key.
  • The Site URL or the API key is wrong.
Some articles are missing from search results
  • Make sure that the article is published. Risotto does not index drafts
  • Make sure that the article's category is not in Excluded categories
  • Make sure that the article is in the workspace that you set in Workspace ID
  • If you changed the article after the last run, click Reindex

Content Verification

After indexing, use Knowledge → Playground to confirm Risotto can find and reference your indexed articles.

Something wrong or missing? Report an issue · View as Markdown