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
    8
    9
    <script> <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "https://wchat.freshchat.com", siteId: "UNIQUE_SITE_ID" }; </script> <script src="https://wchat.freshchat.com/js/widget.js" async></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
    2
    3
    4
    5
    6
    7
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "https://wchat.freshchat.com" }; </script> <script src="https://wchat.freshchat.com/js/widget.js" async></script>
    EXPAND ↓

    Logged in User

    FRESHCHAT WEB MESSENGER FOR LOGGED OUT / ANONYMOUS 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
    12
    13
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "https://wchat.freshchat.com", 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="https://wchat.freshchat.com/js/widget.js" async></script>
    EXPAND ↓

    Restoring a User

    If you give an externalId which is a unique identifier in your database, all conversations can be retrieved from all browsers and devices. For example, a user may have visited your site from a work device and held a couple of conversations. When he / she logs in from a different device, the user will be identified and previous conversations will be restored using the restoreId.

    To get the restoreId:

    1. Subscribe to user create by adding a listener to the event and store the restoreId in your database for restoring conversations.

    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
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "https://wchat.freshchat.com", externalId: "john.doe1987", // user's id unique to your system onInit: function() { window.fcWidget.on('widget:loaded', function() { window.fcWidget.user.get().then(function(resp) { var status = resp && resp.status, data = resp && resp.data; if (status === 200) { if (data.restoreId) { // Update restoreId in your database } } }, function(error) { // User Not Created 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="https://wchat.freshchat.com/js/widget.js" async></script>
    EXPAND ↓

    To restore the user:

    2. The init function should be provided with the externalId and restoreId

    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.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "WEB_CHAT_URL", externalId: "john.doe1987", // user's id unique to your system restoreId: "RESTORE_ID", // restore id obtained }; </script> <script src="https://wchat.freshchat.com/js/widget.js" async></script>
    EXPAND ↓

    Setting User Properties

    window.fcWidget.user.setProperties()

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

    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
    <script> window.fcWidget.user.setProperties({ firstName: <fname>, lastName: <lname>, email: <email>, phone: <phone>, phoneCountry: <country_code>, "plan": "Estate", "status": "Active", "Last Payment": "12th August" }); </script>
    EXPAND ↓

    Setting User Events

    Events

    Freshchat allows you 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
    <script> //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>
    EXPAND ↓

    Widget Customisation

    Widget customisation options 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 screeshots of a widget where the values/strings that can be customised are highlighted.

    Sample Code

    Channel Customisation

    CUSTOMIZING WEB WIDGET CHANNELS

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

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

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

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "WEB_CHAT_URL", tags: ["public", "paid"], externalId: <externalId> }; </script> <script src="https://wchat.freshchat.com/js/widget.js" async></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 channel list). For example, if a user is on the 'Payments' page, these tags will show only payment related channels on the Web Messenger. If he's switching to the 'Deliveries' page, Set Tags help show channels relating to deliveries during transition. Once Set Tags are called, the channel list will immediately be updated.

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

    FAQ CustomisationNEW

    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 your web page.
    • 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 Freshcaht 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
    14
    <script> window.fcSettings = { token: "WEB_CHAT_TOKEN", host: "https://wchat.freshchat.com", // Setting FAQ Tags in the object below. faqTags : { // Array of Tags tags : ['paidusers'], // FAQ Tag Type filterType:'article/category' }, }; </script> <script src="https://wchat.freshchat.com/js/widget.js" async></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 channel 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
    <script> window.fcWidget.setFaqTags({ // For ex: ["public", "paid"] tags : ['hello'], filterType:'article/category' }); </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
    <script> window.fcWidget.on("widget:opened", function(resp) { console.log('Widget Opened'); //Function to do some task }); </script>
    EXPAND ↓

    2. widget:closed - Triggers when the widget close

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    <script> window.fcWidget.on("widget:closed", function(resp) { console.log('Widget Closed'); //Function to do some task }); </script>
    EXPAND ↓

    3. widget:loaded - Triggers when the widget loads

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    <script> window.fcWidget.on("widget:loaded", function(resp) { console.log('Widget Loaded'); //Function to do some task }); </script>
    EXPAND ↓

    4. user:created - Triggers when user is created

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    <script> window.fcWidget.on("user:created", function(resp) { console.log('User has been created'); //Function to do some task }); </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
    <script> window.fcWidget.on("unreadCount:notify", function(resp) { console.log(resp); }); </script>
    EXPAND ↓

    6. 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
    <script> //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>
    EXPAND ↓

    7. window.fcWidget.user.create(payload) - Create 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. 403 - User exists. Use clear() user method

    4. 404 - Init not called
    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    <script> window.fcWidget.user.create().then(function() { console.log('User Created'); }, function() { console.log("User Not Created"); }); </script>
    EXPAND ↓

    8. 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
    <script> 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>
    EXPAND ↓

    9. 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
    <script> window.fcWidget.user.clear('<User Identifier>').then(function() { console.log('User cleared'); }, function() { console.log("User Not cleared"); }); </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
    <script> //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>
    EXPAND ↓

    2. window.fcWidget.open(payload)

    Opens the Freshchat Widget with optional parameters including channel id or name.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    <script> if (window.location.href.indexOf('cart') != -1) { window.fcWidget.open({ name: "Checkout" }); //Do Something } else { window.fcWidget.open({ name: "Support" }); //Do Something Else } </script>
    EXPAND ↓

    3. window.fcWidget.close()

    Closes the Freshchat Widget.

    Sample code
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    <script> //On click of a button, close the widget. jQuery('.close_btn').on('click',function() { window.fcWidget.close(); //Do something. }); </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
    <script> //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>
    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
    <script> //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>
    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
    <script> //Check if user is logging out. if (window.location.href.indexOf('logout') != -1) { window.fcWidget.destroy(); //Do Something } else { //Do Something Else } </script>
    EXPAND ↓