App Manifest

The manifest.json file contains information such as the platform version used by a product, locations on the product UI where an app can be rendered (for front-end apps), dependent packages used by the app, SMI functions that can be invoked from an app’s front-end component, events and the corresponding callbacks (for serverless apps), and the Node.js and FDK versions used to build, test, validate, and pack the app. For apps built using FDK version 9.0.0 or later, if the app is expected to make third-party HTTP calls, manifest.json lists the configured request templates that the app invokes to construct and send secure HTTP requests to the third-party domains. For apps built using an FDK version prior to 9.0.0 (platform version 2.2), manifest.json whitelists all the third-party domains with which the app can interact. This section details the various attributes of the manifest.json file.

Manifest.json file

Sample

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
{
  "platform-version": "2.3",
  "product": {
    "freshcaller": {
      "location": {
        "notification_card": {
          "url": "template.html",
          "icon": "logo.svg"
        },
        "conversation_card": {
          "url": "template.html",
          "icon": "logo.svg"
        }
      },
      "requests": {
          "createCalls": {},
          "getCalls": {}
      }
    }
  },
  "engines": {
    "node": "18.12.1",
    "fdk": "9.0.0"
  },
  "dependencies": {
    "nodemon": "2.72.0"
  }
}
EXPAND ↓

Sample manifest.json for serverless apps

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
{
  "platform-version": "2.3",
  "product": {
    "freshcaller": {
      "events": {
        "onCallCreate": {
          "handler": "onCallCreateCallback"
        },
        "onCallUpdate": {
          "handler": "onCallUpdateCallback"
        }
      },
      "requests": {
         "createCalls": {},
         "getCalls": {}
     }   
    }
  },
  "engines": {
    "node": "18.12.1",
    "fdk": "9.0.0"
  }
}
EXPAND ↓

Sample manifest.json for serverless SMI apps

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
{
  "platform-version": "2.3",
  "product": {
    "freshcaller": {
      "location": {
        "conversation_card": {
          "url": "index.html",
          "icon": "styles/images/icon.svg"
        },
        "notification_card": {
          "url": "template.html",
          "icon": "logo.svg"
        }
      },
      "events": {
        "onCallCreate": {
            "handler": "onCallCreateCallback"
        },
        "onCallUpdate": {
          "handler": "onCallUpdateCallback"
        }
      },
      "functions": {
        "serverMethod": {
          "timeout": "10"
        }
      },
      "requests": {
        "createCalls": {},
        "getCalls": {}
      }
    }
  },
  "engines": {
    "node": "18.12.1",
    "fdk": "9.0.0"
  }
}
EXPAND ↓

Sample - platform version 2.2

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
{
  "platform-version": "2.2",
  "product": {
    "freshcaller": {
      "location": {
        "notification_card": {
          "url": "template.html",
          "icon": "logo.svg"
        },
        "conversation_card": {
          "url": "template.html",
          "icon": "logo.svg"
        }
      }
    }
  },
  "engines": {
    "node": "12.22.6",
    "fdk": "7.0.0"
  },
  "dependencies": {
    "request": "2.72.0"
  },
  "whitelisted-domains": [
    "https://www.google.com"
  ]
}
EXPAND ↓

Sample manifest.json for serverless apps

Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "platform-version": "2.2",
  "product": {
    "freshcaller": {
      "events": {
        "onCallCreate": {
          "handler": "onCallCreateCallback"
        },
        "onCallUpdate": {
          "handler": "onCallUpdateCallback"
        }
      }
    }
  },
  "engines": {
    "node": "12.22.6",
    "fdk": "7.0.0"
  },
  "whitelisted-domains": [
    "https://www.google.com"
  ]
}
EXPAND ↓

Sample manifest.json for serverless SMI apps - platform version 2.2

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
{
  "platform-version": "2.2",
  "product": {
    "freshcaller": {
      "location": {
        "conversation_card": {
        "url": "index.html",
        "icon": "styles/images/icon.svg"
        },
        "notification_card": {
          "url": "template.html",
          "icon": "logo.svg"
        }
      },
      "events": {
        "onCallCreate": {
          "handler": "onCallCreateCallback"
        },
        "onCallUpdate": {
          "handler": "onCallUpdateCallback"
        }
      },
      "functions": {
        "serverMethod": {
          "timeout": "10"
        }
      }
    }
  },
  "engines": {
    "node": "12.22.6",
    "fdk": "7.0.0"
  },
  "whitelisted-domains": [
    "https://www.google.com"
  ]
}
EXPAND ↓

Parameters

Parameter Name Date Type Description
platform-version string When the app files are created, this field value is auto-generated. The value specifics which version of the platform is used to build the app. The version information is used to ensure backward compatibility when a new platform version is released.
Product
Mandatory		 object Associates a Freshworks product with the information that is necessary to render the app on the specified product.
(Child parameter: Freshcaller)
Freshcaller
Mandatory		 object Specifies information that is necessary to render the app on the Freshcaller UI.
(Child parameter: location)
location
Mandatory for all except serverless apps		 object Specifies the locations on the Freshcaller UI, where the app is to be rendered.
For more information, see Placeholders
(Child parameters: notification_card, conversation_card, widget_notification_card, widget_conversation_card)
notification_card
 object Specifies information necessary to render the app, on the Freshcaller web UI, in the incoming call notification.
Attributes: url, icon
conversation_card
 object Specifies information necessary to render the app, on the Freshcaller web UI, in the conversation window that is displayed after a call is established.
Attributes: url, icon
widget_notification_card
 object Specifies information necessary to render the app, on the Freshcaller widget (in another product), in the incoming call notification.
Attributes: url, icon
widget_conversation_card
 object Specifies information necessary to render the app, on the Freshcaller widget (in another product), in the conversation window.
Attributes: url, icon
url
Mandatory		 string Specifies the relative path from the app project directory to the template.html file based on which the app is rendered. The contents of the template.html file are used to render the app in an IFrame at the specified location.
Default value: template.html (file in the app directory)
icon
Mandatory		 string Specifies the 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. The resolution of the image needs to be 64x64 pixels.
Default value: icon.svg (file in the app directory)
requests

Valid only for apps built with platform version 2.3		 object Specifies the configured request templates that the app code uses, for a product, in the following format.
1
2
3
4
5
6
7
8
9
"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.
whitelisted-domains
MANDATORY

Valid only for apps built with platform version 2.2		 array of string To make secure HTTP calls to third-party domains, apps built on platform version 2.2 must use the Request method with domain whitelisting. For the method to work, in manifest.json, the third-party domains must be listed as the whitelisted-domains.

Notes:

  • If the requisite domains are not whitelisted, the fdk run command displays an error message This domain has not been whitelisted.
  • To use iparams to construct the whitelisted-domains values, use the following format:
    1
    		"whitelisted-domains": ["<%= iparam.url %>"]
  • Ensure that the whitelisted-domains array values:
    • Do not contain an IP address or multiple subdomains.
    • Do not contain the path to the resource.
    • Use HTTPS, if iparams are not used to construct the whitelisted-domains values.
    • Are not URLs to a localhost.
engines object Specifies the Node.js version and FDK version that are used to build the app. FDK auto-populates this value.
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.
Child attributes:
node (string): Specifies the 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).
fdk (string): Specifies the FDK version that is used to build, test, validate, and pack the app.
dependencies
 object Specifies the npm packages used by the app, in the “<package_name>”:”<version_number>” format.
For more information, see npm packages.
events
Mandatory for serverless apps		 object Contains the various serverless events and the corresponding call-back function names, specified in the following format:
Copied Copy 
1
2
3
4
5
6
7
8
"events": {
  "<eventName1>": {
    "handler": "<callbackFunctionName1>"
  },
  "<eventName2>": {
    "handler": "<callbackFunctionName2>"
  }
}
EXPAND ↓ For more information, see the Overview section in Serverless.
functions
Mandatory for SMI		 object Lists the SMI functions (server methods) defined in the exports code block of server.js, in the following format:
Copied Copy 
1
2
3
4
5
6
7
8
"functions": {
  "<serverMethodName1>": {
    "timeout": 10
  },
  "<serverMethodName2>": {
    "timeout": 15
  }
}
EXPAND ↓ Child attribute:
timeout (integer): Time in seconds beyond which the app execution times out, if the SMI function does not return a valid response to the front-end component. You can specify an appropriate timeout value based on the SMI function.
Valid values : 5, 10, 15, and 20
For more information, see Server Method Invocation.