Overview

Freshchat now lets you embed a widget in any site - the Web Messenger. The Web Messenger lets you engage with and manage queries from your website visitors - both anonymous and logged in users. It will appear as a widget on the bottom right corner of your web page. Every message that comes in from the Web Messenger will be treated as a separate conversation in the Freshchat inbox.

Setup

Get widget code:

  • Log in to your Freshchat account as Admin
  • Go to Settings
  • Choose Web Messenger
  • You will be directed to the Web Messenger settings page under the Getting Started tab.
  • To chat with your website visitors, you will have to embed the widget on your website

  • Copy the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger widget on your website

  • Installing the Freshchat Web widget is a quick process that involves copying and pasting the code snippet to your web app or website. Embedding the Web Messenger lets you speak to and manage queries posed by both logged-out and logged-in users who visit your website.
  • Multiple Sites

    Using the same Freshchat account on multiple sites

  • If you are a multi-brand commerce company or simply have multiple sites you need to use Freshchat on - while still using the same account and team to engage with your customers across these sites, Freshchat offers a way for you to separate the chat conversations / users across these sites.

  • By declaring a site ID as part of the configuration as shown below, users across the sites with different site IDs will be treated as different users, while all pages/sites using the same site ID will have a common user/common conversations.
  • Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    <script> window.fcWidgetMessengerConfig = { externalId: "15jun@gmail.com", siteId: "UNIQUE_SITE_ID" } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Anonymous User

    FRESHCHAT WEB MESSENGER FOR LOGGED OUT / ANONYMOUS USERS:

  • To embed the widget on your website, copy the code snippet from the Freshchat Settings page as seen in the above image and paste the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger on your website
  • Sample code
    Copied Copy
    1
    <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Logged in User

    FRESHCHAT WEB MESSENGER FOR LOGGED IN USERS:

  • To embed the widget on your website, copy the code snippet from Freshchat Settings page and paste the JavaScript code snippet before the </body> tag on every page to initialize the Web Messenger on your website

  • Additionally you can store an "externaIId" with Freshchat. This externalId is unique to your system. It can be a user's handle or the user's phone number or email. This will be used to restore user conversations securely if they login from a different computer or browser.

  • Note: The example user data has to be replaced with real data that helps in getting actual user information on all of your web pages.

  • You will now be able to see the Freshchat Web Messenger widget on all pages of your website
  • Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcWidgetMessengerConfig = { externalId: "john.doe1987", // user’s id unique to your system firstName: "John", // user’s first name lastName: "Doe", // user’s last name email: "john.doe@gmail.com", // user’s email address phone: "8668323090", // phone number without country code phoneCountryCode: "+1" // phone’s country code } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Restoring a User

    You can restore user conversations for logged in users, every time they initiate a conversation from a different browser or device. To do so, for every user, an unique external ID and restore ID has to be defined.

    Two attributes needed to restore a user conversation,

    • External ID - The external ID has to be unique to each logged in user. This information should be passed to Freshchat from your side. For example, user email ID can be an external ID.

    • Restore ID - This will be created by Freshchat when a logged in user (from the customer’s website) initiates a conversation on Freshchat messenger for the first time. Restore ID is also unique to each created user. This ID will be passed to your website on the user creation callback function. You have to store this ID in your database, once it is passed by Freshchat. The next time the website user pings using the Freshchat messenger from a different browser or mobile app, this restore ID, along with the external ID must be passed from your side to Freshchat for the user conversation to be restored. Otherwise every conversation initiated by the user on a new / fresh browser session will create a new user and the conversation history will be lost.

    Steps:

    1. Paste the entire script from below on your website.

    Note: Restore ID won’t be available when a website user logs in for the first time. It gets created only after a user initiates a conversation on the Freshchat messenger for the first time.

    2. Define external ID. This step is mandatory.

    Note: External ID should be unique for each user. Example: Email ID of each user can be defined as their external ID.

    3. init() and fcWidget.user.get() start running when a user logs in for the first time on your website.

    4. When a logged in user sends a message on Freshchat messenger for the first time, the user gets created in Freshchat, with information from fcWidget.user.setProperties() and call back function for user creation runs.

    5. Parallely, restore ID is created in Freshchat for that user and will be available on fcWidget.on(‘user created’) event.

    6. In if (data.restoreId) condition, add your code to save the restore ID from Freshchat to your database.

    7. When a user starts a conversation from a different browser or device next time, restore ID should be fetched from your database and sent to Freshchat, to restore user conversation. To do this, you have to add code which fetches the restore ID from your database before init().

    8. Finally, pass this restore ID to Freshchat in init().

    Sample code
    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
    31
    32
    33
    <script> var restoreId = RESTOREID //Which need to be fetched from your DB window.fcWidgetMessengerConfig = { externalId: "john.doe1987", // user's id unique to your system restoreId: restoreId ? restoreId : null } window.fcWidget.user.get(function(resp) { var status = resp && resp.status, data = resp && resp.data; if (status !== 200) { window.fcWidget.user.setProperties({ firstName: "John", // user's first name lastName: "Doe", // user's last name email: "john.doe@gmail.com", // user's email address phone: "8668323090", // phone number without country code phoneCountryCode: "+1", // phone's country code plan: "Estate", // user's meta property 1 status: "Active", // user's meta property 2 "Last Payment": "12th August" // user's meta property 3 }); window.fcWidget.on('user:created', function(resp) { var status = resp && resp.status, data = resp && resp.data; if (status === 200) { if (data.restoreId) { // Update restoreId in your database } } }); } }); </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Setting User Properties

    Default properties and Custom Properties

    Use this command to set user properties on Freshchat for users.

    Note that default properties can be set directly on the config object, whereas custom properties need to be set on the meta object as shown in the code snippet below.

    The default properties are:
    • firstName
    • lastName
    • email
    • phone

    Incase you would like to recieve more custom user properties, the properties have to first be set in the CRM Contact page. Go to Admin Settings and scroll down to CRM Modules and Automation. Click Contacts. All the properties expected to be passed during initialization can be managed from here. New properties have to be created and set here first.

    For detailed information on how to create and manage custom fields in CRM Contacts, Click here

    While passing the values during initialization in meta object (see code snippet below), use the respective "Internal name" field as seen in the screenshot below. By default, custom properties start with "cf_".

    Note that any other fields passed as properties which are not in the CRM Contact properties already, they will be ignored.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <script> window.fcWidgetMessengerConfig = { firstName: <fname>, lastName: <lname>, email: <email>, phone: <phone>, meta: { linkedin: <linkedin_data>, // Note that you can specify the "Internal name" (from CRM Contact page) for any property you would like to set cf_custom_property: <custom_property> } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Tracking Custom Events

    Custom events are the events that are sent by you to the web application, these events are user-defined. This can be any action performed by your users on your website/web apps such as Added to wishlist, Added to cart, Product ordered, Product purchased, Payment failed, etc, you can define these events based on your needs.

    Tracking Custom Events through Freshchat

    Freshchat allows you to track any events performed by your users. It can be anything, ranging from updating their profile picture to adding 5 items to the cart. You can use these events as context while engaging with the user. Events can also be used to set up triggered messages or to segment users for campaigns.

    window.fcWidget.track(eventName, payload)

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    <script> window.fcSettings = { onInit: function() { //After Page and Widget is Loaded. //Check if widget is loaded using the isLoaded Condition //Event name add_to_cart can also be set to your preference. window.fcWidget.track('add_to_cart', { //Key and value can be anything relatable to your web app. cartValue: 5000, lastItemCategory: 'electronics' }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Track Custom Events using CRM Tracking Code

    Custom Events in CRM have an event name (like "Added to cart" or "Downloaded white paper") and a list of event properties (like email, product name, price, or return date). Use properties to analyze your events via segments, marketing journeys or the activity timeline.

    Note: Email address is mandatory for tracking custom events through CRM Tracking Code. Check the sample code below.

    FM.trackCustomEvent(eventName, eventProperties)

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    <script> FM.trackCustomEvent("Added to cart", { "email": "david.thompson@sample.com", "price": 100.21, "currency": "USD", "is_mobile_transaction": true, "return date": "2019-12-30" }) </script>
    EXPAND ↓

    Widget Customisation

    Widget customisation allows you to set up your Freshchat web widget with customisations such as custom strings or color or chat backgrounds.

    Screenshots

    Below are a few screenshots of a widget where the values/strings that can be customised are highlighted.

    Sample code with all available customisations

    Note: Please note that the older version of the code had {{time}} which will also work properly.

    Sample code for Freshchat to open automatically into the FAQ screen

    Sample code to hide agent details and disable event tracking

    Font Customisation

    Freshchat's web widget now supports the ability to use a custom font. Just provide the font name and font URL within the headerProperty object in the widget config. If it is a hosted font such as Google Fonts or Adobe Typekit, the sample code will look like this.

    If you'd like to use a commonly available font such as Arial or Times New Roman, you may provide that for fontName. In that case, fontUrl is not needed.

    Note: If the widget is unable to load the custom font, it would default to the local system font.

    Masking Sensitive Information

    Masking feature ensures that no sensitive information is passed via the Freshchat Widget, for example, Credit Card information. You could specify a list of texts to mask, which also supports Regular Expressions (RegEx).

    mask_text should be a array and the object should contain both regex_to_hide and replace_text. Check the sample code below.

    • regex_to_hide - Regex which need to match in the string
    • replace_text - Text which want to be shown instead of the actual text

    Disabling Notifications

    Freshchat now allows you to disable notifications on the Widget. Use this config to disable both Push Notifications as well as Sound Notifications on recieving new messages on the Widget.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    <script> window.fcWidgetMessengerConfig = { config: { disableNotifications: true } ); </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Channel Customisation

    CUSTOMIZING WEB WIDGET TOPICS

  • Tags for topics help customize widget topics according to levels and types of customers. There will arise various scenarios in which you will need to show different topics to different users or a subset of topics to a subset of users.

  • For example: For your paid customers you might want to add an additional "VIP Support" Topic. Or different topics to your users in Europe versus your users in the USA. You can add tags to topics and you can then use these tags to decide which topics to show to whom.
  • Set Tags in widget init

    If the tags are set when the init is set, relevant topics will appear when the widget loads.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    <script> window.fcWidgetMessengerConfig = { tags: ["public", "paid"], externalId: <externalId> } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Set Tags during page transition:

    The tags can also be set later for specific web pages using Set Tags (only the latest selection will be updated for the topic list). For example, if a user is on the 'Payments' page, these tags will show only payment related topics on the Web Messenger. If he's switching to the 'Deliveries' page, Set Tags help show topics relating to deliveries during transition. Once Set Tags are called, the topic list will immediately be updated.

    Sample code
    Copied Copy
    1
    2
    3
    <script> window.fcWidget.setTags(tags); // For ex: ["public", "paid"] </script>
    EXPAND ↓

    Multi LanguageNEW

    Multi Language Support

  • Freshchat provides multilanguage support so that the Web Widget is automatically displayed in the language of the end user. The list of all supported languages and their keys are provided in the table below.
  • Supported Languages

    Language Code Language
    ar Arabic Language (RTL)
    en English
    ca Catalan
    zh-HANS Chinese (Simplified)
    zh-HANT Chinese (Traditional)
    cs Czech
    da Danish
    nl Dutch
    de German
    et Estonian
    fi Finnish
    fr French
    hu Hungarian
    id Indonesian
    it Italian
    ko Korean
    lv Latvian
    nb Norwegian
    pl Polish
    pt Portuguese
    pt-BR Portuguese - Brazil
    ro Romanian
    ru Russian
    sk Slovak
    sl Slovenian
    es Spanish
    es-LA Spanish - Latin America
    sv Swedish
    th Thai
    tr Turkish
    uk Ukrainian
    vi Vietnamese

  • The language is selected based on priority and is explained below.
  • 1. Configured Language

    The highest priority is given to the language that is specified when the widget is initalized. This can be done when you add the Freshchat widget code. For instance, in the below code the key locale is used to set the language when the widget is initalized. For the sample code snippet please go here.

    2. Default Language

    The lowest priority is the Default Language which is set in your Freshchat account. If none of the three values below are not available Freshchat will automatically load the widget the default language. This will be the primary language that is specified on your Freshchat Account.

    3. Operating System Language

    If the browser language is not available, then the next step for fall back is the Operating System Language.

    4. Browser Language

    If there is no language specified on config, the widget will pick the browser language automatically. If there are multiple languages set on the browser it will take the primary language always.

    Code to set Locale on Freshchat

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <html> <head> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </head> <body> <script> window.fcWidgetMessengerConfig = { locale: "fr" } </script> </body> </html>
    EXPAND ↓

    If you want the Freshchat widget's language to be changed dynamically based on user selection such as language dropdown, the locale has to be set when the dropdown is changed. You will have to use the command window.fcWidget.user.setLocale('en') to specify the language in that case. Please refer to the sample code below for better clarity.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    <html> <head> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </head> <body> <script> window.fcWidgetMessengerConfig = { //Widget aleady initalized without locale } </script> <script> //Consider a dropdown with id #lang-btn to select the language $('#lang-btn').on('change',function() { var selectedLanguage = jQuery(this).val(); //Setting the Widget Locale window.fcWidget.user.setLocale(selectedLanguage); }); </script> </body> </html>
    EXPAND ↓

    FAQ Customisation

    CUSTOMIZING WEB WIDGET FAQs

    Tags can be added to FAQ Categories or FAQ Article while creating or adding them. FAQ Tags allow you to filter and display specific FAQs or Categories on web pages.

    • For example, a specific set of FAQ categories/articles regarding pricing and billing can be displayed on the pricing page of your website.
    • Or a specific set of FAQs can be displayed for Paid Subscribers with additional information on the premium features.

    How category and article tags work?

    There are two types of FAQ Tags, which can be set to filter FAQs or Categories.

    • Category tags ( filterType:'category' ) - Category Level Tags can be used to filter FAQ Categories.
    • Article tags ( filterType:'article' ) - Article Level Tags works on two levels. This means if the given tag is associated with any category all the articles in that category will be shown. Then the Article Tags will look for articles with the associated tags under all FAQ Categories.

    Set FAQ Tags on widget init

    If the FAQ tags are set on initialisation of the Freshchat widget, relevant FAQ categories/articles will be loaded when the widget is opened.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <script> window.fcWidgetMessengerConfig = { // Setting FAQ Tags in the object below. faqTags : { // Array of Tags tags : ['paidusers'], //For articles, the below value should be article. //For article category, the below value should be category. filterType:'category' //Or filterType: 'article' } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Set FAQ Tags during page transition:

    The tags can also be set later for specific web pages using setFaqTags (only the latest selection will be updated for the topic list). For example, if a user is on the 'Payments' page, you can set FAQ Tags to display payment related FAQs. If a user switches to the 'Deliveries' page, this funciton will help show FAQs relating to deliveries during transition. Once setFaqTags are called, the FAQ list will immediately be updated.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcWidget.setFaqTags({ // For ex: ["public", "paid"] tags : ['hello'], //For articles, the below value should be article. //For article category, the below value should be category. filterType:'article' //Or filterType: 'category' }); </script>
    EXPAND ↓

    Showing FAQs in Fullscreen Popups

    FAQs could also be shown in a full page popup mode. To enable this feature, set faqPopupView to true as below.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    <script> window.fcWidgetMessengerConfig = { config: { faqPopupView: true } ); </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Messenger Events

    Responses for the first 4 commands

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success

    2. 400 - Backend Error

    3. 401 - Init not called

    4. 403 - ExternalId already used. Use clear() user method

    5. 404 - Init not called / Restore ID is invalid
    data Object 1. undefined - With 200 in status, user not created yet
    - Without 200 in status, error

    2. { restoreId: <value> } Use to synchronise later

    1. widget:opened - Triggers when the widget opens

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("widget:opened", function(resp) { console.log('Widget Opened'); //Function to do some task }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    2. widget:closed - Triggers when the widget close

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("widget:closed", function(resp) { console.log('Widget Closed'); //Function to do some task }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    3. widget:loaded - Triggers when the widget loads

    Alternatively you could also pass a callback function during Widget initialization, to subscribe to Widget loaded event. Pass the callback as a parameter to window.fcWidgetMessengerConfig = { onLoad: callback_function } for the same.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("widget:loaded", function(resp) { console.log('Widget Loaded'); //Function to do some task }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    4. user:created - Triggers when user is created

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("user:created", function(resp) { console.log('User has been created'); //Function to do some task }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    5. unreadCount:notify - To check if there are unread messages

    Usage

    This event will give you the number of unread messages. Mostly used when the default Freshchat bubble is hidden and a custom button is used.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("unreadCount:notify", function(resp) { console.log(resp); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    6. message:sent - Triggers when a message in sent from the Widget

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("message:sent", function(data) { console.log('A message has been sent from the Widget', data); //Do something on message sent }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    7. message:received - Triggers when a message in received on the Widget

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("message:received", function(data) { console.log('A message has been received on the Widget', data); //Do something on message received }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    8. csat:received - Triggers when a CSAT is received

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("csat:received", function(data) { console.log('CSAT received', data); // Do something on CSAT recieved }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    9. csat:updated - Triggers when the recieved CSAT is updated

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("csat:updated", function(data) { console.log('CSAT updated', data); // Do something on CSAT update }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    10. widget:destroyed - Triggers after the window.fcWidget.destroy() call is successful

    window.fcWidget.destroy() is the method that is used to destroy an already loaded Widget. On successful removal of the Widget from the DOM, this event (widget:destroyed) would be published. Subscribe to this event to do any cleanup after the Widget is fully destroyed and removed.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("widget:destroyed", function() { console.log('After widget destroyed'); // Do some clean-up here }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    11. download:file - Triggers after the user downloaded an asset sent by the Agent

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("download:file", function(response) { if (response.success) { console.log('File URL downloaded by User', response.data.url); } }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    12. user:cleared - Triggers after the user is cleared

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("user:cleared", function() { // do some cleanup after user cleared console.log('User Cleared'); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    13. dialog:opened - Triggers if a message was received when the widget was closed (minimized) and the message dialog window opened

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("dialog:opened", function() { // Dialog opened console.log('Message Dialog Opened with message from Agent'); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    14. dialog:closed - Triggers if the message dialog was closed

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <script> window.fcSettings = { onInit: function() { window.fcWidget.on("dialog:closed", function() { // Dialog closed console.log('Message Dialog Closed by the User'); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Messenger API

    1. window.fcWidget.isOpen()

    To check whether the Freshchat Widget is open.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    <script> window.fcSettings = { onInit: function() { //Returns the current window state of the freshchat widget in boolean. //TRUE - Opened / FALSE - Closed jQuery('#myDiv').on('click',function(event, data) { if (window.fcWidget.isOpen() != true) { window.fcWidget.open(); //Or do something else :) } }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    2. window.fcWidget.open(payload)

    Opens the Freshchat Widget with optional parameters including topic id or name.
    The replyText parameter can be used to set up custom text in the text area of the widget.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    <script> window.fcSettings = { onInit: function() { if (window.location.href.indexOf('cart') != -1) { window.fcWidget.open({ name: "Checkout", replyText: "Thank you for the help." }); //Do Something } else { window.fcWidget.open({ name: "Support", replyText: "Thank you for the help" }); //Do Something Else } } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    3. window.fcWidget.close()

    Closes the Freshchat Widget.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <script> window.fcSettings = { onInit: function() { //On click of a button, close the widget. jQuery('.close_btn').on('click',function() { window.fcWidget.close(); //Do something. }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    4. window.fcWidget.isInitialized()

    To check if the Freshchat Widget has already been initialised.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    <script> window.fcSettings = { onInit: function() { //Returns TRUE if the init method is already called else returns FALSE if (window.fcWidget.isInitialized() == true) { console.log('Widget already initialised'); //Do Something } else { console.log('Widget Not Initialised'); //Do Something Else } } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    5. window.fcWidget.isLoaded()

    To check if the Freshchat widget has completed loading.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    <script> window.fcSettings = { onInit: function() { //Returns TRUE if widget has completed loading else returns FALSE if (window.fcWidget.isLoaded() == true) { console.log('Widget already loaded'); //Do Something } else { console.log('Widget Not Loaded'); //Do Something Else } } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    6. window.fcWidget.destroy()

    Removes the widget. Widget will have to be re-initalized again to be shown.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    <script> window.fcSettings = { onInit: function() { //Check if user is logging out. if (window.location.href.indexOf('logout') != -1) { window.fcWidget.destroy(); //Do Something } else { //Do Something Else } } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    7. window.fcWidget.hide()

    Hides the widget if it is visible.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { onInit: function() { window.fcWidget.hide(); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    8. window.fcWidget.show()

    Shows the widget if it is hidden.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { onInit: function() { window.fcWidget.show(); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    9. window.fcWidget.setExternalId()

    Set the External ID dynamically. Check the 'Restoring a User' section

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { onInit: function() { window.fcWidget.setExternalId('externalId'); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    10. window.fcWidget.setConfig(payload)

    The init payload can be set dynamically using this API if the Widget is already inited using window.fcWidget.init()

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { onInit: function() { window.fcWidget.setConfig(payload); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    11. window.fcWidget.trackPage(url, title)

    This API can be used to track the different page visits done by the User. Call this API with the url and title

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { onInit: function() { window.fcWidget.trackPage(url, title); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script> </script>
    EXPAND ↓

    User API

    1. window.fcWidget.user.get() - Get User Promise

    Response

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success

    2. 401 - User not created
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    <script> window.fcSettings = { onInit: function() { //After Widget Open/Init or loaded, getting User. window.fcWidget.user.get().then(function(result) { console.log(result); var userInfo = result.data; //Do Something }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    2. window.fcWidget.user.create(payload, callback) - Create User if it doesn't exist

    Response

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success

    2. 401 - User not created

    3. 403 - User exists. Use clear() user method

    4. 404 - Init not called
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    <script> window.fcSettings = { onInit: function() { window.fcWidget.user.create({ firstName: 'John', lastName: 'Doe', email: 'name@company.com', meta: { userproperty1: 'value', userproperty2: 'value', userproperty3: 'value' } }, function(data) { console.log('User created', data) }) } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    3. window.fcWidget.user.update(payload) - Update User Promise

    Response

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success

    2. 401 - User not created

    3. 400 - Backend error
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    <script> window.fcSettings = { onInit: function() { window.fcWidget.user.update({ firstName: 'John', lastName: 'Doe', email: 'name@company.com', meta: { userproperty1: 'value', userproperty2: 'value', userproperty3: 'value' } }).then(function(response) { console.log(response); } } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    4. window.fcWidget.user.clear() - Clear User Promise

    Response

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success

    2. 401 - User not created

    3. 400 - Backend error

    4. 404 - Init not called
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <script> window.fcSettings = { onInit: function() { window.fcWidget.user.clear().then(function() { console.log('User cleared'); }, function() { console.log("User Not cleared"); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    5. window.fcWidget.user.isExists() - User exists Promise

    Response

    Properties Type Description
    success Boolean TRUE - Success (200), FALSE - Error (Not 200)
    status Var 1. 200 - Success getting data

    2. 401 - User

    3. 400 - Backend error

    4. 404 - Init not called
    data Boolean true or false depening on whether a user is created on Freshchat end
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <script> window.fcSettings = { onInit: function() { window.fcWidget.user.isExists().then(function(data) { console.log('User data', data); }, function() { console.log("Error fetching user); }); } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    Domain Whitelisting

    Enable Freshchat only in certain Domains

    If you would like to restrict showing the Freshchat Widget only on specific domains, please reach out to support@freshchat.com with details of your account and the list of domains to whitelist.

    JWT Authentication

    Enabling user authentication using JSON Web Token

    Freshchat uses JSON Web Token (JWT) to allow only authenticated users to initiate a conversation with you through the Freshchat messenger. Freshchat sends a callback (along with the user’s authentication status) to let you know about any event with respect to the messenger and user’s authentication status.

    Once the user gets authenticated on your system and tries to initiate a conversation, your system communicates the encrypted key to Freshchat to allow or restore conversations. This way, the authenticated user can engage in a secure conversation until the end of a session. This will also prevent any third party from impersonating your users.

    Note:

    As a first step towards enabling JWT Authentication for users, please contact support@freshchat.com to convert your freshchat account to a JWT enabled account

    Overview of JWT user authentication in Freshchat

    Once you enable user authentication for a particular user, an encrypted key is generated from your end and passed on to Freshchat. Subsequently, whenever the user logs into your system and initiates a conversation on Freshchat, Freshchat receives an encrypted SSH-keygen command to decrypt the authentication information, and thereby allow authenticated users to continue the conversation.

    What happens during JWT user authentication

    1. 1. A user tries to initiate a chat session by clicking on the chat widget.

    2. 2. Freshchat requests a signed JWT token containing user data from your API (encrypted with the public key).

    3. 3. Freshchat then initializes the chat by passing along the JWT token to the FreshChat API

    4. 4. FreshChat API receives the token, parses the user details from the JWT payload and then grants the user a chat session.

    Enabling JWT User Authentication

    Let us look at how to enable JWT Authentication for Web and Mobile usecases:

    Web Application

    Freshchat lets you decide what kind of users (logged-in/logged-out) can be allowed to initiate a chat with you. The information required by Freshchat for logged-in users is different from logged-out users. Let’s look at both the processes separately.

    Logged-in users

    • When a logged-in user initiates chat, Freshchat will require the ReferenceID and JWT token from your end.

    • Freshchat checks if the ReferenceID is present for a user. Based on this, the JWT token generated by you will be shared with the Freshchat messenger through init using a placeholder.

    • The JWT token will be decrypted to authenticate the user and restore their conversations.

    • If authentication fails, Freshchat will continue to re-authenticate the user (this re-authentication depends on the time set by you and can be limited from your end by customizing the code and adding a timer or a loop limiter to the code).

    • Each time the page is refreshed after re-authentication fails, init will be called automatically and Freshchat will try to re-authenticate the user(again, the number of times can be limited by Customer).

    Logged-out users

    • These are unidentified users for whom a ReferenceID will not be available. So, based on the code, Freshchat will be calling init, while simultaneously calling authenticateUser(data).

    • This, in turn, will get the universally unique identifier (UUID) from Freshchat messenger, using window.fcWidget.user.getUUID(), which will be signed in your backend.

    • The signed UUID will be used by window.fcWidget.authenticate(signedUUID); to authenticate the user.

    • Once the user is authenticated, the conversation screen will load.

    • If the user is not authenticated, re-authentication will be attempted each time a new JWT is generated.

    Mobile Application

    • When a user initiates chat, Freshchat.getFreshchatUserId() is called and the UUID gets returned.

    • The UUID is then sent to your backend.

    • Your application backend should generate JWT with UUID and the ReferenceID.

    • Your mobile App gets the token and checks Freshchat.getUserIdTokenStatus().

    • If the status of the token ID is set, then Freshchat authenticates the user and restores the conversation. If not, it calls Freshchat.setUserWithIdToken(Token).

    Note:

    A token that does not have a Reference ID & UUID will be rejected. If a user with a given Reference ID is found, the user is updated with details from the token and conversations get restored on the SDK screen. If no user is found with the Reference ID, the user will be created when they send in a message.

    Technical Implementation

    This section is for the team in the company responsible for the companys JWT authentication system. It provides details about the Freshchat JWT User authentication implementation.

    JWT Algorithm

    Specify RS256 as the JWT algorithm in the header of your JWT payload

    {
     "alg": "RS256",
     "typ": "JWT"
    }

    JWT Attributes

    Send attributes to Freshchat as a base64-encoded hash (Ruby) or dictionary (Python). Example using Ruby:

    Freshchat requires a reference-id to uniquely identify the user from your system. Beyond the required attributes listed below, you may optionally send additional user profile data. This data is synced between your user management system and Freshchat.

    Freshchat_uuid is an ID generated by the Freshchat SDK/WebWidget, to be invoked by the integrating website/mobile app and to be included in the generation of the JWT for the user.

    • iat
    • Reference_id
    • freshchat_uuid
    • email
    • first_name
    • last_name
    • phone_number

    Generating SSH key

    Key generation command on Linux and Mac OSX

    We use the ssh-keygen command to generate an RSA public key private key pair with 2048 bits as key size and admin email id as the comment.

    The ssh-keygen command is part of the OpenSSH suite available form https://www.openssh.com. Download and install OpenSSH for your respective OS if you dont have it installed already

    ssh-keygen -t rsa -b 2048 -C admin_email_id

    Parameters to be sent in JWT Token:

    Logged-in Users

    {
     reference_id,
     freshchat_uuid,
     iat,
     exp,
     email,
     name,
     custom_meta,
     signature
    }

    reference_id is provided by the customer and is used to restore the conversation. Only freshchat_identifier and signature are mandatory

    Logged-out Users

    {
     freshchat_uuid,
     Iat,
     exp,
     custom_meta,
     signature
    }
    Sample code
    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
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    <html> <body> <script> window.fcSettings = { onInit: function(){ function authenticateUser(userData) { let authenticateCB = (uuid) => { // Signed UUID Hardcoded. Call Customer backend and generate the signed uuid from uuid let signedUUID = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGH**********"; window.fcWidget.authenticate(signedUUID); }; if (userData && userData.freshchat_uuid) { authenticateCB(userData.freshchat_uuid); } else { // Generate UUID and create new user window.fcWidget.user.getUUID().then((resp) => { let uuid = resp && resp.data && resp.data.uuid; if (uuid) { authenticateCB(uuid); } }); } } window.fcWidget.on("frame:statechange", function(data) { if (data.success === false && data.data.frameState === "not_authenticated") { authenticateUser(data); } }); window.fcWidget.on("user:statechange", function(data) { if (data.success) { let userData = data.data; // authenticate user success if (userData) { if (userData.userState === "authenticated") { console.log("User Authenticated"); } if (userData.userState === "created") { console.log("User Created"); } if (userData.userState === "loaded") { console.log("User Loaded"); } if (userData.userState === "identified") { console.log("User Identified"); } if (userData.userState === "restored") { console.log("User Restored"); } } } else { let userData = data.data; if (userData) { if (userData.userState === "not_loaded" || userData.userState === "unloaded" || userData.userState === "not_created" || userData.userState === "not_authenticated") { authenticateUser(userData); } } } }); } } var userReferenceId; // Call Customer backend and get the user reference id // If user exists in Customer database if (userReferenceId) { // Call Customer backend and get the signature for userReferenceId window.fcWidgetMessengerConfig = { jwtAuthToken: "XYZ.ABC.DEF" // Placeholder for signature. Use the generated one from backend which includes reference_id & user properties } # Append the CRM Tracking Code Dynamically var script = document.createElement('script'); script.src = '//fw-cdn.com/1*****7/2*****4.js'; // Replace this placeholder string from your account. Go to Admin Settings > Chat Widget Customization > Web (Embed Code) script.setAttribute('chat', 'true'); document.body.appendChild(script); } else { # Append the CRM Tracking Code Dynamically var script = document.createElement('script'); script.src = '//fw-cdn.com/1*****7/2*****4.js'; // Replace this placeholder string from your account. Go to Admin Settings > Chat Widget Customization > Web (Embed Code) script.setAttribute('chat', 'true'); document.body.appendChild(script); } </script> </body> </html>
    EXPAND ↓

    Widget Lite (Beta)

    Though the Freshchat Widget size is competitively developed, we want to ensure that the website load time and performance score of our customers’ websites are not impacted because of the Freshchat widget. Widget Lite will ensure that the website’s SEO performance is not impacted and the site can get a better ranking in Performance Scores and Core Web Vital Metrics (Eg. In Lighthouse Reports, Page Speed Insights).

    Widget Lite can be enabled by passing eagerLoad as true during the Chat initialisation, as shown in the code snippet below.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    <script> window.fcWidgetMessengerConfig = { config: { eagerLoad: true } } </script> <script src='//fw-cdn.com/1*****7/2*****4.js' chat='true'></script>
    EXPAND ↓

    How it works

    By enabling Eager Load as part of your widget code, the widget icon will load when the website loads. But other widget elements, such as icons, text, and other elements within the Freshchat widget screen, which might contribute to a load time of the Freshchat Widget, will load only after the page load.

    These widget properties will only start loading when the user is active on your website(will not load if the user has not moved their pointer/scrolled) - this will ensure that if the user is idle when the page loads, their bandwidth is focused on loading the page and not the Freshchat widget elements.

    Additionally, if the user is loading your website on a new tab from a backlink, the widget will not load unless the user is on that new tab. These changes will ensure that the page load is not impacted because of the time it takes to load the elements in the Freshchat widget window.

    Things to be Aware of while using Widget Lite:

    If you have configured triggered campaigns to be sent out to your web visitors based on the time they have spent, there might be a delay in triggering those campaigns for roughly about 5-10% of the web visitors depending on their bandwidth. This is because Freshchat can start tracking the time spent only after the widget elements load. As this will happen only after your website load, the campaign might take longer to trigger for some users.

    Note: Widget Lite is still in Beta testing, very rarely there can be some unforeseen issues, which we request you to report to our team by sending an email to support@freshchat.com. We will work with you in resolving these issues.