With the Freshdesk help widget, you can embed solution articles and a contact form within your website or product. When your customers need help, they can open the widget to search through solution articles or to submit a ticket. You can watch this video to learn how to set up the help widget.


Freshdesk allows you to restrict visibility for certain folders in your knowledge base, to either logged in users of your portal or for contacts from certain companies. With this you can:

  • Prevent solution articles with sensitive information from being displayed publicly
  • Show solution articles with information about a company to just contacts from that company
  • Allow only premium customers to access certain solution articles


When you create a help widget, you can pick solution article categories to associate with that widget. If these categories have folders with restricted visibility, your users need to be authenticated into the widget to view those solution articles.


1. Restricting folder visibility for certain contacts:

You can apply this setting to any folder (and the solution articles in it) by editing its properties. You can choose to make a folder (and its solution articles) visible to:

  • All users
  • Logged in users
  • Agents
  • Companies
  • Bots


To edit the properties of a folder, go to the Solutions screen, select any folder, and click on the edit folder icon.





2. Setting up the help widget:


  • Once enabled, you can select which categories of solution articles to display. 



3. Authenticating users with the shared secret key:


  • To authenticate your customers into the widget, you'll first need your shared secret key. The shared secret key can be found in your Freshdesk account in Admin > Account > Security > Widget settings. Here's an example:



Note: If you are on Freshdesk Omni, go to Admin > Data and Security > Ticket Security.

  • To use the authenticate API, generate a JWT token on the server-side using your customer's name, email, and expiry time in the payload.
  • The expiry time needs to be specified in the Unix Timestamp Format and should not be greater than two hours.
  • This payload needs to be signed with your account's shared secret key using the HS256 algorithm.


To learn more about the specifics of generating a JWT token, please read our API documentation.


Sample code to generate JWT token:


require 'jwt'
payload = {
  name: authenticatedCustomerName,
  email: authenticatedCustomerEmail,
  exp: (Time.now + 2.hours).to_i
}
token = JWT.encode payload, widgetSharedSecretKey


var jwt = require('jwt-simple');
var payload = {
  name: authenticatedCustomerName,
  email: authenticatedCustomerEmail,
  exp: Date.now() + 7200
};
var token = jwt.encode(payload, widgetSharedSecretKey);


  • Python (based on pyjwt library)
import jwt
from datetime import datetime, timedelta
payload = {
  "name": authenticatedCustomerName,
  "email": authenticatedCustomerEmail,
  "exp": int((datetime.now() + timedelta(hours=2)).timestamp())
}
token = jwt.encode(payload, widgetSharedSecretKey, algorithm='HS256')

  • Once you generate the JWT token on your server-side, you need to pass it as a parameter to the widget's JavaScript authenticate API. This will authorize your customers into the widget, allowing them to view restricted solution articles or the contact form (if it's been restricted to logged-in users as well).
  • However, this authorization expires based on the time you've set. For a seamless experience for your customers, pass a callback function to automate token renewal. The callback function will be automatically invoked before token expiry. The callback function on your side needs to:
    • regenerate the JWT token using the customer's name and email in the payload, while also specifying the expiry time. It needs to be signed with the account's shared secret key. 
    • call the authenticate API with the regenerated token
{
  freshworks_widget_auth_token: “eyJh.GUuY29tIiwibmF.RIjow”
}


then this is a sample of how your implementation of the authenticate API would look like:

FreshworksWidget('authenticate', {
  token: 'YOUR_JWT_TOKEN_HERE',
  callback: authenticateCallback
});

authenticateCallback = function() {
fetch('https://your-server.tld/your-auth-url').then(
 function(data) {
    FreshworksWidget('authenticate', {
      token: data.freshworks_widget_auth_token
    });
  })
}


In this example, the authenticate API calls the authenticateCallback() function every time the JWT token expires.


  • The contact form will be prefilled with the customer's details (name and email address).
  • The logged-in customer will be able to view and search only the articles they have access to.
  • The help widget will load the contact form and solution articles in the customer's preferred language. The customer can set their preferred language in your Freshdesk portal by logging in and going to Edit profile > Language. You can override this with the locale parameter.
  • On the agent portal, you will be able to see which customers have marked an article as helpful/not helpful on the help widget.


When customers log out of your website, you need to log them out of the widget. You can make use of the logout API to do this:

FreshworksWidget('logout')

Here's an example of the logout API being used on click of the sign out button:

function logoutWidget() {
    FreshworksWidget('logout')
}
<a href="#" onclick="logoutWidget()">Sign out</a>


7. Resetting shared secret key 

  • You can reset the shared secret key from Admin > Account > Security > Widget settings.
  • When you reset your shared secret key, all sessions will become invalid, and any customer who has been logged into the widget will be logged out. 

After resetting, you'll need to use the new shared secret key to generate the JWT token on your server-side.



For more information on configuring the help widget and embedding in your website, you can refer to this article - Customizing the appearance of your help widget