Authorization Type

Carbon uses OAuth 2.0 to connect to Zendesk workspaces.

Authorization Flow

Functionality

Carbon syncs all Published articles under a single Zendesk workspace. Any Draft article won’t be synced. We currently support only having a single Zendesk workspace connected per customer_id.

Configuration

Custom OAuth Credentials

  1. In Admin Center, click the Apps and integrations icon and then in the sidebar, select APIs > Zendesk APIs.

  1. Click the OAuth Clients tab on the Zendesk API page, and then click Add OAuth client on the right side of the OAuth client list.

  1. Complete the following fields to create a client:
  • Client Name - Enter a name for your app. This is the name that users will see when asked to grant access to your application, and when they check the list of third-party apps that have access to their Zendesk. Description - Optional. This is a short description of your app that users will see when asked to grant access to it.
  • Company - Optional. This is the company name that users will see when asked to grant access to your application. The information can help them understand who they’re granting access to.
  • Logo - Optional. This is the logo that users will see when asked to grant access to your application. The image can be a JPG, GIF, or PNG. For best results, upload a square image. It will be resized for the authorization page.
  • Unique Identifier - The field is auto-populated with a reformatted version of the name you entered for your app. You can change it if you want.
  • Redirect URLs - Enter https://api.carbon.ai/integrations/zendesk here. You can also opt to use a custom CNAME record pointing to https://api.carbon.ai. The domain path must still be /integrations/zendesk.

  1. Click Save. After the page refreshes, a new pre-populated Secret field appears on the lower side. This is the client_secret value specified in the OAuth2 spec. Send us the client_secret value over Slack.
  2. Copy the Secret value to your clipboard and save it somewhere safe. Note: The characters may extend past the width of the text box, so make sure to select everything before copying.

  1. Copy the Unique Identifier of the OAuth app and share that value over Slack as well.
  2. In order for us to white-label your OAuth app, you need to request approval first to convert the app from a local OAuth client to global OAuth client. You can follow the instructions here to do so.

Synchronization

Syncs are triggered when end-users add or remove pages via the Zendesk OAuth flow. You can use the resync_file API endpoint to programmatically resync specific Zendesk files.

To sync Zendesk files on a 24-hour schedule (more frequent schedules available upon request), you can use the /update_users endpoint. This endpoint allows organizations to customize syncing settings according to their requirements, with the option to enable syncing for all data sources using the string ‘ALL’. It’s important to note that each request supports up to 100 customer IDs.

Here’s an example illustrating how to automatically enable syncing for updated Zendesk content for specified users:

{
    "customer_ids": ["team@carbon.ai", "sam@openai.com"],
    "auto_sync_enabled_sources": ["ZENDESK"]
}