# Zendesk Guide

Index and search Zendesk Guide help center articles in Risotto

Connect your Zendesk Guide help center to Risotto to make your published articles searchable through the AI assistant.

> **Note:** This indexes **Zendesk Guide** help center articles. To sync Zendesk
> **tickets**, see the [Zendesk ticketing
> integration](https://www.tryrisotto.com/docs/integrations/ticketing/zendesk) instead — the two are
> configured separately, even though they share credentials.

## Prerequisites

> **Warning:** You need a Zendesk **Admin** account, or a role with the **Manage webhooks**
> permission, to generate the API token this integration uses.

Before setting up this integration, ensure you have:

1. **Your Zendesk subdomain** — the part before `.zendesk.com` (e.g. `mycompany`)
2. **An API token** — see [Enable Token Access and Generate an API Token](https://www.tryrisotto.com/docs/integrations/ticketing/zendesk#1-enable-token-access-and-generate-an-api-token) in the Zendesk ticketing guide for the steps
3. **The email address of the user who generated the token**

> **Tip:** If you've already connected Zendesk for ticketing, you can reuse the same
> subdomain, email, and API token here — you don't need a second token.

## Setup Process

### Step 1: Configure Integration in Risotto

1. **Open Zendesk's page**

   Go to [**Settings** → **Integrations** → **Zendesk**](https://dashboard.tryrisotto.com/settings/integrations/zendesk) and open the **Knowledge** tab. Click **Add category**. If you have no index yet, click **Index a category** on the **Help Center categories** row. The **Index a Help Center category** dialog opens.

2. **Configure the Index**

   Enter the following required information:

   - **Subdomain**: Your Zendesk subdomain only, for example `mycompany` for `https://mycompany.zendesk.com`. For a full URL, the form shows "Enter only the subdomain, such as acme for acme.zendesk.com".
   - **Category ID**: The help center category to index. Find it in the category URL: `https://SUBDOMAIN.zendesk.com/hc/categories/CATEGORY_ID`. Risotto indexes the published articles in that category.
   - **User email**: The email address of the user who generated the API token
   - **API token**: A [vault credential](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) that holds your Zendesk API token
   - **Department** and **Audience**: Choose who gets answers from this index. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

   The index takes the category's name, so the dialog asks for no name.

   *Product example: The Index a Help Center category dialog on the Zendesk integration page: the subdomain, the category ID, the user email, an API token from the vault, Department and Audience, and Index category.*

3. **Create and Monitor Index**

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

**Create index** on [**Knowledge > Indexes**](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#create-an-index) still adds the category as a **Zendesk Guide** index with the same details, plus an **Index name**. It is the only place to set **Profile filters**.

## Content Considerations

- Only **published** articles are indexed — drafts are skipped
- Articles are indexed per help center locale; if your help center is multilingual, each locale's version is indexed separately

## Change the API token

A Zendesk Guide index connects with an API token only. Risotto does not support OAuth for Zendesk Guide. The **Configure** dialog of an index shows only **Audience** and **Department**, so you cannot change the token there.

To use a new token:

1. Generate a new API token in Zendesk.
2. Go to **Settings → Credential Vault**. In the row menu of the credential that the index uses, choose **Rotate Value**, and enter the new token. See [Rotate a value](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault#rotate-a-value).
3. Reindex the index.

If the index does not use a vault credential, delete the index and create it again with the new token.

## Reindexing Content

To pull in article updates:

1. Navigate to [**Knowledge** → **Indexes**](https://dashboard.tryrisotto.com/knowledge/indexes)
2. Find your Zendesk Guide index
3. Click the row's **⋮** menu (**Index actions**), then click **Reindex**

## Troubleshooting

### Connection fails with a 401 error

Confirm the API token belongs to an Admin, or a user whose role includes
**Manage webhooks** — this is the same requirement as the Zendesk ticketing
integration.

### The index has only public articles

Make sure that the API token is still active in Zendesk. If Zendesk deleted or
deactivated the token, the index can finish without an error but keep only the
articles that anyone can see without signing in. Put a new token in the index
(see [Change the API token](#change-the-api-token)), then reindex.

### Articles missing from search results

- Confirm the article is published, not a draft
- Confirm the article is in the category you entered in **Category ID**

### Content Verification

After indexing, use [**Knowledge** → **Playground**](https://dashboard.tryrisotto.com/knowledge/playground) to confirm Risotto can find and reference your indexed articles.

## Related Integrations

- [Zendesk Integration](https://www.tryrisotto.com/docs/integrations/ticketing/zendesk) — two-way ticket sync

Source: https://www.tryrisotto.com/docs/integrations/knowledge/zendesk-guide
