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 users open the contact form.

If you'd like to get on the beta for the help widget and try it out,

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.

Copied Copy
1
2
3
4
5
6
7
8
<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 />
EXPAND ↓

Please ensure that the widget's embed code precedes your APIs.

Identify

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

If your users 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.

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

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.

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

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

Hide

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.

Sample
Copied Copy
1
FreshworksWidget('hide', 'ticketForm', ['name', 'email', 'custom_fields.cf_order_id']);
EXPAND ↓

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

Attribute Description
name Name of the customer
email Email address of the customer
custom_fields.cf_name_of_the_field Custom field

Clear

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.

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

Open

To open the widget when a user lands on certain pages or when they perform an action, use this method.

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

Close

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

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

Destroy

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

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

Initialize

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

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

Overview

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 behaviour and force load the widget in a certain language, you can use the locale property.

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 property is useful if you have users 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.

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 Locale Language
ca Catalan cs Czech
da Danish de German
en English es-LA Spanish (Latin America)
es Spanish et Estonian
fi Finnish fr French
hu Hungarian id Indonesian
it Italian ja-JP Japanese
ko Korean nb-NO Norwegian
nl Dutch pl Polish
pt-BR Portuguese (Brazil) pt-PT Portuguese (Portugal)
ru-RU Russian sk Slovak
sl Slovenian sv-SE Swedish
tr Turkish vi Vietnamese
zh-CN Chinese uk Ukrainian
th Thai ro Romanian
zh-TW Chinese (Traditional) lv-LV Latvian
bs Bosnian bg Bulgarian
hr Croatian el Greek
ms Malay lt Lithuanian
sr Serbian

Translate labels

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.

The launcher text will be translated by default. If you'd still like to specify your own label in secondary languages, you can use the launcher property to override it. We recommend you don't add anything more than ten characters for the launcher text.

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 ↓