Zoho Desk

Overview

This integration is dedicated to importing Tickets from your Zohodesk portal into Birdie. Below are key details about what we need to set up the integration and how tickets and data are imported.

Requirements

Access and Refresh Tokens

Birdie's integration with the Zoho Desk API requires a Refresh Token that can be acquired by following the necessary authentication steps. Zoho Desk's APIs use the industry-standard OAuth 2.0 protocol for authentication and authorization. This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. For more information, see the documentation.

There are 2 types of tokens:

• Access Token: provides secure and temporary access to Zoho Desk APIs and is used by the applications to make requests to the connected app. Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.

• Refresh Token: A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.

Setup in Zoho Desk

This means that in order for Birdie to be able to access your data automatically, we need a Refresh Token and the process to generate one is:

1

Register your Application

At Zoho API Console, choose Server based client and enter the following details:

• Client Name: The name of your application you want to register with Zoho. We suggest using “Birdie App” for easy identification.

Zoho API Console: Applications page

Zoho API Console: Add Client pop-up options

• Homepage URL: The URL of your web page. It doesn’t necessarily need to be one of your company’s domain, so we suggest using ours:

https://birdie.ai

• Authorized Redirect URIs: A valid URL to which Zoho Accounts redirects you with a grant token (code) after successful authentication. We suggest using:

https://birdie.ai/success

Zoho API Console: Client set up options

Zoho API Console: Client information

Note: The Redirect URI is used during the OAuth 2.0 authorization process to securely redirect the user back to your application after authorization. It is a standard part of the flow, even if your application does not actively process the redirected request.

Since your application does not need to actively process the authorization code, you do not need to implement a functional route at the Redirect URI. However, you must specify one that you or Birdie controls. For security and consistency, we recommend using a Redirect URI hosted on our domain but that might not be approved by your security team. If needed, you can use the following template to build your own route:

https://{your_domain}.com/oauth/callback

Nonetheless, make sure the Redirect URI is:

• Consistent — the URI used in your code must match the one registered in the Zoho API Console.

• Secure — use HTTPS to ensure data is transmitted securely.

2

Making the Authorization Request

Server-based applications are chosen when your application is used by multiple users and requires user intervention during authorization. In this authorization flow, obtain an authorization grant by invoking the authorization URI:

https://accounts.zoho.com/oauth/v2/auth?scope=Desk.search.READ,Desk.tickets.ALL,Desk.contacts.ALL&client_id={1000.XXXXXXXXXXXXXXXXXXXX}&response_type=code&access_type=offline&redirect_uri={Authorized_Redirect_URI}&prompt=consent

Make sure to replace {1000.XXXXXXXXXXXXXXXXXXXX} and {Authorized_Redirect_URI} with the appropriate values. E.g. the value of Client ID and Authorized Redirect URIs in the above images.

After you invoke the Authorization URI, a "user-consent" page opens.

Zoho Desk: Authorization request

When the user clicks Accept, the application gets authorized and a grant token is sent as a parameter in the redirect_uri. E.g.:

https://birdie.ai/?code={1000.XXXXXXXXXXXXXXXXXXXX}&location=us&accounts-server=https%3A%2F%2Faccounts.zoho.com

Birdie: Redirect page

Note: You need to securely store the code 1000.YYYYYYYYYYYYYYYYYYYY from the redirect URL. This code is valid for 60 seconds and you need to use it within this timeframe in order to change it to an Access Token.

3

Switch Authorization Code for an Access Token

Now you need to make an HTTP request using your preferred method. We use curl as an example:

curl -X POST https://accounts.zoho.com/oauth/v2/token \
  -d "grant_type=authorization_code" \
  -d "client_id={Client ID}" \
  -d "client_secret={Client Secret}" \
  -d "redirect_uri={Authorized Redirect URI}" \
  -d "code={1000.YYYYYYYYYYYYYYYYYYYY}"

Note:

Make sure to replace {Client ID}, {Client Secret}, {Authorized Redirect URI} and {1000.YYYYYYYYYYYYYYYYYYYY} with the appropriate values. E.g. the values of Client ID, Client Secret, and Authorized Redirect URIs in the images from Step 1 and the Authorization Code you saved from Step 2.

Which will generate a response following the template:

{
  "access_token": "1000.xxxxxxxx",
  "refresh_token": "1000.yyyyyyyy",
  "api_domain": "https://desk.zoho.com",
  "token_type": "Bearer",
  "expires_in": 3600
}

Note: You need to securely store the Refresh Token (1000.yyyyyyyy) from the response. This is the token Birdie will use to connect with your Zoho Desk Portal.

Share Connection Details with Birdie

After completing the OAuth flow above, securely provide Birdie with the following information:

{
  "connection_details": {
    "client_id": "1000.XXXXXXXXXXXXXXXXXXXX",
    "client_secret": "your-client-secret",
    "refresh_token": "1000.yyyyyyyy"
  }
}

Section	Field	Required	Description
connection_details	client_id	Yes	OAuth Client ID from Step 1 (Zoho API Console).
connection_details	client_secret	Yes	OAuth Client Secret from Step 1 (Zoho API Console).
connection_details	refresh_token	Yes	OAuth Refresh Token obtained in Step 3.

Share credentials securely with the Birdie team. Never send credentials via email or unencrypted channels.

Data in scope

Ticket import process and update frequency

Birdie imports Zoho Desk's Tickets by checking for new data through the modifiedTime field, ensuring that the latest modifications are reflected in our application. This method enables Birdie to capture only the most recent changes without re-importing old data.

Custom fields

Zoho Desk allows you to store additional, flexible data within tickets beyond standard fields, accommodating various data types. If your Zoho Desk setup includes custom fields for tickets, these fields can be mapped directly into Birdie, preserving your unique data structure.

Once imported, Zoho Desk's custom fields appear as Birdie custom fields, maintaining consistency across both platforms. Mapped to Birdie’s data structure, these fields enhance data organization and filtering, supporting extended segmentation within Birdie’s interface. This allows for customized workflows and data displays based on the unique attributes of each ticket.