Freshdesk

1. Overview

Freshdesk is a cloud-based customer support platform that helps teams manage customer interactions through a unified ticketing system. It streamlines support operations by organizing customer queries, tracking issues, and enabling efficient communication across multiple channels.

Through the GoInsight Freshdesk node, you can seamlessly integrate customer support operations into your automated workflows. This integration enables comprehensive management of your support ecosystem, including:

• Contact Management: Create, retrieve, update, and delete customer contact records.
• Ticket Operations: Create, retrieve, update, and delete support tickets to track customer issues.
• Batch Retrieval: Fetch multiple contacts or tickets with pagination and filtering capabilities.

2. Prerequisites

Before using this node, you need to have the following:

• A valid Freshdesk account with an active subscription.
• API access enabled on your Freshdesk account.
• Appropriate permissions to create and manage API keys (typically requires agent or administrator access).

3. Credentials

For detailed guidance on how to obtain and configure your Freshdesk API credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

The Freshdesk node primarily operates around two core resources: Contacts (customer records) and Tickets (support requests). The following table provides an overview of all available operations:

Operation Details

Create a Contact

Creates a new contact in Freshdesk using provided details and API key.

Input Parameters:

• ApiKey: The Freshdesk API Key for authentication.
• Domain: Your Freshdesk subdomain without protocol and suffix (e.g., "yourcompany").
• Name: The contact's name (required).

Options:

• Email: The contact's email address (optional).
• Phone: The contact's phone number (optional).
• Address: The contact's address (optional).
• TwitterId: The contact's Twitter ID (optional).
• UniqueExternalId: A unique external identifier for the contact (optional).

Output:

• Contact (object): The Freshdesk contact object returned, including details such as id, name, email, phone, address, twitter_id, unique_external_id, created_at, updated_at, etc.
• StatusCode (int): HTTP status code — 201 for success; -1 for parameter validation error; 500 for exception; other codes as returned by the API.
• ErrorMessage (string): Error message if any; empty on success.

Get a Contact

Gets details of a Freshdesk contact specified by its contact ID.

Input Parameters:

• ApiKey: The Freshdesk API Key for authentication.
• Domain: Your Freshdesk subdomain without protocol and suffix (e.g., "yourcompany").
• ContactId: The ID of the contact to retrieve (required).

Output:

• Contact (object): The Freshdesk contact object returned, including details such as id, name, email, phone, address, twitter_id, unique_external_id, created_at, updated_at, etc.
• StatusCode (int): HTTP status code — 200 for success; -1 for parameter validation error; 500 for exception; other codes as returned by the API.
• ErrorMessage (string): Error message if any; empty on success.

Get many Contacts

Gets a list of Freshdesk contacts with optional pagination parameters.

Input Parameters:

• ApiKey: The Freshdesk API Key for authentication.
• Domain: Your Freshdesk subdomain without protocol and suffix (e.g., "yourcompany").
• Page: Page number to retrieve (must be > 0).
• PerPage: Number of contacts per page (must be > 0).

Output:

• Results (array): List of Freshdesk contact objects returned by the API.
• StatusCode (int): HTTP status code — 200 for success; -1 for parameter validation error; 500 for exception; other codes as returned by the API.
• ErrorMessage (string): Error message if any; empty on success.

Update a Contact

Updates an existing Freshdesk contact specified by its contact ID with provided details.

Input Parameters:

• ApiKey: The Freshdesk API Key for authentication.
• Domain: Your Freshdesk subdomain without protocol and suffix (e.g., "yourcompany").
• ContactId: The ID of the contact to be updated (required).

Options:

• Name: The contact's name.
• Email: The contact's email address.
• Phone: The contact's phone number.
• Address: The contact's address.
• TwitterId: The contact's Twitter ID.
• UniqueExternalId: A unique external identifier for the contact.

Output:

• Updated (boolean): Indicates whether the contact was successfully updated.
• Contact (object): The Freshdesk contact object returned, including details such as id, name, email, phone, address, twitter_id, unique_external_id, created_at, updated_at, etc.
• StatusCode (int): Operation result code: 200 for success; -1 for parameter validation error; 500 for exception; other codes as returned by the API.
• ErrorMessage (string): Error message if update failed or exception occurred; empty on success.

Delete a Contact

Deletes a Freshdesk contact specified by its contact ID. This operation cannot be undone.

Input Parameters:

• ApiKey: The Freshdesk API Key for authentication.
• Domain: Your Freshdesk subdomain without protocol and suffix (e.g., "yourcompany").
• ContactId: The ID of the contact to be deleted (required).

Output:

• Deleted (boolean): Indicates whether the specified contact was successfully deleted.
• StatusCode (int): Operation result code: 204 for success; -1 for parameter validation error; 500 for exception; other codes as returned by the API.
• ErrorMessage (string): Error message if deletion failed or exception occurred; empty on success.

Create a Ticket

Creates a ticket in Freshdesk with the specified details.

Input Parameters:

• ApiKey: Freshdesk API key for authentication.
• Domain: Your Freshdesk account subdomain (the part before .freshdesk.com).
• Subject: Subject of the ticket.
• Description: Detailed description for the ticket.
• Email: Requester's email address.
• Priority: Ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent).
• Status: Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed).

Output:

• TicketId (int): ID of the newly created ticket.
• StatusCode (int): Operation status code: 201 (created), 500 (server error), -1 (parameter validation error).
• ErrorMessage (string): Error message if the creation failed; empty string on success.

Get a Ticket

Retrieves the details of a Freshdesk ticket specified by its ticket ID.

Input Parameters:

• ApiKey: Freshdesk API key for authentication.
• Domain: Your Freshdesk account subdomain (the part before .freshdesk.com).
• TicketId: The ID of the ticket to retrieve.

Output:

• Ticket (object): The Freshdesk ticket object with all fields as returned by the API.
• StatusCode (int): Overall operation status code: 200 (success), 404 (not found or other error codes), 500 (server error), -1 (parameter validation error).
• ErrorMessage (string): Error message if retrieval failed; empty string on success.

Get many Tickets

Retrieves a list of Freshdesk tickets with optional filters for status, priority, pagination, and updated_since.

Input Parameters:

• ApiKey: A valid Freshdesk API key.
• Domain: Your Freshdesk account subdomain (without https:// and .freshdesk.com).
• Page: Page number to retrieve, starting from 1.
• PerPage: Number of tickets per page, maximum 100.

Options:

• Status: Filter tickets by status (2=Open, 3=Pending, 4=Resolved, 5=Closed).
• Priority: Filter tickets by priority (1=Low, 2=Medium, 3=High, 4=Urgent).
• UpdatedSince: RFC 3339 timestamp to filter tickets updated after this time.

Output:

• Tickets (array): A list of Freshdesk ticket objects as returned by the API.
• StatusCode (int): Overall operation status code: 200 (success), 404 (not found or other error), 500 (server error), -1 (parameter validation error).
• ErrorMessage (string): Error message if retrieval failed; empty string on success.

Update a Ticket

Updates a Freshdesk ticket specified by its ticket ID with the provided fields.

Input Parameters:

• ApiKey: A valid Freshdesk API key for authentication.
• Domain: Your Freshdesk account subdomain (without https:// and .freshdesk.com).
• TicketId: The ID of the ticket to update.

Options:

• Subject: New subject for the ticket.
• Description: New description for the ticket.
• Status: New ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed).
• Priority: New ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent).

Output:

• Ticket (object): The updated Freshdesk ticket object as returned by the API.
• StatusCode (int): Overall operation status code: 200 (success), 404 (not found or other error codes), 500 (server error), -1 (parameter validation error).
• ErrorMessage (string): Error message if update failed; empty string on success.

Delete a Ticket

Deletes a ticket in Freshdesk specified by its ticket ID. This operation cannot be undone.

Input Parameters:

• ApiKey: Freshdesk API key for authentication.
• Domain: Freshdesk account subdomain (the part before .freshdesk.com).
• TicketId: The ID of the ticket to delete.

Output:

• Deleted (boolean): Indicates whether the ticket was successfully deleted.
• StatusCode (int): Operation status code: 204 (deleted), 404 (not found or other error codes), 500 (server error), -1 (parameter validation error).
• ErrorMessage (string): Error message if the deletion failed; empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow that creates a new support ticket in Freshdesk. This is one of the most common use cases when integrating support operations into your automation.

Scenario: You want to automatically create a support ticket when a customer submits a request through your system.

Workflow Overview: The workflow consists of three nodes: Start → Freshdesk → Answer. The Start node initiates the workflow, the Freshdesk node creates the ticket, and the Answer node returns the result.

Step-by-Step Guide:

1. Add the Freshdesk Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the popup panel, select the "Tools" tab.
   • Find and select Freshdesk from the tools list.
   • In the list of supported operations for Freshdesk, click to select Create a Ticket. This will add the corresponding node to your canvas.
2. Configure the Node:
   • Click on the newly added Create a Ticket node. The configuration panel will expand on the right side.
   • Credentials Configuration: At the top of the panel, locate the credentials field. Click the dropdown menu and select your pre-configured Freshdesk credentials (API Key and Domain).
   • Parameter Configuration: Fill in the required input parameters:
   • Subject: Enter a subject for the ticket, such as "Customer inquiry about product features".
   • Description: Provide a detailed description of the issue, for example "Customer is asking about advanced features in the Pro plan".
   • Email: Enter the requester's email address, such as "customer@example.com".
   • Priority: Set the priority level. For this example, select 2 (Medium priority).
   • Status: Set the initial status. Select 2 (Open status).
3. Run and Verify:
   • Once all required parameters are correctly filled in, any error indicators in the top-right corner of the canvas will disappear.
   • Click the "Test Run" button in the top-right corner to execute the workflow.
   • After successful execution, click the log icon in the top-right corner to view the detailed input and output of the node, and verify that the ticket was successfully created. You should see a TicketId in the output, along with a StatusCode of 201.

Final Workflow Summary: After completing the above steps, your workflow is fully configured. When you click "Test Run", a new support ticket will be successfully created in your Freshdesk account, and you can verify it by logging into your Freshdesk dashboard.

6. FAQs

Q: What should I do if I receive a 401 Unauthorized error?

A: This error typically indicates an authentication issue. Please check the following:

• Verify that your API Key is correct and hasn't expired.
• Ensure your Domain is correctly formatted (e.g., "yourcompany" without the ".freshdesk.com" suffix).
• Confirm that your API access is enabled in your Freshdesk account settings.

Q: How do I find my Freshdesk subdomain?

A: Your Freshdesk subdomain is the first part of your Freshdesk URL. For example, if your Freshdesk URL is https://yourcompany.freshdesk.com, then your subdomain is yourcompany. When configuring the node, only provide the subdomain part without "https://" and ".freshdesk.com".

Q: What do the different ticket status codes mean?

A: Freshdesk uses numeric codes for ticket statuses:

• 2 = Open
• 3 = Pending
• 4 = Resolved
• 5 = Closed

Q: What do the different ticket priority codes mean?

A: Freshdesk uses numeric codes for ticket priorities:

• 1 = Low
• 2 = Medium
• 3 = High
• 4 = Urgent

Q: Can I permanently recover a deleted contact or ticket?

A: No. The delete operations for both contacts and tickets are permanent and cannot be undone. Please exercise caution when using these operations. Consider implementing a confirmation step in your workflow before executing delete operations.

Q: What is the maximum number of results I can retrieve in a single request?

A: For the "Get many Tickets" operation, the maximum is 100 tickets per page. For contacts, while there's no strict limit mentioned, it's recommended to use reasonable page sizes (e.g., 30-100) for optimal performance. Use pagination to retrieve larger datasets.

7. Official Documentation

For more detailed information about Freshdesk's API capabilities, please refer to the official documentation:

Freshdesk Official API Documentation