Zendesk app installation guide

This document provides instructions on the installation of the Zendesk application with CCAI Platform.

Prerequisites

  • Have access as an administrator to the CCAI Platform portal.

  • Have a Zendesk account on the Professional or Enterprise plan.

  • Have downloaded the Zendesk app files:

Get started

Zendesk apps are private. They are not listed on the public Zendesk App Marketplace. You can contact your Zendesk representative to obtain and install them to your Zendesk account.

Installation

Follow the instructions below to refer to the Zendesk apps site Uploading and installing your private app in Zendesk.

Uploading and installing a private app in Zendesk Support

  1. Click Settings to go to Admin Center.

  2. Select Apps and Integrations > Zendesk Support App > Private App.

  3. Click Upload Private App.

  4. Enter a Name for the app. Example: (Call V1.4) (Chat V1.3)

  5. Click Choose file and select the zip file for your private app (ujet-zendesk-call-v1.4.zip or ujet-zendesk-chat-v1.3.zip).

  6. Click Upload.

  7. In the window that appears, click Agree and upload this App.

  8. Input your account subdomain.

  9. When prompted, click Install.

When the process is complete, your private app appears in the list of installed apps on the Manage Apps page.

Repeat steps if both the Call and Chat app need to be installed.

The following configuration items need to be set:

  • App Name: It is recommended that you use Call and Chat.

  • App Configurations

    • Subdomain: Enter the subdomain of your account. For example: Instance, ie., instance.uc1.ccaiplatform.com.

    • Domain Name: Leave it as the default value example.com.

Manage apps

Applications can be managed through the Zendesk portal.

Changing app settings

You can change the installed app settings, or update apps by using the following link from Zendesk: Managing your installed apps.

Change the settings for an app, including the title:

  1. On the My Apps > Currently Installed page, find the app you want to change.

  2. Click the options menu on the app where you want to change settings, then select Change settings.

  3. Make the changes you want and click Update. Your changes are saved.

You can also update apps:

  1. On the My Apps > Private App page, find the app you want to update.

  2. Click the Options menu, then select Update.

  3. Upload your updated zip file.

 Setting up an OAuth client

Zendesk apps use OAuth 2.0 to authenticate API requests to Zendesk. You should set up an OAuth Client for Zendesk Apps.

Follow these instructions or refer to the following link from Zendesk: Using OAuth authentication with your application.

Registering your Application

  1. In the Zendesk Support Admin Center, click Apps and Integrations > Zendesk API.

  2. Click the OAuth Clients tab on the Channels/API page, and then click Add OAuth Client by the client list.

  3. 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.

    • Redirect URLs: Enter the URL or URLs that Zendesk should use to send the user's decision to grant access to your application. The URLs must be absolute and not relative, https (unless localhost or 127.0.0.1), and newline-separated.

  4. Click Save.

    After the page refreshes, a new pre-populated Secret field appears. This is the "client_secret" value specified in the OAuth2 spec.

  5. Copy the Secret value to your clipboard and save it somewhere safe.

Redirect URLs

Set the Redirect URLs of the OAuth client as follows,

https://INSTANCE.ccaiplatform.com/v1/zendesk/oauth_callback

You should replace INSTANCE with the actual subdomain of your CCAI Platform.

Unique Identifier and Secret

The Unique Identifier and Secret fields are auto-populated while adding a new OAuth client. These are the client_id and client_secret values in the OAuth2 spec.

You can edit the Unique Identifier if you want, but not the Secret.

The Secret is displayed fully only once while adding a new client. Ensure this is kept safe.

Configure application settings

This section outlines the specific application settings.

Configuring OAuth

  1. Sign in to the CCAI Platform portal as an administrator user.

  2. Go to Settings > Developer Settings.

  3. Select Agent Platform Zendesk in CRM section.

  4. Set Zendesk Subdomain to the subdomain of your Zendesk account.

    https://your_zendesk_subdomain.zendesk.com

  5. Set OAuth Client ID to the Unique Identifier of your Zendesk OAuth client.

  6. Set OAuth Client Secret to the Secret of your Zendesk OAuth client.

  7. Click Save.

 Generate an API Token**

The following steps enable you to generate an API token in Zendesk:

  1. In Zendesk Support Admin Center, click Apps and Integrations > Zendesk API.

  2. Click the Settings tab, and make sure Token Access is enabled.

  3. Click the Add API Token button to the right of Active API Tokens.

  4. Optionally, enter a description under API Token Description. The token is generated, and displayed for you:

    token display

  5. Copy the token, and paste it somewhere secure.

  1. Click Save to return to the API page. A truncated version of the token is displayed.

Configure API token

The follow sections provide guidance on configuring the Zendesk API token.

Assigning the API Token in the Admin settings

  1. Sign in to the CCAI Platform portal with an administrator account, and go to Settings > Developer Settings.

  2. Set API Token to the API token copied from your Zendesk client.

Create customer and ticket fields

The application creates custom fields and fills the value. We need to create an account which has both administrator and agent roles.

  1. In the CCAI Platform portal, go to Settings > Agent & Manager Team.

  2. Select Add an admin.

  3. Check This admin is also an agent.

  4. Activate the account from invitation email.

  5. Sign out of the current administrator account and sign in with the new account.

  6. Sign in to Zendesk with Admin role (not an Agent role).

  7. In Zendesk, sign in using the widget with credential which is an administrator with agent role.

  8. Click Authorize.

  9. In the CCAI Platform portal, go to Settings > Developer Settings.

  10. Navigate to the CRM > Customer fields for Contact and Ticket section.

  11. Click Create.

  12. Check if custom ticket fields were created from Zendesk by referring to:

    • Admin > Manage > User Fields

    • Admin > Manage > Ticket Fields

Fields

  • User Fields

    • Identifier

  • Ticket Fields

    • Verification (Checkbox)

    • Customer Text Feedback (Multi-line text)

    • Customer Satisfaction Rating (Numeric): 1 to 5

    • Shared Customer Rating (Text): Twitter or Facebook

Domain-based Access Control

Refer to Domain-based Access Control for steps to limit platform access based on the domain and details related to CRM-specific domains.