Zendesk

 

Admin Configuration

An Organization-level connection must first be made between Zendesk and Tellescope. Then, individual users connect their Zendesk accounts to their Tellescope account via OAuth (described below).

The one-time admin setup can be done by navigating to the Integrations page in Tellescope, and clicking the Zendesk Admin card

This will require the following information:

• subdomain is the start of your Zendesk URL. For example, if your Zendesk is hosted at https://tellescope.zendesk.com, then your subdomain would be tellescope

• clientId is the Unique Identifier for your OAuth Client (see OAuth below)

• clientSecret is the Secret value for your OAuth Client (see OAuth below)

• adminAPIKey is an API key that you generate while logged in to Zendesk as an admin

• apiKeyEmail is the admin email of the account login that is used to generate the API key

  API Keys

  We need an admin-level API key, so that we can load data from Zendesk when we receive a webhook, without being restricted by the access level of a particular user

  In the Zendesk API page, Enable Token access, Add API token, and save the result so that you can include it in the Zendesk/Tellescope Admin Configuration

  Making “Tellescope” the description for this API key is recommended

  

OAuth

OAuth allows each Tellescope user to connect their individual ZenDesk account, so that integrated tickets can be managed on a more personalized per-user level

OAuth Client Setup

In the Zendesk Admin Center, navigate to Apps and integrations > APIs > OAuth Clients

or if on an older version of the Zendesk UI, you may see Zendesk API (see below)

You may need to first opt in to their terms of service

Select the OAuth Clients tab, and click Add OAuth client

Fill out Client name, Description, Company, and Logo (if desired)

For Client Kind, make sure it is Confidential

For Redirect URls, enter the following

https://api.tellescope.com/v1/zendesk-oauth2-verify

Then click Save to continue

 💡 You will be shown a Secret value. Be sure to save this somewhere safe to include in the Zendesk Admin configuration as the clientSecret. You will also need to include this value when configuration webhooks.

You should also see a Unique Identifier which will be included as the clientId to finish the Admin Tellescope/Zendesk connection.

Webhooks

✋🏼 Have you finished configuring the Admin Zendesk/Tellescope connection in the Integrations page of Tellescope? Wait to configure Webhooks until that process is complete. Otherwise, Webhooks will not work. Once Webhooks are enabled, tickets corresponding to existing patients in Tellescope will start to sync.

In the same Admin Center, go to Webhooks and Create webhook

Choose Trigger or automation

Enter the following details

Name: Tellescope

Description: (optional)

Endpoint URL: https://api.tellescope.com/v1/webhooks/zendesk

Request method: POST

Request format: JSON

Authentication

• API Key
  • Header name: apikey
  • Value: Use the same Secret value from your OAuth setup

During the connect webhook step, follow the instructions by going to Triggers in the Admin Center

Click + Add trigger at the bottom

Enter the following details

Trigger name: Tellescope

Description: blank

Category: Notifications

Conditions

For Actions, Notify by > Active webhook, selecting the Tellescope webhook that has been set up

Use the following for the JSON body

{
	"id": "{{ticket.id}}",
	"email": "{{ticket.requester.email}}",
	"phone": "{{ticket.requester.phone}}",
	"groupName": "{{ticket.group.name}}"
}

Click Save

Priority Groups

Some groups (e.g. Care Navigation) may need to sync tickets from Zendesk, while other tickets are not necessary to sync to Tellescope. To specify such groups, press Edit Settings on the Zendesk Admin configuration in Tellescope, enter the relevant groups into the menu, and then saving.

Resolution Field

Many teams set up a custom field in Zendesk to be completed before marking a ticket as Solved. To support this flow, Tellescope needs to be configured accordingly. Like Priority Groups, this can be set up by clicking Edit Settings on the Zendesk Admin configuration in Tellescope.

The Field ID value can be found in the Zendesk Admin Center under

• Objects and rules > Tickets > Fields

 💡 The Field ID value is unique for every Zendesk account (e.g. Sandbox vs. Production), even if the name is the same. If updating a connected Zendesk instance, make sure to update the Field ID value accordingly

Resolution options should be populated with relevant values that can be saved for this custom resolution field.

 💡 If the custom field is a Drop-down type, the Tag value should be used as a Resolution Option in Tellescope, not the Value itself. These are visible by clicking into the custom field and viewing the configured options.