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.

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' }; </script> <script type='text/javascript' src='https://widget.freshworks.com/widgets/12000000025.js' async defer /> <script> !function(){if("function"!=typeof window.FreshworksWidget){var n=function(){n.q.push(arguments)};n.q=[],window.FreshworksWidget=n}}() </script>
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.
* 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 ↓