Freshdesk
The Freshdesk example solution showcases how to connect a Teneo solution with the Freshdesk REST API. The example flows in the solution demonstrate how tickets can be retrieved as well as how to create, update or delete tickets on Freshdesk.
Solution contents
Freshdesk integration
The solution contains a Freshdesk backend integration containing methods for authentication, retrieval of tickets, agents, contacts as well as for creating, updating and deleting tickets. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.
Example flows
For each core method in the Freshdesk integration, the solution contains a corresponding example flow:
- User asks to retrieve tickets assigned to someone
- User asks to retrieve tickets requested by someone
- User asks to create a new Freshdesk ticket
- User asks to delete a ticket
- User asks to update an existing field of ticket
- Bot asks an user to login into Freshdesk
- User asks to logout from Freshdesk
Authentication flow
Freshdesk provides a support for OAuth authentication, API token based authentication and basic authentication methods that allow a Teneo bot to interact with Freshdesk on the user's behalf. Which authentication method to use depends on factors like use case and channel. This example solution contains flow to demonstrate API token based authentication approach.
Getting started
Prerequisites
These instructions assume you have a Freshdesk admin account. Alternatively, you can sign up for a free user account on Freshdesk. These instructions assume you have downloaded and imported the Freshdesk solution. See instructions below.
Create a Freshdesk connected app
It's time to create a developer instance on Freshdesk developer portal in order to perform and experience some CRUD operations by using Freshdesk Teneo bot
- Using your administrator account, log in to your Freshdesk developer portal.
- For first time login users, click on the 'Get started' button and go over the wizard steps once to make sure that your user account is activated and completed on all aspects.
- Click on avatar icon located at the top most right corner of Freshdesk instance and click on 'Profile settings' menu.
- User access credentials such as user's full name and API key (located under Your API Key section) and this should be copied and secured immediately as this requires for you to login to Freshdesk Teneo bot to perform various operations.
- Your Freshdesk instance setup is completed now.
Configure user agent settings (optional)
It's good to have a look on your user agent settings to manage the roles associated with your account
- Click on 'Admin' icon located at the left side panel menu of Freshdesk portal.
- Under General settings click on 'Agents' button.
- Move your mouse cursor on any agent and click on 'Edit' icon appeared on the right side
- Scroll down until you find a section Ticket scope, 'Choose groups that the agent is a part of' and assign relevant roles as you wish
Add credentials to your solution
The solution contains global variables Freshdesk_sLoginUserId, Freshdesk_sAPIKey and Freshdesk_sInstanceEndPointUrl in which various credentials we have collected should be stored. We’re interested in our instance userId and API key. People may try to use their Freshdesk userId and API key accordingly. The value of the global variable should be a type of String like this:
| Variable Name | Example value | Description |
|---|---|---|
| Freshdesk_sLoginUserId | 'teneoUser' | Freshdesk user account id |
| Freshdesk_sAPIKey | 'ttNxxxxxxLIlxx3r' | Freshdesk user account API key |
| Freshdesk_sInstanceEndPointUrl | https://xxxxxxxxxxxxxxxxxx.freshdesk.com | Base URL of Freshdesk instance end point |
To update the global variables, proceed as follows:
- In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
- In you Freshdesk solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
- Select the 'Variables' tab at the top, select the variables called Freshdesk_sLoginUserId, Freshdesk_sAPIKey and Freshdesk_sInstanceEndPointUrl.
- In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
- When done, click 'Save All' in the top left corner.
Test in Try Out
Your solution is now ready. You can test this in Try Out by asking I need to retrieve Freshdesk tickets assigned to other user. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the tickets, which are assigned to a user on Freshdesk portal.
Example conversations
User: I want to login
Bot: Hi there! I'm a Freshdesk Connector virtual assistant from Artificial Solutions.
Bot: Please enter your Freshdesk account user id.
User: teneoUser
Bot: Please enter an API key provided by Freshdesk.
User: ttNxxxxxxLIlxx3r
Bot: Please enter an instance url provided by Freshdesk. Example :https://xxxxxx.freshdesk.com
User:https://xxxxxx.freshdesk.com
Bot: Hi testuser, Your login has been successful!
User: I want to create a new Freshdesk ticket
Bot: Please enter the description of ticket.
User: Test descr
Bot: Please enter the subject of ticket.
User: Test ticket subject
Bot: Please enter the requester email id. Example : test@domain.com
User: teneo@example.com
Bot: Please choose one of the following priorities. Low, Medium, High, Urgent
User: High
Bot: New ticket #14 has been created on your Freshdesk instance successfully.
User: I need to retrieve Freshdesk tickets assigned to other user
Bot: Please enter an assignee name. Note: Assignee name is case sensitive.
User: John Doe
Bot: Below are list of tickets assigned to John Doe. 16, 15, 5
User: I need to retrieve Freshdesk tickets requested by other user
Bot: Please enter a requester name. Note: Requester name is case sensitive.
User: test requester
Bot: Below are list of tickets requested by test requester. 3, 10, 23
User: I need to modify a Freshdesk ticket
Bot: Please enter an existing ticket id.
User: 18
Bot: Please choose one of the following ticket fields. Description, Status, Priority, Source, Assignee (Agent)
User: Assignee
Bot: Please enter an assignee name. Note : Assignee name is case sensitive.
User: John Doe
Bot:responder_id field has been updated on ticket 18 successfully!
User: I wish to delete a Freshdesk ticket
Bot: Please enter an existing ticket id
User: 18
Bot: Freshdesk ticket 18 has been deleted successfully!
User: I want to logout
Bot: Your logout has been successful!
For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.
More on authentication
Freshdesk offers multiple authentication methods including OAuth authentication, Basic authentication and API token key based authentication by using user id & API key that developers can use to allow their users to authenticate with Freshdesk. Which authentication flow to use depends on the type of application and the use case.
This Freshdesk solution contains a flow called 'Bot asks a user to login into Freshdesk'. This flow is responsible to set a value of global variable called Freshdesk_bHasUserLoggedIn which is included at the beginning of each other flows that checks the user's authentication to access the flows. This flow checks if the global variables Freshdesk_sLoginUserId, Freshdesk_sAPIKey and Freshdesk_sInstanceEndPointUrl contains values which is needed to perform API requests. If the __Freshdesk_bHasUserLoggedIn__variable is 'false', this flow answers a user authentication failure message.
By default, the Freshdesk 'Bot asks a user to login into Freshdesk' flow uses the stored credentials from global variables to authenticate the user. This flow uses Freshdesk's API key based authentication mechanism, which provides instructions in the getting started section on this page explain how to prepare your solution using this authentication approach.
This authentication uses stored credentials from global variables Freshdesk_sLoginUserId, Freshdesk_sAPIKey and Freshdesk_sInstanceEndPointUrl to prepare an authentication with Freshdesk and it generates a Base64 encoded authorization header value on another global variable Freshdesk_sBasicAuthToken and checks an access against Freshdesk instance URL stored on Freshdesk_sInstanceEndPointUrl and return a successful authentication. The value generated for global variable Freshdesk_sBasicAuthToken looks like this:
| Variable Name | Example value | Description |
|---|---|---|
| Freshdesk_sBasicAuthToken | 'Basic Qwtr3edsfxxxxx==' | Basic auth token (Base64 encoded) to access Freshdesk resources via REST API |
This Base64 encoded value is then stored in the global variable Freshdesk_sBasicAuthToken, so it can be used for subsequent requests that require authentication across flows in the Freshdesk solution. The global variable is used by the Freshdesk integration for the various REST requests.
The solution uses the stored credentials approach by default, mostly because it is easiest and quickest to get started. However, because this authentication flow passes the user’s credentials back and forth it is advised to use this authentication method for development purposes only. Additionally, using stored credentials means that all objects created by the bot are created by the same user. Therefore, it might be preferred to implement an authentication flow that enables Teneo to interact with Freshdesk on the user's behalf.
However, this authentication flow can still be used in production grade only when a frontend connector or a channel connector supplies necessary user credentials instead of hardcoding them in Teneo in a more secured way by using any industrial standard encryption techniques.
The authentication flow for the API Key based authentication in combination with Teneo roughly looks like this:
For more details on Freshdesk and API Key based authentication, see: Digging Deeper into API token in Freshdesk.
Download
- Download the solution freshdesk.
- Import the solution into Teneo. For more details see: How to import solutions.