Connect a Zendesk data source

After you set up authentication and store your credentials in an AWS Secrets Manager secret, create the Zendesk data source in your knowledge base. This page describes how to create the data source with the AWS Management Console or the API, followed by a reference for the connector parameters you can configure.

Note

Complete authentication setup first. See Set up OAuth 2.0 Client Credentials authentication for Zendesk. You need the secret ARN.

Create the data source

Console

To connect Zendesk to your managed knowledge base

1. Open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/. In the navigation pane, choose Knowledge Bases and open your managed knowledge base.

2. Under Data source, provide a name for your data source.

3. From the Data source type list, select Zendesk.

4. For Zendesk host URL, enter your Zendesk subdomain URL (for example, https://yoursubdomain.zendesk.com). For multi-brand instances, provide the subdomain for the specific brand that you want to sync.

5. Under Authentication, the connector uses OAuth 2.0. Select or create an AWS Secrets Manager secret containing your clientId, clientSecret, and instanceUrl.

6. Under Sync scope, select the content to crawl:

   • Articles (includes attachments) – Crawls help center articles and their attachments.

   • Community posts – Crawls community posts.

7. (Optional) Under Article filters, enter a category or section ID to limit synced articles. All articles sync by default.

8. (Optional) Under Community posts filter by topics, enter topic IDs to sync posts from specific topics only. All community posts sync by default.

9. (Optional) Under Label name filter, enter labels to sync only articles and community posts that match specific labels. Use this filter alongside the article and topic filters to further refine synced content.

API

To create a Zendesk data source, send a CreateDataSource request with an Agents for Amazon Bedrock build-time endpoint. The following AWS Command Line Interface example creates a Zendesk data source. For a description of each field, see the connector parameters reference that follows.

aws bedrock-agent create-data-source \
 --name "Zendesk-connector" \
 --knowledge-base-id "your-knowledge-base-id" \
 --data-source-configuration file://zendesk-managed-connector.json

The zendesk-managed-connector.json file contains the following:

{
    "type": "MANAGED_KNOWLEDGE_BASE_CONNECTOR",
    "managedKnowledgeBaseConnectorConfiguration": {
        "connectorParameters": {
            "type": "ZENDESK",
            "connectorType": "ZENDESK",
            "version": "1",
            "connectionConfiguration": {
                "secretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:bedrock-zendesk-creds",
                "authType": "OAUTH2",
                "hostUrl": "https://yoursubdomain.zendesk.com"
            },
            "dataEntityConfiguration": {
                "crawlArticles": true,
                "crawlArticleAttachments": true,
                "crawlCommunityPosts": true
            },
            "filterConfiguration": {
                "maxFileSizeInMegaBytes": "10240",
                "articleFilter": {
                    "inclusionCategoryIds": ["category-id"],
                    "inclusionSectionIds": ["section-id"]
                },
                "communityPostFilter": {
                    "inclusionTopicIds": ["topic-id"]
                }
            }
        }
    }
}

The dataEntityConfiguration fields control which entities the connector crawls. The filterConfiguration field is optional; use it to scope the crawl to specific article categories or sections, community topics, or labels, and to set a maximum file size. Without filters, the connector crawls all articles and community posts.

For managed knowledge bases, CreateDataSource is asynchronous: the data source status transitions from CREATING to AVAILABLE when the operation completes.

Connector parameters

The data source configuration uses the following connector parameters. Within connectorParameters, set both type and connectorType to ZENDESK and set version to 1. For the fields that wrap connectorParameters (such as deletionProtectionConfiguration and mediaExtractionConfiguration), see Connect a data source.

The following table describes the connectionConfiguration fields.

connectionConfiguration

Field	Required	Description
secretArn	Yes	The ARN of the AWS Secrets Manager secret containing your clientId, clientSecret, and instanceUrl.
hostUrl	Yes	Your Zendesk host URL (for example, https://yoursubdomain.zendesk.com). For multi-brand instances, use the subdomain for the specific brand. This value must match the instanceUrl in the secret.
authType	Yes	The authentication type. Zendesk supports OAUTH2. See Authentication method.

The following table describes the dataEntityConfiguration fields, which control the entities that the connector crawls. In the console, articles and their attachments are combined into a single Articles (includes attachments) option, but the API exposes them as separate fields.

dataEntityConfiguration

Field	Required	Description
crawlArticles	Yes	Whether to crawl help center articles.
crawlArticleAttachments	Yes	Whether to crawl attachments on help center articles.
crawlCommunityPosts	Yes	Whether to crawl community posts.

The following table describes the optional filterConfiguration fields, which scope the crawl.

filterConfiguration (optional)

Field	Required	Description
articleFilter	No	Scopes article crawling. Contains inclusionCategoryIds (a list of help center category IDs) and inclusionSectionIds (a list of section IDs). These IDs are numeric and appear in the help center URL when you view a category or section (for example, the category ID in https://yoursubdomain.zendesk.com/hc/en-us/categories/200420805 is 200420805).
communityPostFilter	No	Scopes community post crawling. Contains inclusionTopicIds (a list of community topic IDs). A topic ID is numeric and appears in the URL when you view a community topic (for example, the topic ID in https://yoursubdomain.zendesk.com/hc/en-us/community/topics/360001234567 is 360001234567).
inclusionLabelNames	No	A list of label names. The connector syncs only articles and community posts that match these labels. Labels are keywords or tags applied to articles and community posts, found at the bottom of any article or post in the editor. For example, if an article is tagged billing and a community post is tagged FAQ, entering those labels syncs only content matching those tags. Use alongside the article and community post filters to further refine synced content.
maxFileSizeInMegaBytes	No	Maximum size, in megabytes, of any single file the connector ingests. Provide as a numeric string (for example, "10240").

Next steps

After you create the data source, sync it to ingest content into your knowledge base. For details, see Sync a data source. Because Zendesk doesn't support document-level access control, all authenticated users who can query the knowledge base can see all crawled content.