Zendesk Support

1. How to connect to Zendesk Support?

You can follow the following steps to build a connection with your Zendesk Support. If you need any helps to set up your integration, please contact us.

1. Go to the Resources page and click the Add Resource button.

2. In the "Select a data source" step, select Zendesk Support under Apps.

3. In the "Configure the data source" step, enter the following information:

  • Start Date: Retrieve data from a specific date and time. The date should be defined in UTC date and time, such as 2017-01-25T00:00:00Z.

  • Email: the email address that is registered for your Zendesk account.

  • API Token: The value of the API token generated. See here to get an API token.

  • Subdomain: The subdomain for your Zendesk Support.

4. In the "Select the tables", choose tables that you want to connect. See here for more details on each table.

5. Click Finish Setup. You will see a icon next to your Zendesk Support resource. It may take a few minutes to several hours depending on the data size and the number of your tables. Once your APP's data is ready, you will receive a notification email.

2. How to generate an API token for Zendesk Support?

Zendesk Support and Zendesk Talk can share the same API token. If you have already generated an API token for Zendesk Talk, then you can use the same one to connect to Zendesk Support.

To connect to your Zendesk account on Acho, you have to enable API token access and generate a token in Zendesk. You must be an administrator and API token access must be enabled. Here are the instructions to do so.

1. Click the Admin icon (img) in the sidebar, then select Channels > API. Or, you can go here directly: https://YourSUBDOMAIN.zendesk.com/agent/admin/api/settings (Remember to change "YourSUBDOMAIN" in the link to your subdomain name)

2. Enable API token access.

3. Click Add API token and find your API tokens as shown below.

4. Click Save.

3. How to set up Data Sync?

Acho supports creating schedulers to retrieve the latest data from your Zendesk Support account at a certain time interval. To see more details, you can visit here.

4. Available Tables

For every third-party App integration, there are many tables that can be imported. Outside of the reference tables, here are some of the most used tables for your analytics.

Tickets

Tickets are the means through which your end-users (customers) communicate with agents in Zendesk Support. Tickets can originate from a number of channels, including email, Help Center, chat, phone call, Twitter, Facebook, or the API.

Name

Type

Description

id

integer

Automatically assigned when the ticket is created

allow_attachments

boolean

Permission for agents to add attachments to a comment. Defaults to true

allow_channelback

boolean

Is false if channelback is disabled, true otherwise. Only applicable for channels framework ticket

assignee_id

integer

The agent currently assigned to the ticket

brand_id

integer

Enterprise only. The id of the brand this ticket is associated with

collaborator_ids

array

The ids of users currently CC'ed on the ticket

collaborators

array

POST requests only. Users to add as cc's when creating a ticket. See Setting Collaborators

created_at

string

When this record was created

custom_fields

array

Custom fields for the ticket. See Setting custom field values

description

string

Read-only first comment on the ticket. When creating a ticket, use comment to set the description. See Description and first comment

due_at

string

If this is a ticket of type "task" it has a due date. Due date format uses ISO 8601 format.

email_cc_ids

array

The ids of agents or end-users currently CC'ed on the ticket. See CCs and followers resources in the Support Help Center

external_id

string

An id you can use to link Zendesk Support tickets to local records

follower_ids

array

The ids of agents currently following the ticket. See CCs and followers resources

followup_ids

array

The ids of the follow-ups that are created from this ticket. Ids are only visible once the ticket is closed

forum_topic_id

integer

The topic in the Zendesk Web portal this ticket originated from, if any. The Web portal is deprecated

group_id

integer

The group that this ticket is assigned to

has_incidents

boolean

Is true if a ticket is a problem type and has one or more incidents linked to it. Otherwise, the value is false.

is_public

boolean

Is true if any comments are public, false otherwise

macro_ids

array

POST requests only. List of macro IDs to be recorded in the ticket audit

organization_id

integer

The organization of the requester. You can only specify the ID of an organization associated with the requester. See Organization Memberships

priority

string

The urgency with which the ticket should be addressed. Allowed values are "urgent", "high", "normal", or "low".

problem_id

integer

For tickets of type "incident", the ID of the problem the incident is linked to

raw_subject

string

The dynamic content placeholder, if present, or the "subject" value, if not. See Dynamic Content

recipient

string

The original recipient e-mail address of the ticket

requester_id

integer

The user who requested this ticket

satisfaction_rating

object

The satisfaction rating of the ticket, if it exists, or the state of satisfaction, "offered" or "unoffered". The value is null for plan types that don't support CSAT

sharing_agreement_ids

array

The ids of the sharing agreements used for this ticket

status

string

The state of the ticket. Allowed values are "new", "open", "pending", "hold", "solved", or "closed".

subject

string

The value of the subject field for this ticket

submitter_id

integer

The user who submitted the ticket. The submitter always becomes the author of the first comment on the ticket

tags

array

The array of tags applied to this ticket

ticket_form_id

integer

Enterprise only. The id of the ticket form to render for the ticket

type

string

The type of this ticket. Allowed values are "problem", "incident", "question", or "task".

updated_at

string

When this record last got updated

url

string

The API URL of this ticket

via

object

For more information, see the Via object reference

via_followup_source_id

integer

POST requests only. The id of a closed ticket when creating a follow-up ticket. See Creating a follow-up ticket

Groups

When support requests arrive in Zendesk Support, they can be assigned to a Group. Groups serve as the core element of the ticket workflow; support agents are organized into Groups and tickets can be assigned to a Group only, or to an assigned agent within a Group. A ticket can never be assigned to an agent without also being assigned to a Group.

Name

Type

Description

id

integer

Automatically assigned when creating groups

created_at

string

The time the group was created

default

boolean

If the group is a default for the account

deleted

boolean

Deleted groups get marked as such

description

string

The description of the group

name

string

The name of the group

updated_at

string

The time of the last update of the group

url

string

The API url of this group

Users

Zendesk Support has three types of users: end users (your customers), agents, and administrators.

  • End users: End users request support through tickets. End users have access to Help Center where they can view knowledge base articles and community content, access their ticket history, and submit new tickets.

  • Agents: Agents work in Zendesk Support to solve tickets. Agents can be divided into multiple groups and can also belong to multiple groups. Agents don't have access to administrative configuration in Zendesk Support such as business rules or automations, but can configure their own macros and views.

  • Administrators: Administrators have all the abilities of agents, plus administrative abilities. Accounts on the Enterprise plan and above can configure custom roles to give agents varying degrees of administrative access.

id

string

The time zone for the use

id

integer

Automatically assigned when the user is created

active

integer

false if the user has been deleted

alias

boolean

An alias displayed to end-users

chat_only

string

Whether or not the user is a chat-only agent

created_at

boolean

The time the user was created

custom_role_id

string

A custom role if the user is an agent on the Enterprise plan or above

default_group_id

integer

The id of the user's default group

details

integer

Any details you want to store about the user, such as an address

email

string

The user's primary email address. The primary email is specified when you create the user. On update, a secondary email is added.

external_id

string

A unique identifier from another system. The API treats the id as case insensitive. Example: "ian1" and "Ian1" are the same users

iana_time_zone

string

The time zone for the user

last_login_at

string

The last time the user signed in to Zendesk Support

locale

string

The user's locale. A BCP-47 compliant tag for the locale.

locale_id

integer

The user's language identifier

moderator

boolean

Designates whether the user has forum moderation capabilities

name

string

The user's name

notes

string

Any notes you want to store about the user

only_private_comments

boolean

true if the user can only create private comments

organization_id

integer

The id of the user's organization. If the user has more than one organization membership, the id of the user's default organization.

phone

string

The user's primary phone number. The phone number follows a format with a country dial prefix, an area code, and a subscriber number. For example, +15551234567.

photo

object

The user's profile picture which is represented as an Attachment object

report_csv

boolean

Whether or not the user can access the CSV report on the Search tab of the Reporting page in the Support admin interface. See Analyzing Help Center search results in Help Center. Only available on the Support Professional or Suite Growth plan or above.

restricted_agent

boolean

If the agent has any restrictions; false for admins and unrestricted agents, true for other agents

role

string

The user's role. Possible values are "end-user", "agent", or "admin"

role_type

integer

The user's role id. 0 for custom agents, 1 for the light agent, 2 for the chat agent, and 3 for the chat agent added to the Support account as a contributor.

shared

boolean

If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only

shared_agent

boolean

If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only

shared_phone_number

boolean

Whether the phone number is shared or not. If true, the phone number can be linked with multiple users. Otherwise, the phone number is only lined with a single user.

signature

string

The user's signature. Only agents and admins can have signatures

suspended

boolean

If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal

tags

array

The user's tags. Only present if your account has user tagging enabled

ticket_restriction

string

Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null

time_zone

string

The user's time zone. A time_zone name consists of a string such as "Eastern Time (US & Canada)".

two_factor_auth_enabled

boolean

If two-factor authentication is enabled

updated_at

string

The time the user was last updated

url

string

The user's API URL

user_fields

object

Values of custom fields in the user's profile.

verified

boolean

Any of the user's identities are verified. See User Identities

Organizations

Just as agents can be segmented into groups in Zendesk Support, your customers (end-users) can be segmented into organizations. You can manually assign customers to an organization or automatically assign them to an organization by their email address domain. Organizations can be used in business rules to route tickets to groups of agents or to send email notifications.

Name

Type

Description

id

integer

Automatically assigned when the organization is created

created_at

string

The time the organization was created

details

string

Any details about the organization, such as the address

domain_names

array

An array of domain names associated with this organization

external_id

string

A unique external id to associate organizations to an external record

group_id

integer

New tickets from users in this organization are automatically put in this group

name

string

A unique name for the organization

notes

string

Any notes you have about the organization

organization_fields

object

Custom fields for this organization

shared_comments

boolean

End users in this organization are able to see each other's comments on tickets

shared_tickets

boolean

End users in this organization are able to see each other's tickets

tags

array

The tags of the organization

updated_at

string

The time of the last update of the organization

url

string

The API URL of this organization

Ticket Audits

Audits are all updates to a ticket. When a ticket is updated in Zendesk Support, an audit is stored. Each audit represents a single update to the ticket.

Name

Type

Description

id

integer

Automatically assigned when creating audits

author_id

integer

The user who created the audit

created_at

string

The time the audit was created

events

array

An array of the events that happened in this audit. See the Ticket Audit events reference

metadata

object

Metadata for the audit, custom, and system data

ticket_id

integer

The ID of the associated ticket

via

object

Describes how the object was created. See the Via object reference

Ticket Comments

Ticket comments represent the conversation between requesters, collaborators, and agents. Comments can be public or private.

Name

Type

Description

id

integer

Automatically assigned when the comment is created

attachments

array

Attachments, if any. See Attachment

author_id

integer

The id of the comment author.

body

string

The comment string

created_at

string

The time the comment was created

html_body

string

The comment formatted as HTML

metadata

object

System information (web client, IP address, etc.) and comment flags, See the details for comment flags.

plain_body

string

The comment as plain text

public

boolean

true if a public comment; false if an internal note. The initial value set on ticket creation persists for any additional comment unless you change it

type

string

Comment or VoiceComment. The JSON object for adding voice comments to tickets is different. See Adding voice comments to tickets

uploads

array

List of tokens received from uploading files for comment attachments. The files are attached by creating or updating tickets with the tokens. See Attaching files in Tickets

via

object

Describes how the object was created. See the Via object reference

Ticket Fields

Ticket fields are used for creating ticket forms where end users provide the subject and description of their question or support issue. There are two types of ticket fields. System ticket fields are the standard, default fields that agents see in a ticket. Custom ticket fields can be created in addition to system ticket fields to gather additional information from the person who is requesting support.

Name

Type

Description

id

integer

Automatically assigned when created

active

boolean

Whether this field is available

agent_description

string

A description of the ticket field that only agents can see

collapsed_for_agents

boolean

If true, the field is shown to agents by default. If false, the field is hidden alongside infrequently used fields. Classic interface only

created_at

string

The time the custom ticket field was created

custom_field_options

array

Required and presented for a custom ticket field of type "multiselect" or "tagger"

description

string

Describes the purpose of the ticket field to users

editable_in_portal

boolean

Whether this field is editable by end users in Help Center

position

integer

The relative position of the ticket field on a ticket. Note that for accounts with ticket forms, positions are controlled by the different forms

raw_description

string

The dynamic content placeholder if present, or the description value if not. See Dynamic Content

raw_title

string

The dynamic content placeholder if present, or the title value if not. See Dynamic Content

raw_title_in_portal

string

The dynamic content placeholder if present, or the "title_in_portal" value if not. See Dynamic Content

regexp_for_validation

string

For "regexp" fields only. The validation pattern for a field value to be deemed valid

removable

boolean

If false, this field is a system field that must be present on all tickets

required

boolean

If true, agents must enter a value in the field to change the ticket status to solved

required_in_portal

boolean

If true, end users must enter a value in the field to create the request

sub_type_id

integer

For system ticket fields of type "priority" and "status". Defaults to 0. A "priority" sub type of 1 removes the "Low" and "Urgent" options. A "status" sub type of 1 adds the "On-Hold" option

system_field_options

array

Presented for a system ticket field of type "tickettype", "priority" or "status"

tag

string

For "checkbox" fields only. A tag added to tickets when the checkbox field is selected

title

string

The title of the ticket field

title_in_portal

string

The title of the ticket field for end users in Help Center

type

string

System or custom field type. Editable for custom field types and only on creation. See Create Ticket Field

updated_at

string

The time the custom ticket field was last updated

url

string

The URL for this resource

visible_in_portal

boolean

Whether this field is visible to end users in Help Center

Ticket Forms

Ticket forms allow an admin to define a subset of ticket fields for display to both agents and end users. Currently, ticket forms are only available on Zendesk Enterprise accounts or Zendesk accounts with the Productivity Pack add-on.

Name

Type

Description

id

integer

Automatically assigned when creating ticket form

active

boolean

If the form is set as active

agent_conditions

array

Array of condition sets for agent workspaces

created_at

string

The time the ticket form was created

default

boolean

Is the form the default form for this account

display_name

string

The name of the form that is displayed to an end user

end_user_conditions

array

Array of condition sets for end user products

end_user_visible

boolean

Is the form visible to the end user

in_all_brands

boolean

Is the form available for use in all brands on this account

name

string

The name of the form

position

integer

The position of this form among other forms in the account, i.e. dropdown

raw_display_name

string

The dynamic content placeholder, if present, or the "display_name" value, if not. See Dynamic Content

raw_name

string

The dynamic content placeholder, if present, or the "name" value, if not. See Dynamic Content

restricted_brand_ids

array

ids of all brands that this ticket form is restricted to

ticket_field_ids

array

ids of all ticket fields which are in this ticket form. The products use the order of the ids to show the field values in the tickets

updated_at

string

The time of the last update of the ticket form

url

string

URL of the ticket form

Ticket Metrics

Returns a specific metric, or the metrics of a specific ticket.

Name

Type

Description

id

integer

Automatically assigned when the client is created

agent_wait_time_in_minutes

object

Number of minutes the agent spent waiting during calendar and business hours

assigned_at

string

When the ticket was assigned

assignee_stations

integer

Number of assignees the ticket had

assignee_updated_at

string

When the assignee last updated the ticket

created_at

string

When the record was created

first_resolution_time_in_minutes

object

Number of minutes to the first resolution time during calendar and business hours

full_resolution_time_in_minutes

object

Number of minutes to the full resolution during calendar and business hours

group_stations

integer

Number of groups the ticket passed through

initially_assigned_at

string

When the ticket was initially assigned

latest_comment_added_at

string

When the latest comment was added

on_hold_time_in_minutes

object

Number of minutes on hold

reopens

integer

Total number of times the ticket was reopened

replies

integer

The number of public replies added to a ticket by an agent

reply_time_in_minutes

object

Number of minutes to the first reply during calendar and business hours

requester_updated_at

string

When the requester last updated the ticket

requester_wait_time_in_minutes

object

Number of minutes the requester spent waiting during calendar and business hours

solved_at

string

When the ticket was solved

status_updated_at

string

When the status of the ticket was last updated

ticket_id

integer

Id of the associated ticket

updated_at

string

When the record was last updated

url

string

The API url of the ticket metric

Group Memberships

A membership links an agent to a group. Groups can have many agents, as agents can be in many groups.

Name

Type

Description

id

integer

Automatically assigned upon creation

created_at

string

The time the group was created

default

boolean

If true, tickets assigned directly to the agent will assume this membership's group

group_id

integer

The id of a group

updated_at

string

The time of the last update of the group

url

string

The API url of this record

user_id

integer

The id of an agent

Macros

A macro consists of one or more actions that modify the values of a ticket's fields. Macros are applied to tickets manually by agents. For example, you can create macros for support requests that agents can answer with a single, standard response.

Name

Type

Description

id

integer

The ID automatically assigned when a macro is created

actions

array

Each action describes what the macro will do. See Actions reference

active

boolean

Useful for determining if the macro should be displayed

created_at

string

The time the macro was created

description

string

The description of the macro

position

integer

The position of the macro

restriction

object

Access to this macro. A null value allows unrestricted access for all users in the account

title

string

The title of the macro

updated_at

string

The time of the last update of the macro

url

string

A URL to access the macro's details

Satisfaction Ratings

If you have enabled satisfaction ratings for your account, this end point allows you to quickly retrieve all ratings.

Name

Type

Description

id

integer

Automatically assigned upon creation

assignee_id

integer

The id of agent assigned to at the time of rating

comment

string

The comment received with this rating, if available

created_at

string

The time the satisfaction rating got created

group_id

integer

The id of group assigned to at the time of rating

reason

string

The reason for a bad rating given by the requester in a follow-up question. Satisfaction reasons must be enabled

reason_code

integer

The default reasons the user can select from a list menu for giving a negative rating. See Reason codes in the Satisfaction Reasons API. Can only be set on ratings with a score of "bad".

requester_id

integer

The id of ticket requester submitting the rating

score

string

The rating "offered", "unoffered", "good" or "bad"

ticket_id

integer

The id of ticket being rated

updated_at

string

The time the satisfaction rating got updated

url

string

The API url of this rating

Tags

You must enable the tagging of users and organizations in Zendesk Support for the API calls to work. In Support, click the Admin icon in the sidebar, select Settings > Customers, and enable the option.

Name

Type

Description

tags

array

An array of strings

SLA Policies

A Service Level Agreement (SLA) is a documented agreement between a support provider and their customers that specifies performance measures for support. There can be multiple SLA policies per Zendesk Support account.

Name

Type

Description

id

integer

Automatically assigned when created

created_at

string

The time the SLA policy was created

description

string

The description of the SLA policy

filter

object

An object that describes the conditions that a ticket must match in order for an SLA policy to be applied to that ticket. See Filter.

policy_metrics

array

Array of Policy Metric objects

position

integer

Position of the SLA policy that determines the order they will be matched. If not specified, the SLA policy is added as the last position

title

string

The title of the SLA policy

updated_at

string

The time of the last update of the SLA policy

url

string

URL of the SLA Policy reacord