Freshdesk is a customer support platform from Freshworks. Support teams use it to manage tickets from multiple channels, maintain a knowledge base, and measure customer satisfaction.
Hevo uses the Freshdesk API to replicate the tickets, conversations, contacts, companies, agents, automation rules, surveys, knowledge base, and discussions of your Freshdesk account to the Destination of your choice. To ingest data, you must provide Hevo with the API key of a Freshdesk agent and the subdomain of your Freshdesk account.
Supported Features
| Feature Name | Supported |
|---|---|
| Capture deletes | Yes |
| History mode | No |
| Custom data (user-configured tables & fields) | Yes, the custom fields of tickets, contacts, and companies |
| Data blocking (skip objects and fields) | Yes |
| Resync (objects and Pipelines) | Yes |
| API configurable | Yes |
Prerequisites
-
An active Freshdesk account from which data is to be ingested.
-
The API key of a Freshdesk agent. To ingest data for all the objects, use the API key of an agent with the Account Administrator or Administrator role. Read Obtain the API Key.
Obtain the API Key
Hevo connects to your Freshdesk account using the API key of an agent. Hevo can read only the data that the agent can access, and some objects, such as Agent, Automation, Role, SLA Policy, and Ticket Field, can be read only by an administrator. If the agent cannot access an object, Hevo marks the object as inaccessible and continues to ingest data for the other objects. Hence, to ingest data for all the objects, use the API key of an agent with the Account Administrator or Administrator role.
Perform the following steps to obtain the API key:
-
Log in to your Freshdesk account as an administrator.
-
Click your profile picture in the top-right corner of the page, and then click Profile settings.
-
In the right pane, click View API Key.
-
Select the I’m not a robot check box, and complete the verification if prompted.
-
Click the copy icon next to the Freshdesk API key, and save the key securely like any other password.
Read How to find your API key for more information.
If the API key is reset, or the agent is deleted from your Freshdesk account, Hevo cannot connect to your account, and the Pipeline fails. To resume data ingestion, modify the Source configuration with a valid API key.
Configure Freshdesk as a Source in your Pipeline
Perform the following steps to configure your Freshdesk Source:
-
Click Pipelines in the Navigation Bar.
-
Click + Create Pipeline in the Pipelines List View.
-
On the Select Source Type page, select Freshdesk.
-
On the Select Destination Type page, select the type of Destination you want to use.
-
On the Select Pipeline Type page, click Edge, and then click Continue.
Note: This page appears only if both the Source and the Destination type you selected are supported in Edge. Otherwise, the Configure Source page appears.
-
On the Configure Source page, specify the following:
-
Source Name: A unique name for your Source, not exceeding 255 characters. For example, Freshdesk Source.
-
In the Connect to Freshdesk section:
-
Subdomain: The part of your Freshdesk URL before .freshdesk.com. For example, if your Freshdesk URL is https://acme.freshdesk.com, enter acme.
-
API Key: The API key that you copied from your Freshdesk account.
-
-
-
Click Test & Continue to test the connection to your Freshdesk Source. Hevo uses the API key to read the details of the agent to whom the key belongs. Once the test is successful, you can proceed to set up your Destination.
Data Replication
Hevo replicates data for all the objects selected on the Configure Objects page during Pipeline creation. By default, all supported objects and their available fields are selected. However, you can modify this selection while creating or editing the Pipeline.
The first run of the Pipeline ingests all the data of the selected objects. In the subsequent runs, as per the sync frequency, Hevo ingests data as follows:
| Ingestion | Objects |
|---|---|
| New and updated records, based on the time each record was last updated | Contact |
| All the records, in each run | All other objects |
Hevo ingests all the tickets of your Freshdesk account, however old, including the deleted tickets and the tickets marked as spam. In the first run, Hevo ingests the conversations of all the tickets. In the subsequent runs, Hevo ingests the conversations of only the tickets updated since the previous run. Hevo reads the conversations of each ticket with a separate API request.
You can resync any object.
Freshdesk limits the number of API requests that your account can make in a minute, based on your Freshdesk plan. Trial accounts can make 50 requests per minute. The limit applies to your whole account, so the requests made by other apps that use the Freshdesk API also count toward it. If the limit is exceeded, Hevo waits and retries the request. Read Rate Limit.
Note: You can create a Pipeline with this Source only using the Merge load mode. The Append mode is not supported for this Source.
Schema and Primary Keys
Hevo uses the following schema to upload the records in the Destination. For a detailed view of the objects, fields, and relationships, click the ERD.
Data Model
The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:
| Object | Description |
|---|---|
| Advanced Survey | Contains the customer satisfaction (CSAT) surveys created with the new survey builder, including the title, language, and state of each survey. |
| Advanced Survey Answer | Contains the answers given to each question in a response to an advanced survey. |
| Advanced Survey Question | Contains the questions in each advanced survey, including the question text, type, and display settings. This object has a child object, Advanced Survey Question Rating, which contains the rating options of each question, with their value and label. |
| Advanced Survey Response | Contains the responses to each advanced survey, including the ticket, contact, agent, and group that each response relates to. |
| Agent | Contains the agents of your helpdesk, including their availability, type, ticket scope, and signature. |
| Agent Group | Contains the groups that each agent belongs to. |
| Agent Role | Contains the roles assigned to each agent. |
| Automation | Contains the automation rules of your helpdesk, including the rule type, status, position, and the number of tickets affected. |
| Automation Action | Contains the actions that each automation rule performs, such as sending an email, adding a note, or calling a webhook. |
| Automation Condition | Contains the conditions that decide when each automation rule runs. |
| Automation Event | Contains the events that trigger each automation rule, such as a change in a ticket property. |
| Automation Performer Member | Contains the agents set as performers of each automation rule. |
| Business Hour | Contains the business hours of your helpdesk, including the time zone and the working hours of each day. |
| Company | Contains the companies that your contacts belong to, including the description, notes, industry, account tier, and renewal date. Each custom field of your companies is stored in a separate column, named custom_<field name>. |
| Company Domain | Contains the email domains of each company. |
| Contact | Contains your customers, including their name, email address, phone number, company, language, and time zone, and whether each contact is blocked or deleted. Each custom field of your contacts is stored in a separate column, named custom_<field name>. |
| Conversation | Contains the replies and notes on each ticket, including the body, sender, source, and whether the entry is private or incoming. |
| Conversation Attachment | Contains the files attached to each conversation, including the name, size, and content type. |
| Conversation BCC Email | Contains the email addresses in the BCC field of each conversation. |
| Conversation CC Email | Contains the email addresses in the CC field of each conversation. |
| Conversation To Email | Contains the email addresses that each conversation was sent to. |
| Discussion Category | Contains the categories of the discussion forums in your support portal. |
| Discussion Comment | Contains the comments posted on each discussion topic. |
| Discussion Forum | Contains the forums in each discussion category, including the forum type, visibility, and the number of topics and posts. |
| Discussion Topic | Contains the topics in each discussion forum, including the title, hits, votes, and reply details. |
| Email Config | Contains the support email addresses of your helpdesk, including the reply email address and the group and product that each address is linked to. |
| Group | Contains the agent groups of your helpdesk, including the business hours and automatic ticket assignment settings of each group. |
| Priority Lookup | Contains the ticket priorities of your helpdesk, with the ID and name of each priority. |
| Product | Contains the products configured in your helpdesk. |
| Role | Contains the agent roles of your helpdesk. |
| Satisfaction Rating | Contains the satisfaction ratings that your customers gave, including the feedback and the ticket, agent, and group that each rating relates to. |
| Satisfaction Rating Value | Contains the rating given to each survey question in a satisfaction rating. |
| SLA Policy | Contains the service level agreement (SLA) policies of your helpdesk, including the status and position of each policy. This object has the following child objects: - SLA Policy Applicable To: The companies, groups, sources, products, and ticket types that each policy applies to. - SLA Policy Target: The response, next response, and resolution targets of each policy, for each ticket priority. - SLA Policy Escalation Response, SLA Policy Escalation Next Response, and SLA Policy Escalation Resolution: The agents to whom a ticket is escalated when the target is missed, with the escalation time. - SLA Policy Escalation Reminder Response, SLA Policy Escalation Reminder Next Response, and SLA Policy Escalation Reminder Resolution: The agents who are reminded before the target is due, with the reminder time. |
| Solution Article | Contains the articles of your knowledge base, including the title, status, tags, and feedback counts of each article. |
| Solution Category | Contains the categories of your knowledge base, in each language. |
| Solution Folder | Contains the folders in each knowledge base category, including the visibility and the number of articles. |
| Source Lookup | Contains the ticket sources (channels) of your helpdesk, with the ID and name of each source. |
| Status Lookup | Contains the ticket statuses of your helpdesk, including the custom statuses, with the labels shown to agents and customers. |
| Survey | Contains the classic customer satisfaction surveys of your helpdesk. |
| Survey Question | Contains the questions in each classic survey, including the label and the accepted ratings. |
| Ticket Field | Contains the ticket fields of your helpdesk, including the default and custom fields, their type, and their visibility settings for agents and customers. |
| Ticket History | Contains the tickets of your helpdesk with their details, including the subject, status, priority, source, requester, assigned agent and group, due dates, and whether each ticket is deleted or marked as spam. Each custom field of your tickets is stored in a separate column, named custom_<field name>. This object has the following child objects: - Ticket CC Email, Ticket Forward Email, Ticket Reply CC Email, and Ticket To Email: The email addresses in the CC, forward, reply CC, and To fields of each ticket. - Ticket Tag: The tags of each ticket. |
| Time Entries | Contains the time that agents logged against each ticket, including the time spent and whether it is billable. |
Additional Information
Read the detailed Hevo documentation for the following related topics:
Handling of Deletes
Hevo captures the deletes of the Freshdesk objects as follows:
| Deletes Captured | Objects |
|---|---|
| In each run, by comparing the data | All objects, except Contact. Hevo ingests all the records of these objects in each run, and marks the records that are no longer returned by Freshdesk as deleted by setting the value of the metadata column __hevo__marked_deleted to True. For example, a company that you delete in Freshdesk is marked as deleted in the next run. |
| Through the source data |
Contact and Ticket History. Hevo also ingests the contacts and tickets that are deleted in Freshdesk, and the value of the deleted column of these records is set to True. A contact that you permanently delete in Freshdesk is no longer returned by Freshdesk and remains in the Destination. |
Source Considerations
-
If the agent whose API key you use does not have access to an object, for example, because the agent’s role or your Freshdesk plan does not include it, Hevo marks the object as inaccessible and continues to ingest data for the other objects.
-
Hevo ingests all the tickets in each run, with 100 tickets per API request, and reads the conversations of each updated ticket with a separate API request. As a result, the number of API requests in each run increases with the number of tickets.
-
Hevo creates a table in the Destination only for the objects that have data. For example, if you do not use the Freshdesk forums, the Discussion Category, Discussion Forum, Discussion Topic, and Discussion Comment tables are not created.
Limitations
- Hevo supports only the Freshdesk domains, such as acme.freshdesk.com, and not custom domains.