Zendesk Support Integration

Last modified on 2022/10/27 17:52
Contents

SM_IntegrationIntroduction_OnlyEN

You can integrate third-party systems with Service Manager in many ways. The method you select will depend on business requirements, architectural and security constraints as well as the characteristics specific to each third-party application or service.

This document describes an integration process that has already been implemented in a customer context. 

To find out more about this integration (e.g. scripts to be used), please do not hesitate to contact your EasyVista contact, or your service provider and integrator.

Integration Summary

This integration is used to retrieve all available information from your Zendesk domain using the Zendesk REST API (GET method).

example   Retrieve and display a list of open tickets in an Service Apps app

Integration Data Feed (direction) Authentication Type Integration Connector Options

Favicon EasyVista - 32.png Service Apps

Up arrow.png

Logo - ZenDesk.png

Check icon.png   Personal API Key/Token Access Authentication

REST data source   Apps - Datasource - JSON Online icon.png

SaaS Version of Third-Party Product

On-premise Version of Third-Party Product

Check icon.png

Not check icon.png

example    https://{subdomain}.Zendesk.com  ==> replace {subdomain} with the name of your Zendesk domain

API detailed description

Item Comments
About the software and company

Logo - ZenDesk.png

Zendesk, Inc. is a software development company based in San Francisco, California. The company provides a cloud-based customer service platform, also called Zendesk, that includes ticketing, self-service options, and customer support features.
Information about the REST API

Date on which the information was retrieved from the software company's website: January 2016

Last known REST API name/version/date: Core API V2
Main useful links to software company information about REST

Zendesk REST API Introduction

Zendesk Help Center

Zendesk Restrictions and Responsibilities
Format and sample of API resources/endpoints

https://{subdomain}.freshdesk.com/helpdesk/tickets.json

Notes:
  • When documenting a resource, Freshdesk uses curly brackets { } for identifiers.
  • Replace {subdomain} in the URI with your subdomain name provided by Zendesk.
API assets

N/A
API recommendations (limitations, advice, tips)
  • API calls: This API is rate limited. Only a certain number of requests per minute are allowed. Zendesk reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients. As an API consumer, you should expect to be able to make at least 200 requests per minute.
  • Pagination: By default, most list endpoints return a maximum of 100 records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request URL parameters. However, you cannot exceed 100 records per page for most endpoints.
    example    per_page=50  

    When the response exceeds the per-page maximum, you can paginate through the records by incrementing the page parameter. List results include next_page and previous_page URLs in the response body for easier navigation.

    example    page=3  
  • Only administrators can make API requests successfully with Zendesk Personal API Key/Token Access Authentication.
Comments
  • In order to use and access the Zendesk API (using the Personal API Key/Token Access Authentication mechanism enabled by Zendesk), you must obtain API credentials (a token) by subscribing to the service. You must not share this token and keep this token and all login information secure.

Step-by-step integration process

Zendesk can be integrated with Service Apps in 4 easy steps:


Step 1: Check the list of prerequisites

  • This documentation assumes that you already have a Zendesk domain.
  • You need an active Zendesk user account and you must be a verified user to make API requests.
  • To use the Zendesk Personal API Key/Token Access Authentication (preferable to Basic Authentication), you must enable it in the Admin console of your Zendesk domain. You must generate or add at least one token. The token will be required in the data sources you create in an Service Apps app.
    Open url.png See the procedure
    How to enable the Zendesk Personal API Key

    Open url.png To find out more, see the Zendesk REST API Security and Authentication help page

    1. In the Zendesk Admin interface, select Admin > Channels > API. Then click Enabled in the Token Access settings.

    2. Click [ ADD NEW TOKEN ]. Enter a label and click [ CREATE ].

    3. Click [ SAVE ].

    Prerequisites - Channels API.png
  • There are three types of Zendesk users: end-users (your customers), agents, and administrators.
  • You must be an administrator to be able to access the Zendesk Admin interface and view, add, or delete tokens.
  • Only administrators can make API requests successfully with Zendesk Personal API Key/Token Access Authentication.


Step 2: Start the process for creating the REST data source

   Open url.png  For details about the creation, see the wiki page REST data source

  • Click Apps - Add datasource icon.png in the Objects pane. 
  • Open the Online category and select the REST data source Apps - Datasource - JSON Online icon.png.
  • Name the data source.

example   Zendesk_List of Open Tickets


Step 3: Authenticate to Zendesk

Authenticate to Zendesk with the Zendesk Personal API Key/Token Access Authentication

  • Select the type of authentication: Authentication Type = Basic.
  • Click Apps - Edit icon.png next to the Basic Authentication Parameters field. 
  • Enter the User Name using the following format: firstname.lastname@company.com/token. Enter the Password.
             Basic Access Authentication via Token.png
    • The user name is the Zendesk account/login you want to use for this data source. Remember to enter the text, /token, after your account name.
    • The password is the token you obtained by selecting Admin > Channels > API.
    • Once you validate, the *** symbols will appear in the field.


Step 4: Create a query string using Zendesk documentation

         Open url.png See the Zendesk API documentation
        Open url.png See Examples of use cases

  • Create a query string as a data source, i.e. a resource to access, in the URL field.

example   You want to create a data source that will retrieve a list of open tickets  ==>  Enter the following text in the URL field. Note: Replace {subdomain} with the name of your Zendesk domain.

https://{subdomain}.Zendesk.com/api/v2/search.json?query=type:ticket+status:open

Note: Zendesk tickets include the following sub-types: Question, Incident, Problem, Task

Best Practice

        Open url.png  See Best Practice for the REST data source

  • By default, most Zendesk list endpoints return a maximum of 100 records per page. Therefore, to keep the number of records as low as possible, we recommend that you define as many parameters as possible. These parameters can include the status (authorized values: new, open, pending, hold, solved or closed), type (authorized values: problem, incident, question or tasks), due_at (for tasks), etc.
  • You must not share the Personal API Key/Token Access Authentication. You must keep this token and all information on credentials secure.

Samples of most relevant use cases and resources

Note: Replace {subdomain} in the URI with your subdomain name provided by Zendesk.

Method: GET

Use Case Sample Endpoint
Retrieve the list of users

  • for the domain

Authentication Type: Personal API Key/Token Access Authentication
Basic Authentication Parameters: User Name: {email_address}/Token

Password: {Token}
URI: https://{subdomain}.zendesk.com/api/v2/users.json
Selector: N/A
Retrieve a list of all tickets

  • sorted chronologically by creation date
  • from oldest to newest

Authentication Type: Personal API Key/Token Access Authentication
Basic Authentication Parameters: User Name: {email_address}/Token

Password: {Token}
URI: https://{subdomain}.zendesk.com/api/v2/tickets.json
Selector: N/A
Retrieve a list of all open tickets

  • sorted chronologically by creation date
  • from oldest to newest

Authentication Type: Personal API Key/Token Access Authentication
Basic Authentication Parameters: User Name: {email_address}/Token

Password: {Token}
URI: https://{subdomain}.zendesk.com/api/v2/search.json?query=type:ticket+status:open
Selector: N/A
Retrieve information on the currently authenticated user

(e.g. first and last name)

Authentication Type: Personal API Key/Token Access Authentication
Basic Authentication Parameters: User Name: {email_address}/Token

Password: {Token}
URI: https://{subdomain}.zendesk.com/api/v2/users/me.json
Selector: N/A
SAS_IntegrationRESTAboutTheUse_OnlyEN

About the use of the software companies API REST

Note: The possible cost of the use of the third-parties API REST via Service Apps is not taken care by EasyVista.

  • Numerous software companies limit the access to the API REST of their software, generally by basing itself on a number of calls by hour/day/month.
  • Only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
  • Some software companies set up plans, e.g., Classic, Professional, Enterprise, for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.
Tags:
Powered by XWiki © EasyVista 2022