​
Authorization Type

Carbon uses OAuth 2.0 to connect to Zendesk workspaces.

​
Authorization Flow

​
Functionality

The integrations/oauth_url and integrations/connect endpoints sync articles by default.

To customize the sync behavior, use the file_sync_config parameter:

"file_sync_config": {
  "auto_synced_source_types": ["TICKET"],
  "sync_attachments": true
}
  • auto_synced_source_types: An array specifying the types of items to sync. Valid values are “ARTICLE” (default) and “TICKET”. To sync both articles and tickets, include both values in the array.
  • sync_attachments: A boolean indicating whether to sync attachments from ticket comments. Set to true to enable attachment syncing.

​
Additional Endpoints

The following endpoints can be used with Zendesk to list and sync items:

  • integrations/items/sync: Sync items from Zendesk
  • integrations/items/list: List items from Zendesk
  • integrations/files/sync: Sync files from Zendesk

​
Articles

Carbon can sync Published articles from multiple Zendesk workspaces. Note that Draft articles will not be synced.

​
Tickets

Carbon can sync tickets and their associated file attachments. The following ticket information is available as tags for filtering:

{
  "ticket_type": "incident",
  "ticket_status": "open",
  "ticket_assignee": "swapnil+zen1@carbon.ai",
  "ticket_priority": "normal",
  "ticket_requester": "customer@example.com",
  "ticket_submitter": "swapnil+zen1@carbon.ai"
}

Use these tags to filter and organize synced tickets based on their properties.

​
Configuration

​
Custom OAuth Credentials

Custom OAuth credentials is only required for customers who enable white labeling.
  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. Set the Client kind to Confidential.

6. 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"]
}
IntercomFreshdesk