Quick Start

In this section, you will learn to build a simple Freshchat app using the following steps.

Step 1: Install NVM

Step 2: Install Node

Step 3: Install the CLI

Step 4: Create your First App

Step 5: Test your App

Step 6: Validate and Pack

Apps built on the Freshworks platform are compatible with the latest two versions of the following browsers.

  • Google Chrome
  • Firefox
  • Edge
  • Safari
  • Internet Explorer - Not supported

Install NVM

It is recommended to use Node Version Manager (NVM) to install Node.js as it enables you to install and work with multiple versions of Node easily.

Check if Node exists in your computer by running the following command: node --version. Uninstall any existing Node version on your computer and remove all folders related to Node and NPM.

You can skip step 1 if you have already installed NVM.

  1. To install NVM:
    1. For Mac/Linux, refer to the steps given here.
    2. For Windows, click here to download and extract the installer from nvm-setup.zip listed under Assets.
  2. To verify the installed nvm version, run the following command. $ nvm --version
Install Node

Next, to install Node.js, follow the given steps.

  1. To install Node (recommended version is 8.10.x) using NVM, run the following command. $ nvm install 8.10

    We support only Node 8.10.x. For more information, see Moving on to Node.js 8.

  2. To verify the installed node version, type the following command. $ node --version

    For Windows, if the node version is not displayed, you may need to enable nvm by running the command: nvm on

  3. To set the default node version with NVM, run the following command: $ nvm alias default 8.10
  4. For Windows, you need to install a few required tools and configurations by using the following command. $ npm install --global --production windows-build-tools For further reference, click here.
Install the CLI

Now, you need to install the Freshworks CLI on your machine to build, test, and publish apps in Freshchat Marketplace.

By installing the CLI, you agree to these Terms and Conditions.

  • To install the CLI, run the following command.
  • Copied Copy
    npm install https://dl.freshdev.io/cli/fdk-5.3.0.tgz -g
  • To verify the version, run the following command.
  • $ fdk version
Create your First App

In this section, you will learn to create a simple app to display the Freshworks logo and name of the user(customer) on the Inbox page.

Open the terminal window, navigate to an empty directory in which you want to create your app, and follow the given steps.

  1. At the prompt, type fdk create
  2. From the product list, select freshchat and press Enter.
A new app is created from the your_first_app template and the following app files appear in the directory.
app/ This directory contains all the files (HTML, JS, CSS, images, library) required for the front-end component of your app. The JS files must follow the ES5 standard.
app/icon.svg This is the product icon file in the app directory created as part of the sample project. You can replace it with your own assets while building your app.
Note: The icon file should be of SVG type with a resolution of 64 x 64 pixels.
app/template.html This file contains the HTML required for the app’s UI which is rendered in an IFrame.
config/ This directory contains installation parameters and OAuth configuration files.
config/iparams.json This file contains all the installation parameters which users will have to specify/set when they install the app. For more information on installation parameters and related APIs, see Installation Parameters.
config/iparam_test_data.json This file contains the installation parameter values which you will specify to test the app on your machine.
manifest.json This file contains details about your app and its characteristics.
README.md This file contains any additional instructions or specifications which developers might want to outline.

If you use React, Ember, Vue, or any other front-end framework, include the source files of your app in the src directory. This will ensure quick app reviews.

Test your App

For testing, we recommend that you use the latest version of Chrome browser. To test your app on your machine, follow the given steps.

  1. Open your console, navigate to your project folder, and execute the following command. $ fdk run
  2. Log in to your Freshchat account (if you do not have a Freshchat account, sign up here).
  3. In the Inbox page, in the address bar, append the URL with ?dev=true. For example, the URL should look like this: https://web.freshchat.com/a/1234/inbox/1/0/conversation/9876?dev=true.
  4. When testing the app on your machine, you may see a shield icon in the browser address bar. Clicking the icon will display a warning message as the Support portal runs on HTTPS while the server used for testing runs on HTTP.
  5. Click Load unsafe scripts to continue testing.
  6. From the Conversation panel, click any conversation. The rendered app is displayed on the right side of the page as shown in the image.
  7. Note:
    While testing your app, if you have any issues that require the Support team, attach detailed logs of the output along with your support ticket for a quick resolution.

Validate and Pack

To check if the app is error-free and package it for submission, follow the given steps.

  1. Navigate to your project folder and validate the code by using the following command. $ fdk validate [--app-dir DIR] Here, DIR is the relative or absolute path to the project directory.
  2. Once validation is successful, you can pack the project by running the following command. $ fdk pack [--app-dir DIR] The pack command generates the dist/my_first_app.zip file which you need to upload in the Developer portal to be published in Freshchat Marketplace. For information on the submission process, see the Types of Apps section in Marketplace Listing.