Hide the widget

1
FreshworksWidget('hide');

1
FreshworksWidget('hide', 'launcher');

Show the widget

1
FreshworksWidget('show');

1
FreshworksWidget('show', 'launcher');

Open the widget

1
FreshworksWidget('open');

Close the widget

1
FreshworksWidget('close');

Destroy the widget

1
FreshworksWidget('destroy');

Initialize the widget

1
FreshworksWidget('boot');

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
FreshworksWidget('open', 'ticketForm', {
  formId: 1234 // Ticket Form ID
});

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
4
5
6
FreshworksWidget('identify', 'ticketForm', {
  name: 'Rachel',
  email: 'rachel@acme.inc',
}, {
  formId: 1234 // Ticket Form ID
});

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
  }, {
    formId: 1234 // Ticket Form ID
  }
});

Accepted values for default fields

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
FreshworksWidget('disable', 'ticketForm', ['subject', 'description', 'priority', 'status', 'group_id', 'product_id', 'type', 'custom_fields.cf_order_id'], {
        formId: 1234 // Ticket Form ID
      });

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
FreshworksWidget('hide', 'ticketForm', ['subject', 'description', 'priority', 'status', 'group_id', 'product_id', 'type', 'custom_fields.cf_order_id'], {
  formId: 1234 // Ticket Form ID
});

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
4
5
6
7
8
FreshworksWidget('hideChoices', 'ticketForm', {
  'priority':[2,3],
  'custom_fields': {
    'cf_issue_category': ['Account cancellation', 'Premium support']
  }, {
    formId: 1234 // Ticket Form ID
  }
});

Accepted values for default fields

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.

Note:
Ticket Form ID parameter is applicable only for Pro and Enterprise plans that have Ticket Forms.
Ticket Form ID parameter is mandatory if multiple forms are associated with the Widget.

1
2
3
FreshworksWidget('clear', 'ticketForm', {
  formId: 1234 // Ticket Form ID
});

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.

Learn more about this API

1
2
3
FreshworksWidget('open', 'article', {
  id: 123 // article ID
});

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.

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>

List of locales

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.

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!"
            }
          }
          });

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"
            }
          }
        });

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:

1
2
3
4
{
  "alg": "HS256",
  "typ": "JWT"
}

The payload needs to contain these claims:

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

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

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

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:

1
{ freshworks_widget_auth_token: "eyJh.GUuY29tIiwibmF.RIjow" }

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

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
    });
  });
}

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

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

1
FreshworksWidget('logout');

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.