Overview

With the Freshdesk help widget, you can embed a contact form or a knowledge base right within your products. With the help of these APIs, you can customize the widget even further - for example, you can hide the widget in certain pages or prefill certain fields when your customers open the contact form.

Before you dive in

Here's how you can configure a new help widget:

  1. Login to your account.
  2. Go to Admin > Widgets.
  3. Click 'Create a new widget'.
  4. Enable options based on what you'd like your customers to see when they open the widget. You can choose to embed a contact form or have solution articles show up, or both.
  5. Once you're done, click the 'Embed code' tab, copy and paste the code in the page where you want the widget to appear, right before the </body> tag.
  6. Please ensure that you include the APIs only after the widget's embed code, enclosed within <script> tags.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
<script> window.fwSettings={ 'widget_id':12000000025, 'locale': 'en' }; !function(){if("function"!=typeof window.FreshworksWidget){var n=function(){n.q.push(arguments)};n.q=[],window.FreshworksWidget=n}}() </script> <script type='text/javascript' src='https://widget.freshworks.com/widgets/12000000025.js' async defer /> <script type='text/javascript'> //insert API here </script>
EXPAND ↓

Hide the widget

If you'd like to hide the widget on certain web pages on your site, you can use this API.

Copied Copy
1
FreshworksWidget('hide');
EXPAND ↓

If you already have a link or a button on your website which should invoke the help widget, and you want the widget to be hidden until your customers click on the link or button, we suggest you use the API below. This will hide the launcher as well.

Copied Copy
1
FreshworksWidget('hide', 'launcher');
EXPAND ↓

Click here to learn more about using this API. Click the button below to see a demo of the hide and show APIs on the widget embedded on this page.

Show the widget

Using the show API, you can make the widget appear if you had previously hidden it on your web pages.

Copied Copy
1
FreshworksWidget('show');
EXPAND ↓

If you had previously hidden the launcher button using the hide API, you can make it appear using this API:

Copied Copy
1
FreshworksWidget('show', 'launcher');
EXPAND ↓

Click the button below to see a demo of the hide and show APIs on the widget embedded on this page.

Open the widget

If you'd like the widget to open when your customers click on a link or a button on your website, you can use the open API.

Click here to learn more about using this API.

Copied Copy
1
FreshworksWidget('open');
EXPAND ↓

Close the widget

To close the widget if it's already open, use this API.

Copied Copy
1
FreshworksWidget('close');
EXPAND ↓

Destroy the widget

If you want the widget to display only in certain pages on your website, you can use this API to unmount it.

Copied Copy
1
FreshworksWidget('destroy');
EXPAND ↓

Initialize the widget

If you've unmounted the widget on certain pages using the destroy API, use this API to initialize the widget. This does not open the widget, only brings it to life.

Copied Copy
1
FreshworksWidget('boot');
EXPAND ↓

Open the form

If you have a widget with both solutions and contact form in it, you can use this API to directly open the contact form when your customers click on a link or button on your website.

Copied Copy
1
FreshworksWidget('open', 'ticketForm');
EXPAND ↓

Prefill details about your customers

Using the identify API, you can send information that identifies a customer on your website - like their name and email address. This will be filled in the contact form, when they open it.

If your customers are already logged in to your website, you can use this API to pass their email address and name so that they don't have to fill it again when they're trying to reach out to you.

Click here to learn more about using this API.

Sample
Copied Copy
1
2
3
4
FreshworksWidget('identify', 'ticketForm', { name: 'Rachel', email: 'rachel@acme.inc', });
EXPAND ↓

The following table lists the attributes that can be sent to the identify method.

Attribute Type Description
name string Name of the customer
email string Email address of the customer

Prefill other fields

Using the prefill API, you can populate any field in the contact form. Even after your customers submit the contact form, the fields you've prefilled will continue to persist data. You need to explicitly use the clear API to have them cleared.

Click here to learn more about using this API.

Sample
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
FreshworksWidget('prefill', 'ticketForm', { subject: 'Damaged order', description: 'I received a damaged product', priority: 1, status: 2, group_id: 123, product_id: 12, type: 'Question', custom_fields: { cf_order_id: 100, //Number field cf_date_of_order: '2019-12-31', //Date field cf_order_name: 'Model S', //Single line text field cf_order_amount: 94099.90, //Decimal field cf_order_details: 'I have a problem with this order', //Multi line text field cf_location_country: 'United States', //Dropdown field cf_warranty: true, //Checkbox } });
EXPAND ↓

The following table lists the attributes that can be sent to the prefill API.

Attribute Type Description
subject string Subject to be filled in the form
description string Description to be filled in the form
priority * number Priority to be filled in the form
status * number Status to be filled in the form
group_id number Group that needs to be filled in the form
product_id number Product to be filled in the form
type string Type to be filled in the form
custom_fields object Custom fields to be filled in the form. To determine the name of any custom field, use this API. To prefill dropdowns, send the choice that needs to be filled in. If you have multiple languages, and if you'd like to prefill a dropdown with a certain choice, just use the value of the choice in the primary language.
* Refer the table below for supported values.

Accepted values for default fields

Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4

Disable fields in the form

Using the disable fields API, you can disable any field in the contact form. The field will be visible to your customers when they open the contact form, but they will not be able to edit it.

Click here to learn more about using this API.

Sample
Copied Copy
1
FreshworksWidget('disable', 'ticketForm', ['subject', 'description', 'priority', 'status', 'group_id', 'product_id', 'type', 'custom_fields.cf_order_id']);
EXPAND ↓

The following table lists the attributes that can be sent to the disable API.

Attribute Description
subject To disable the subject field
description To disable the description field
priority To disable the priority field
status To disable the status field
group_id To disable the group field
product_id To disable the product field
type To disable the type field
custom_fields.cf_name_of_the_field Custom fields to be disabled in the form. To determine the name of any custom field, use this API.

Hide fields in the form

Using the hide API, you can hide any field in the contact form. If a required field is hidden but it's not prefilled, a ticket cannot be submitted.

Click here to learn more about using this API.

Sample
Copied Copy
1
FreshworksWidget('hide', 'ticketForm', ['subject', 'description', 'priority', 'status', 'group_id', 'product_id', 'type', 'custom_fields.cf_order_id']);
EXPAND ↓

The following table lists the attributes that can be sent to the hide method.

Attribute Description
subject To hide the subject field
description To hide the description field
priority To hide the priority field
status To hide the status field
group_id To hide the group field
product_id To hide the product field
type To hide the type field
custom_fields.cf_name_of_the_field Custom fields to be hidden in the form. To determine the name of any custom field, use this API.

Hide choices in dropdown fields

Using this API, you can hide certain choices in a default or a custom dropdown field when your customers open the contact form.

Sample
Copied Copy
1
2
3
4
5
6
FreshworksWidget('hideChoices', 'ticketForm', { 'priority':[2,3], 'custom_fields': { 'cf_issue_category': ['Account cancellation', 'Premium support'] } });
EXPAND ↓

The following table lists the attributes that can be sent to the hideChoices method to hide choices in default fields:

Attribute Description
priority To hide choices in the priority field

status To hide choices in the status field
group_id To hide choices in the group field
type To hide choices in the type field

Accepted values for default fields

Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4

Clear the form

Using the clear API, you can clear the contents of any field that may have been prefilled. This does not clear the name and email address you may have prefilled using the identify API.

Copied Copy
1
FreshworksWidget('clear', 'ticketForm');
EXPAND ↓

Open a solution article

If you'd like to open a solution article when your customers click on a link on your website, you can use this API. When using this API, you'll have to specify the article's ID.

To find out an article's ID, please open the article in your portal. The URL would look something like: yourportalname.freshdesk.com/support/solutions/123-this-is-an-article or like this: yourcname.com/support/solutions/123-this-is-an-article. Here, 123 is the article ID.

Sample
Copied Copy
1
2
3
FreshworksWidget('open', 'article', { id: 123 // article ID });
EXPAND ↓

Multilingual support

If you support customers in different languages, you can use Freshdesk to provide solution articles and even translate ticket fields in those languages. You can add languages to your account from Admin > Helpdesk > Manage languages. You can learn more about setting up different languages in Freshdesk here.

Only languages that have been marked as 'Visible for customers' in the 'Manage languages' page are supported in the widget.

Set the widget's language

The help widget first looks for the browser's language and loads solution articles and the contact form in that language. To override this behavior and force load the widget in a certain language, you can use the locale property.

The locale property is useful if you have customers who access your product or website in a certain language, and you want to communicate their preference from your website to the widget. Once the widget is initialized with a certain locale, the language cannot be changed.

If the browser's language or the language mentioned in locale doesn't match any of the languages marked as visible in your account, the widget will load solutions and the contact form in the primary language.

The locale parameter needs to be placed right after widget_id in the embed code.

Sample code to set the widget's language
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
<html> <body> <script> window.fwSettings = { 'widget_id':12000000025, 'locale': 'en' }; !function(){if("function"!=typeof window.FreshworksWidget){var n=function(){n.q.push(arguments)};n.q=[],window.FreshworksWidget=n}}() </script> <script type='text/javascript' src='https://widget.freshworks.com/widgets/12000000025.js' async defer /> </body> </html>
EXPAND ↓
List of locales
Locale Language
ca Catalan
da Danish
en English
es Spanish
fi Finnish
hu Hungarian
it Italian
ko Korean
nl Dutch
pt-BR Portuguese (Brazil)
ru-RU Russian
sl Slovenian
tr Turkish
zh-CN Chinese
th Thai
zh-TW Chinese (Traditional)
bs Bosnian
hr Croatian
ms Malay
sr Serbian
Locale Language
cs Czech
de German
es-LA Spanish (Latin America)
et Estonian
fr French
id Indonesian
ja-JP Japanese
nb-NO Norwegian
pl Polish
pt-PT Portuguese (Portugal)
sk Slovak
sv-SE Swedish
vi Vietnamese
uk Ukrainian
ro Romanian
lv-LV Latvian
bg Bulgarian
el Greek
lt Lithuanian

Translate content

This API can be used to specify translations for labels used in the widget.

Some labels specific to the widget are customizable from the Admin section (like the contact form's title or the welcome message, for example). When you specify these labels in the Admin section, you're specifying them in the primary language.

While solution articles and the contact form will load in the browser's language or in the language set via the locale property, you'll have to provide translations for additional labels that are used in the widget. This can be done using the setLabels API.

While translating the launcher text, we recommend you don't have more than ten characters.

Click here to learn more about using this API.

Sample code to translate labels
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
FreshworksWidget("setLabels", { 'fr': { banner: "Contactez notre équipe de support", launcher: "Soutien", contact_form: { title: "Contactez nous", submit: "Envoyer", confirmation: "Nous reviendrons vers vous bientôt" }, frustration_tracking: { banner: "Pouvons-nous aider?", description: "Nous avons remarqué que vous êtes coincé. Dites-nous ce que vous avez essayé d'accomplir et notre équipe d'assistance vous contactera dans les meilleurs délais.", confirmation: "Merci. Nous serons en contact!" } }, 'es': { banner: "Contacta a nuestro equipo de soporte", launcher: "Apoyo", contact_form: { title: "Contáctenos", submit: "Enviar", confirmation: "¡Nos pondremos en contacto con usted pronto!" }, frustration_tracking: { banner: "¿Podemos ayudar?", description: "Notamos que estás atrapado. Díganos qué estaba tratando de lograr y nuestro equipo de soporte se comunicará con usted lo antes posible.", confirmation: "Gracias. ¡Estaremos en contacto!" } } });
EXPAND ↓
Sample code to translate the contact form title
Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
FreshworksWidget("setLabels", { 'fr': { contact_form: { title:"Contactez nous" } }, 'es': { contact_form: { title:"Contáctenos" } } });
EXPAND ↓

Authenticating customers

On Freshdesk, you can restrict the visibility of solution articles to certain customers. You can learn more about this here. If you want to make articles that have been restricted to logged-in users, or users from certain companies available on the widget, you’ll have to follow the steps listed below.

Generating a JWT token

First, 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. The shared secret key can be found in Admin > Security > Widget settings.

In the header, you can set the type of the token and the signining algorithm, like this:

Copied Copy
1
2
3
4
{ "alg": "HS256", "typ": "JWT" }
EXPAND ↓

The payload needs to contain these claims:

name This is the name of the customer.
email This is the email address of the customer.
exp This is the token expiry time. It can't be greater than 2 hours from the time of generation.
Sample code to generate JWT token
Ruby (based on ruby-jwt gem)
Copied Copy
1
2
3
4
5
6
7
require 'jwt' payload = { name: authenticatedCustomerName, email: authenticatedCustomerEmail, exp: (Time.now + 2.hours).to_i } token = JWT.encode payload, widgetSharedSecretKey
EXPAND ↓

NodeJS (based on jwt-simple package)
Copied Copy
1
2
3
4
5
6
7
var jwt = require('jwt-simple'); var payload = { name: authenticatedCustomerName, email: authenticatedCustomerEmail, exp: Math.round(Date.now() / 1000) + 7200 }; var token = jwt.encode(payload, widgetSharedSecretKey);
EXPAND ↓

Python (based on pyjwt library)
Copied Copy
1
2
3
4
5
6
7
8
9
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')
EXPAND ↓

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

This authorization expires based on the time you've set in exp. To ensure a seamless experience for your customers, pass a callback function. The callback function will be automatically invoked before the expiry time you’ve set. The callback function on your side needs to:

  • regenerate the JWT token using the customer’s name and email in the payload on your server, while also specifying the new expiry time. It needs to be signed with the account’s shared secret key.
  • call the authenticate API with the regenerated token.

For instance, 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:

Copied Copy
1
{ freshworks_widget_auth_token: "eyJh.GUuY29tIiwibmF.RIjow" }
EXPAND ↓

then this is a sample of how your implementation of the authenticate API (with the callback function) would look like:

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
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 }); }); }
EXPAND ↓

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

Once you’ve embedded the widget code and authenticated a customer

  • The logged-in customer will be able to view and search only the articles they have access to.
  • The contact form will be prefilled with the customer’s details (name and email address).
  • 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. This can be overridden by the locale parameter.

Logging out customers

When your customers log out of your website, you'll have to log them out of the widget as well. This can be done with the logout API:

Copied Copy
1
FreshworksWidget('logout');
EXPAND ↓

Resetting shared secret key

You can reset the shared secret key from Admin > 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.