Freshworks Developer Platform Docs

Marketplace Platform v2.3 deprecation:We’re continuing to improve the Marketplace Platform to deliver stronger security, better performance, and new capabilities. As part of this evolution, Marketplace Platform v2.3 will be deprecated. To learn the dates and next steps, see Migration guide.

Server Method Invocation (SMI) facilitates the front-end component of an app to invoke a server method that runs as a serverless component.

To build an SMI app,

Create a serverless app.
Configure the app manifest.
Register the SMI functions: In the manifest.json > product.<product-name>.functions object, specify all the server methods that are called from the front-end component of the app, to allowlist the methods.
Navigate to server.js and enter your app logic.
1. Navigate to the root folder and create an app folder to host the app’s front-end files. For information on the app folder structure, see Create a front-end app.
2. In the app folder, create an app.js file and enter the app logic for the front-end component. Use our front-end methods - app lifecycle methods, data methods, events methods, and interface methods - to formulate your app logic.
3. Invoke the serverless component: In app.js, specify the method to invoke the serverless component and pass an appropriate payload to the serverless component. By default, the serverless environment adds the installation parameters set during app installation to the payload.
4. Navigate to server.js and and enter your app logic. Use our serverless events - app set-up events, product events, external events, and scheduled events - to formulate your app logic.
5. Define the server methods: In server.js, define the server method (SMI function) that is allow-listed in the app manifest and called from the front-end component. In this server method, include the app logic that runs based on the payload passed and the renderData() method to return success and failure responses to the front-end component.
Use our developer tooklit to help solve specific requirements of your app.
Use our app UI guidelines or Crayons (the Freshworks component library) to construct your app’s UI.
Configure app settings.

Notes:

The rate limit for the serverless component is 50 triggers per minute.
The payload passed to the severless component should not exceed 100 KB.
The default app execution timeout is 20 seconds. If the request timeout is increased to 20, 25, or 30 seconds, the app execution timeout is extended to 40 seconds.
To know all the platform restrictions and constraints, see Rate limits and constraints.

Configure manifest and register SMI functions

After creating a serverless app’s files, to configure the app manifest for an SMI app , from the app’s root directory, navigate to manifest.json.

App manifest attributes - description and how to configure them

platform-versionstring
Platform version you use to build the app. This value is auto-generated when you create the default app files by using the fdk create command.

When you build a new app, ensure that you are on the latest version of the platform . If you update your existing app that was built with an earlier platform version, ensure to move to the latest version of the platform.
productobjectRequired
Associates a Freshworks product with the information that is necessary to render the app on the specified product.
- <product-name>objectRequired
  Name of the product for which you are building the app. This value is auto-generated when you create the default app files by using the fdk create command.
  locationobjectRequired
  Details of the location(s) on the product’s UI, where the front-end component of the SMI app is rendered. An app can be rendered in multiple locations and inside this object, you can specify multiple placeholder locations.
  
  For an SMI app, this attribute is not a default attribute. When building the app, include this attribute along with its child attributes.
  
  For information on all available placeholder locations where your front-end component of your SMI app can be deployed, see Include placeholders for app deployment.
  <placeholder-name>objectRequired
  Name of the placeholder where the front-end component of your app is rendered.
  
  When you build an SMI app, enter the placeholder name pertaining to your app and the appropriate placeholder information in the child attributes.
  
  For information on all available placeholder location names, see Include placeholders for app deployment.
  urlstringRequired
  Relative path from the app project directory to the template.html file based on which the UI component of the app is rendered. The contents of the template.html file are used to render the app in an IFrame at the specified placeholder location.
  
  Default value: template.html (file in the app directory). When you build an app, you can modify the default url value and the name of the template.html file.
  Caution:If you modify the template.html filename, ensure to specify the correct path and filename as the url value.
  iconstringRequired
  Relative path from the app project directory to an image file (in SVG format). The image is used as the app’s icon when the app is rendered on the UI. Ensure that the resolution of the image is 64 x 64 pixels.
  
  Default value: icon.svg (file in the app directory). When you build an app, you can modify the default icon value.
  Caution:If you store your app icon with a name other than icon.svg, ensure to specify the correct path and filename as the icon value.
  eventsobjectRequired
  Various serverless events and the corresponding call-back function names, specified in the following format:
  "events": { "<eventName1>": { "handler": "<callbackFunctionName1>" }, "<eventName2>": { "handler": "<callbackFunctionName2>" } }
  When you build an SMI app, replace the default values in this attribute with the events pertaining to your app. For more information, see Build serverless apps.
  functionsobjectRequired
  SMI functions (server methods) defined in the exports code block of server.js, specified in the following format:
  "functions": { "<serverMethodName1>": {}, "<serverMethodName2>": {} }
  Register the SMI functions: The functions attribute is not a default attribute. When you build an SMI app, include the functions attribute, to allowlist the SMI functions that are defined in server.js.
  Note:If the front-end component tries to invoke a function/method that is not registered in the app manifest, the fdk run or fdk validate commands display the error message Requested function not found or registered.
  requestsobject
  All configured request templates that the app code uses, for a product, in the following format.
  "requests": { "<requestTemplateName>":{ "<option-name>": "<option-value>", "<option-name1>": "<option-value1>" … }, "<requestTemplateName1>": {} … }
  Notes:
  <requestTemplateName> must be the same as that configured in config/requests.json.
  Possible values of <option-name> are maxAttempts, retryDelay, and isOAuth. If an option is specified in both manifest.json and config/requests.json, the option value specified in manifest.json takes precedence.
  
  This attribute is not a default attribute. If you are using FDK version 9.0.0 or later, and if you expect your app to make third-party HTTP calls, in request.json, configure the necessary request templates and in manifest.json include this request attribute and list all the configured template names.
enginesobject
Node.js and FDK versions that are used to build the app. When you create the front-end app files by using the fdk create command, this attribute value is auto-populated.

Creating an app: If you use FDK 7.0.0 or later versions to create an app, the engines attribute is available by default as part of the manifest.json file.

Migrating an app: If you have an existing app that is built using FDK 6.x.x or an earlier version, ensure to,
1. Install the latest FDK version.
2. Run fdk validate to migrate the app to the latest FDK version. As part of this process, the FDK updates the engines attribute.
3. Retest the app.
- nodestring
  Node.js version on which the app is built (in case of new apps) or successfully validated (in case of apps built using FDK 6.x.x or earlier versions and migrated to the latest FDK).
- fdkstring
  FDK version that is used to build, test, validate, and pack the app.
appobject
Information pertaining to the app metrics, auto-generated when the app is created.
Note:Currently, this object is auto-generated only when the app uses any Freddy Copilot features.
- trackingIdstring
  Identifier for the app.
- startTimestring
  Timestamp of when the app was created, specified in the UTC format.

Sample manifest.json

{
  "platform-version": "2.3",
  "product": {
    "freshworks_crm": {
      "location": {
          "left_nav_cti": {
            "url": "template.html",
            "icon": "logo.svg"
          }
        },
      "events": {
        "onContactCreate": {
          "handler": "onContactCreateHandler"
        },
        "onExternalEvent": {
          "handler": "onExternalEventHandler"
        }
      },
      "functions": {
        "serverMethod": {}
      },
      "requests": {
        "createContact": {},
        "getContacts": {}
      }
    }
  },
  "engines": {
      "node": "18.12.1",
      "fdk": "9.0.0"
  }
}

Invoke the serverless component

From the app’s root directory,

Navigate to the app.js file.
Define the JSON payload that is to be passed to the method in the server.js file. In the sample app.js code displayed in the right pane, options is the JSON payload that is passed.
Include the client.request.invoke(“serverMethodName”, JSON_payload) method to invoke the serverless component. By default, the serverless environment adds an iparams object to the payload.
Include functions to handle the response obtained from the serverless component.

Sample app.js

Sample payload

var options = { "url": "https://api.github.com/users/sample" };
client.request.invoke("serverMethod", options).then(
  function(data) {
     // data is a json object with requestID and response.
     // The serverless environment generates the request ID.
     /*The serverless method in server.js returns two objects (error,response).
     data.response is the response object from the serverless method.*/
    console.log("Server method Request ID is: " + data.requestID);
    console.log("Server method response is: " + data.response);
  },
  function(err) {
    /* err is a json object with requestID, status, and message.*/
    // The serverless environment generates the request ID.
    /* The serverless method in server.js returns two objects (error,response).*/
    /* The error object contains the status and message attributes.*/
    // err.status is the error.status attribute.
    // err.message is the error.message attribute.
    console.log("Request ID: " + err.requestID);
    console.log("error status: " + err.status);
    console.log("error message: " + err.message);
  });

Send response to the front-end component

After the app logic in the server method runs, the server method sends an appropriate response to the front-end component. To enable this:

Navigate to the server.js file. In the exports code block, define the server method that is called from the front-end component. Place the app logic inside the server method.
Notes:
- The SMI function name is case-sensitive.
- The SMI function name:
  - Can be alphanumeric ([a-z], [A-Z], [0-9]) and can contain the special character underscore ( _ ).
  - Should not start with a number.
  - Should not contain any spaces between the characters.
  - Can be 2 to 40 characters long.
Use the renderData(error, data) method to return a response to the front-end component.
Notes:
- error and data are passed as JSON objects to the caller method. Ensure that the first argument of renderData(error, data) is always the error object. For success responses, ensure to pass null as the first argument.
- error is an object with status and message attributes. data is an object with valid <key>: <value> pairs.
- The serverless environment adds a requestID attribute, to the error or data object.

To send a success response, use the renderData() method as follows:

Code

Sample response

exports = {
 serverMethod:  function(options) {
   // app logic resides here
   renderData(null,  { "key": "value" });
 }
}

To send a failure response, use the renderData() method as follows:
Code
Sample response
exports = { serverMethod: function(options) { var error = { status: 403, message: "Error while processing the request" }; renderData(error); } }
In the response if error.status is not present, the default status code of 500 is used as the error status. If the error object in renderData(error) is of incorrect JSON format, error.status value is 400 and error.message value is The error should be a JSON Object with a message or a status parameter.
The front-end component can render this error as follows:
```
 {
   "requestID": "2edc13f8-3b81-4ade-b857-8d8e316fa87c",
   "status": 400,
   "message": "The error should be a JSON Object with a message or a status parameter."
 }
```
Note:If the server method does not return a response, the app execution timeout error occurs.

Test the SMI app

From the command line, navigate to the directory that contains the app related files and run the fdk run command.
Log in to your Freshsales Suite account.
To the Freshsales Suite account URL, append ?dev=true.
Example URL: https://subdomain.freshsales_suite.com/helpdesk/tickets/1?dev=true
To allow the Chrome browser to connect to the test server that runs on HTTP,
1. Navigate to Settings > Advanced > Privacy and security > Site settings > Insecure content.
2. In the Allow section, click Add and enter the account URL.
  Example URL: https://subdomain.freshsales_suite.com
From the homepage of your account, navigate to the appropriate location where your app is to be deployed, verify that the app is rendered and test your app’s function.