Freshdesk: Setup and required permissions

When you create a new connector app instance in any of your SIGNL4 teams, you can configure some parameters or you leave it with the default values. In any case there is two fields that you need to specify and which do not have default values:

• Freshdesk Instance URI
  • This is simply the main URI of your Freshdesk account. An example is
    https://signl4.freshdesk.com/
• API key
  • SIGNL4 uses the Freshdesk REST API (https://developers.freshdesk.com/api/) to setup some required assets in Freshdesk and to read ticket data or linked entities (e.g. retrieving the name of a company a ticket belongs to). Read through the next sections to learn how to create an awesome API key in Freshdesk so that you can enter it in the app configuration.

How to create the API key in Freshdesk?

API keys in Freshservice belong to agent user accounts. Each agent can find his/her API key in the personal profile menu. The easiest thing you could do is to use the API key of the Freshservice account owner. That user has of cause all permissions and thus its API key is suitable for all API actions the connector app uses.

Creating an integration user account

However, this is most likely not what you want as you don't want to hand out such a "master" key to a 3rd party application like SIGNL4. Instead, what you want to do is creating a dedicated integration agent user account specifically for SIGNL4. A nice guide on how to add agents can be found here: https://support.freshdesk.com/support/solutions/articles/37591-adding-new-support-agents-

Note: When you create the agent you must use an email address that you have access to because an activation link will be sent to that email address. You may need to register a temporary mailbox in order to accomplish that.

During agent creation, assign this user the agent role, we will change this later on.

Create a dedicated user role with streamlined permissions

Next, you'll create a new user role in Freshdesk specifically for SIGNl4. A great article how this can be done is available here: https://support.freshdesk.com/support/solutions/articles/97077-how-to-create-a-new-custom-role-and-why-

Note: The Agent Type of the role must be "Support agent".

All required permissions can be found in the screenshot below. It's recommended that in your role you tick the exact same boxes.

A few words on the required "Admin permissions":

• Manage all agents (Assume identity)
  • SIGNL4 adds notes to tickets, e.g. when mobile agents are adding some annotations in the SIGNL4 mobile app. If this box is ticked, SIGNL4 can impersonate these agents and the ticket activity log will show their profile picture with the notes that were added. This works for other agents but not for other admins (even with this box ticked, SIGNL4 cannot impersonate users with higher roles than it has itself)
• Play God with Super Admin controls
  • This option is required to be able to read ticket fields (https://developers.freshdesk.com/api/#ticket-fields). The connector reads these fields and is then able to create very user friendly Signls in which you can read the name of a status (e.g. 'Pending') instead of its id. Same goes for priority, etc.

SIGNL4 does a lot of GET methods on the API (e.g. tickets, companies, products) to be able to compose user friendly tickets. It does the POST/PUT method on the ticket for agent assignment or adding notes. It however never does a DELETE method at all.

Putting all pieces together

Once the agent account and user role has been created, it is very simple to get your API key:

• Open the details of the created agent user account for SIGNL4
• Remove all existing roles from it
• Add the recently created SIGNL4 user role to the agent user account
• Log in as the created agent
• Navigate to your profile details and extract your API key as described here: https://support.freshdesk.com/support/solutions/articles/215517-how-to-find-your-api-key
• Copy the key and paste it in the SIGNL4 connector app config in the "API key" field.