Pull from Zendesk¶
Zendesk is a service-first customer relationship management (CRM) application. Companies use Zendesk to improve customer relationships by providing support, chat, and community services that span channels.
Important
Zendesk is removing API tokens as an authentication method . Zendesk does not allow new API tokens to be created after October 27, 2026, and deactivates all remaining API tokens on April 30, 2027.
Every Zendesk destination and courier must use an OAuth client credential by April 30, 2027. A destination or courier that still uses an API token (legacy) credential stops working when Zendesk deactivates its API token. Switch each one to an OAuth client credential before that date.
To switch, see Switch from an API token to an OAuth client.
Use the Zendesk Users API to pull customer support histories to Amperity, and then associate them to your customer profiles and transaction histories.
The steps that are required to pull customer support histories to Amperity from Zendesk:
To move a courier that uses an API token to an OAuth client, see Switch from an API token to an OAuth client.
Get details¶
Zendesk requires the following configuration details:
The client ID and client secret of a Zendesk OAuth client, for an OAuth client credential. An API token (legacy) credential uses the email address of the Zendesk API user and an API token instead.
The subdomain for the customer’s Zendesk account. For example: “acme” (in
acme.zendesk.com). Both credential types require the subdomain. When it is empty, an OAuth client credential fails with the message “Subdomain is required for Zendesk OAuth authentication.”
Amperity supports two credential types for Zendesk:
OAuth client authenticates with a Zendesk OAuth client, using a client ID and a client secret. Amperity selects this credential type by default when you add a credential. Use it for every new Zendesk credential.
API token (legacy) authenticates with a Zendesk API token and the email address of the user who created it.
A Zendesk administrator creates the OAuth client in Zendesk Admin Center, under Apps and integrations > APIs > OAuth clients:
Sign in to Zendesk as a dedicated service account user, not as a person. Zendesk attributes every action Amperity takes with the OAuth client to the user who created it, so a client created under a person’s account can stop working later, for example after that person leaves.
Create a new OAuth client, and set its client kind to Confidential. Amperity uses the client credentials grant, which Zendesk allows only for confidential clients. A public client fails.
Leave the redirect URL empty. The client credentials grant does not use one.
Set Allowed scopes to
read users:write, or leave it empty to allow all scopes. Amperity requests both of these scopes, and fails when the OAuth client does not allow them.Copy the client ID and the client secret.
Add courier¶
A courier brings data from an external system to Amperity.
To add a courier
From the Sources page, click Add Courier. The Add Source page opens.
Find, and then click the icon for Zendesk. The Add Courier page opens.
The Credential Type dropdown selects OAuth client by default. Select API token (legacy) only for an API token that already exists in Zendesk.
Enter the name of the courier. For example: “Zendesk”.
From the Credential field, select an existing credential or select Create a new credential.
To add a credential, enter the name of the credential, a description, and the client ID and client secret of the Zendesk OAuth client. Click Save.
Under Settings enter the subdomain for the Zendesk account. For example: “acme” is the subdomain in “acme.zendesk.com”.
Under Select Data, enable Users.
Click Create.
Run courier manually¶
Run the courier again. This time, because the load operations are present and the feeds are configured, the courier will pull data from Zendesk.
To run the courier manually
From the Sources tab, open the menu for the courier with updated load operations that is configured for Zendesk, and then select Run. The Run Courier dialog box opens.
Select the load option, either for a specific time period or all available data. Actual data will be loaded to a domain table because the feed is configured.
Click Run.
This time the notification will return a message similar to:
Completed in 5 minutes 12 seconds
Review feed and domain table¶
After running the Zendesk courier a feed is created automatically with a pre-defined list of fields. You may apply semantic tags to these fields and you may make the domain table available to Stitch, depending on your use cases. A domain table named Zendesk:Users will be added.
The feed and domain table will match the fields defined in the Zendesk Users API :
active
alias
chat_only
created_at
custom_role_id
default_group_id
details
email (assigned the email semantic tag)
external_id
iana_time_zone
id (assigned the pk semantic tag)
last_login_at
locale
locale_id
moderator
name (assigned the full-name semantic tag)
notes
only_private_comments
organization_id
phone (assigned the phone semantic tag)
photo
remote_photo_url
report_csv
restricted_agent
role
role_type
shared
shared_agent
shared_phone_number
signature
suspended
tags
ticket_restriction
time_zone
two_factor_auth_enabled
updated_at
url
user_fields
verified
Add to courier group¶
A courier group is a list of one or more couriers that run as a group. A courier group can act as a constraint on downstream workflows and can run automatically as part of a scheduled workflow.
To add the courier to a courier group
From the Sources tab, click Add Courier Group. This opens the Create Courier Group dialog box.
Enter the name of the courier. For example: “Zendesk”.
Add a cron string to the Schedule field to define a schedule for the orchestration group.
A schedule defines the frequency at which a courier group runs. All couriers in the same courier group run as a unit and all tasks must complete before a downstream process starts. Define a schedule using cron.
Cron syntax specifies the fixed time, date, or interval at which cron runs. Each line represents a job.
30 8 * * *represents “run at 8:30 AM every day” and30 8 * * 0represents “run at 8:30 AM every Sunday”.For example:
┌───────── minute (0 - 59) │ ┌─────────── hour (0 - 23) │ │ ┌───────────── day of the month (1 - 31) │ │ │ ┌────────────── month (1 - 12) │ │ │ │ ┌─────────────── day of the week (0 - 6) (Sunday to Saturday) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ * * * * * command to execute
Amperity validates the cron syntax and shows you the results. You may also use crontab guru to validate cron syntax.
Set Status to Enabled.
Specify a time zone.
A courier group schedule is associated with a time zone. The time zone determines the point at which a courier group’s scheduled start time begins. A time zone should be aligned with the time zone of system from which the data is being pulled.
Use the Use this time zone for file date ranges checkbox to use the selected time zone to look for files. If unchecked, the courier group uses the current time in UTC to look for files to pick up.
Note
The time zone that is chosen for an courier group schedule should consider every downstream business processes that requires the data and also the time zones in which the consumers of that data will operate.
Add at least one courier to the courier group. Select the name of the courier from the Courier dropdown. Click + Add Courier to add more couriers.
Click Add a courier group constraint, and then select a courier group from the dropdown list.
A wait time is a constraint placed on a courier group that defines an extended time window for data to be made available at the source location.
Important
A wait time is not required for a bridge.
A courier group typically runs on an automated schedule that expects customer data to be available at the source location within a defined time window. However, in some cases, the customer data may be delayed and is not made available within that time window.
For each courier group constraint, apply any offsets.
A courier can be configured to look for files within range of time that is older than the scheduled time. The scheduled time is in Coordinated Universal Time (UTC), unless the “Use this time zone for file date ranges” checkbox is enabled for the courier group.
This range is typically 24 hours, but may be configured for longer ranges. For example, it is possible for a data file to be generated with a correct file name and datestamp appended to it, but for that datestamp to represent the previous day because of how an upstream workflow is configured. A wait time helps ensure that the data at the source location is recognized correctly by the courier.
Warning
This range of time may affect couriers in a courier group whether or not they run on a schedule. A manually run courier group may not take its schedule into consideration when determining the date range. Only the provided input days to load data from are used as inputs.
Click Save.
Switch from an API token to an OAuth client¶
Move each Zendesk courier from an API token (legacy) credential to an OAuth client credential before Zendesk deactivates API tokens on April 30, 2027.
To switch a courier to an OAuth client
Create an OAuth client in Zendesk Admin Center, as described in Get details.
From the Sources page, open the menu for the courier that was configured for Zendesk, and then select Edit.
From the Credential Type dropdown, select OAuth client.
From the Credential field, select an existing OAuth client credential, or select Create a new credential and enter the client ID and client secret of the OAuth client.
Under Settings, confirm that the subdomain is set.
Click Save.