Last updated: 2025-02-17

Source: https://support.freshdesk.com/support/solutions/articles/50000000978-authenticating-users-into-the-help-widget

Authenticating users into the help widget

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. For information on creating the help widget, see Set up your help widget.

  • 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:

  • If you don't have the help widget, you can reach out to support@freshdesk.com. For information on creating the help widget, see Set up your help widget.
  •  While setting up the widget, you can choose to show solution articles.

  • 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:

  • Ruby (based on ruby-jwt gem)

    • ```ruby

    ```

    Ruby

  • NodeJS (based on jwt-simple package)

    • ```javascript

    ```

    JavaScript

  • Python (based on pyjwt library)

    • ```python

    ```

    Python

    4\. Using the authenticate API

  • 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

  • If you're making an API call to _https://your-server.tld/your-auth-url_ to generate a JWT token on the server-side, and it returns this data:

    • ```javascript

    ```

    JavaScript

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

    ```javascript

    ```

    JavaScript

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

    5\. Once you've embedded the widget code and authenticated a customer

  • 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.

    • 6\. Logging out your users

    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:

    ```javascript

    ```

    JavaScript

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

    ```javascript

    ```

    JavaScript

    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.