### Sample App Setup Event Payload Source: https://developers.freshcaller.com/docs/app-setup-events An example of the payload received when an 'onAppInstall' event occurs. ```json { "timestamp": 1583839686, "account_id": "12345", "domain": "https://sample.freshcaller.com", "event": "onAppInstall", "region": "US" } ``` -------------------------------- ### Configuring Visible and Required Parameters Source: https://developers.freshcaller.com/docs/installation-parameters Example demonstrating how to set a parameter as both required and visible on the installation page. ```json { "contact": { "display_name": "Contact Details", "description": "Please enter the contact details", "type": "text", "required": true, "visible": true } } ``` -------------------------------- ### Retrieve All Installation Parameters Source: https://developers.freshcaller.com/docs/installation-parameters Retrieves all configured installation parameters except secure ones. ```APIDOC ## Retrieve All Installation Parameters This method returns all the configured installation parameters except secure iparams. ### Method ```javascript client.iparams.get() ``` ### Request Example ```javascript client.iparams.get().then ( function(data) { // success output // "data" is returned with the list of all the iparams }, function(error) { console.log(error); // failure operation }); ``` ### Sample Response ```json { "contact": "rachel@freshcaller.com", "contact-type": "Email", "request_domain": "sample.freshcaller.com", "subdomian": "sample" } ``` ``` -------------------------------- ### Handle Successful App Installation Source: https://developers.freshcaller.com/docs/app-setup-events Define the onAppInstallCallback in server.js to allow app installation completion. Use renderData() without arguments for success. ```javascript 1234567| exports = { onAppInstallCallback: function(payload) { console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload)); // If the setup is successful renderData(); } } ``` -------------------------------- ### Testing Installation Parameters Source: https://developers.freshcaller.com/docs/installation-parameters Instructions on how to test configured installation parameters using the FDK CLI. ```APIDOC ## Testing Installation Parameters To test the configured installation parameters: 1. From the command prompt, navigate to the app project folder, and run the following command: `$ fdk run` 2. If the app contains an installation page, the following message is displayed: `To test the installation page, visit - http://localhost:10001/custom_configs` 3. Navigate to the specified location. The installation page is displayed. 4. Enter appropriate values in the fields and click **INSTALL** to test the installation page. ``` -------------------------------- ### Basic iparam.json Configuration Source: https://developers.freshcaller.com/docs/installation-parameters This JSON structure defines various installation parameters with their display names, descriptions, types, and requirements. It includes examples for text, number, dropdown, domain, and API key types. ```json { "contact": { "display_name": "Contact Details", "description": "Please enter the contact details", "type": "text", "required": true }, "age": { "display_name": "Age", "description": "Please enter your age in years", "type": "number" }, "contactType": { "display_name": "Contact Type", "description": "Please select the contact type", "type": "dropdown", "options": [ "Phone", "Email" ], "default_value": "Email" }, "domainName": { "display_name": "Domain Name", "description": "Please enter your domain name", "type": "domain", "type_attributes": { "product": "freshcaller" }, "required": true }, "apiKey": { "display_name": "API Key", "description": "Please enter your api_key", "type": "api_key", "secure": true, "required": true, "type_attributes": { "product": "freshcaller" } } } ``` -------------------------------- ### Sample OAuth Configuration with Installation Parameters Source: https://developers.freshcaller.com/docs/oauth Configure OAuth using installation parameters for dynamic URLs and credentials, such as Shopify's domain-specific authorization. ```json { "client_id": "5eXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXc8d1", "client_secret": "q8NbXXXXXXXXXXXXXXXX1p1", "authorize_url": "https://<%= oauth_iparams.domain %>/authorize.srf", "token_url": "https://<%= oauth_iparams.domain %>/token.srf", "options": { "scope": "read" }, "token_type": "account", "oauth_iparams": { "domain": { "display_name": "Shopify domain", "description": "Please enter your Shopify domain", "type": "text", "required": true }, "client_id": { "display_name": "Shopify Client ID", "description": "Please enter your Shopify client ID", "type": "text", "required": true }, "client_secret": { "display_name": "Shopify Client Secret", "description": "Please enter your Shopify client secret", "type": "text", "required": true } } } ``` -------------------------------- ### Store Installation Parameters with postConfigs Source: https://developers.freshcaller.com/docs/custom-installation-page Include this method in iparams.html to store installation parameter values when INSTALL is clicked. It captures iparam values as JSON key-value pairs and passes secure values via meta tags. ```javascript ``` -------------------------------- ### Retrieve Installation Parameters with getConfigs Source: https://developers.freshcaller.com/docs/custom-installation-page Include this method in iparams.html to retrieve stored installation parameters and populate the Edit Settings page. It is triggered when the Settings icon is clicked on the Installed Apps Listing page. ```javascript ``` -------------------------------- ### Text Input Field Source: https://developers.freshcaller.com/docs/installation-parameters Use 'text' for a single-line text input on the installation form. It is a required field in this example. ```json 12345678| { "ContactDetails": { "display_name": "Contact details", "description": "Please enter the contact details", "type": "text", "required": true } } ``` -------------------------------- ### Install NVM on Linux Source: https://developers.freshcaller.com/docs/quick-start Use this command to install NVM on Linux systems. Ensure cURL is installed first. Refresh .bashrc after installation. ```bash sudo apt install curl curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash source ~/.bashrc ``` -------------------------------- ### Retrieve All Installation Parameters Source: https://developers.freshcaller.com/docs/installation-parameters This method retrieves all configured installation parameters except for secure iparams. The 'data' variable will contain a list of all iparams upon success. ```javascript 12345678910| client.iparams.get().then ( function(data) { // success output // "data" is returned with the list of all the iparams }, function(error) { console.log(error); // failure operation } ); ``` ```json 123456| { "contact": "rachel@freshcaller.com", "contact-type": "Email", "request_domain": "sample.freshcaller.com", "subdomian": "sample" } ``` -------------------------------- ### Retrieve Specific Installation Parameter Source: https://developers.freshcaller.com/docs/installation-parameters Retrieves a specific installation parameter by its key. ```APIDOC ## Retrieve Specific Installation Parameter This method identifies an iparam by the iparam key specified and returns the value corresponding to the iparam. If you try to retrieve a secure iparam, an error message is displayed. ### Method ```javascript client.iparams.get(iparam_key) ``` ### Request Example ```javascript client.iparams.get("contact").then ( function(data) { // success output // "data" is returned with the value of the "contact" attribute. }, function(error) { console.log(error); // failure operation }); ``` ### Sample Success Response ```json { "contact": "rachel@freshcaller.com" } ``` ### Sample Failure Response ```json { "message": "Could not find an installation parameter that matches this key." } ``` ``` -------------------------------- ### Handle Failed App Installation Source: https://developers.freshcaller.com/docs/app-setup-events Define the onAppInstallCallback to disallow installation on failure. Use renderData() with an error object, including a message, to indicate the reason. ```javascript 1234567| exports = { onAppInstallCallback: function(payload) { console.log("Logging arguments from onAppInstallevent: " + JSON.stringify(payload)); // If there is an error during the setup, see screenshot below renderData({message: "Invalid API Key"}); } } ``` -------------------------------- ### Install Node.js Build Tools on Windows Source: https://developers.freshcaller.com/docs/quick-start Install the necessary build tools for Node.js on Windows using npm. Refer to node-gyp documentation for more details. ```bash npm install --global --production windows-build-tools ``` -------------------------------- ### Configure App Setup Events in manifest.json Source: https://developers.freshcaller.com/docs/app-setup-events Include the 'events' attribute in your manifest.json file to specify app setup events and their corresponding callback methods. ```json "events": { "": { "handler": "" } } ``` -------------------------------- ### Validate Installation Parameters with validate Source: https://developers.freshcaller.com/docs/custom-installation-page Include this method in iparams.html to validate iparam values on the installation or Edit Settings page. If the method returns false, the installation or saving of values is stopped. ```javascript ``` -------------------------------- ### Install Node.js using NVM Source: https://developers.freshcaller.com/docs/quick-start Install Node.js version 18 using NVM. This version is required for the latest FDK. Verify the installation and set it as the default. ```bash nvm install 18 node --version nvm alias default 18 ``` -------------------------------- ### Install Node.js Build Tools on MacOS Source: https://developers.freshcaller.com/docs/quick-start Install the XCode CLI tool required for Node.js build tools on MacOS. Verify the installation afterwards. ```bash xcode-select --install xcode-select -p ``` -------------------------------- ### Install NVM on Windows using Chocolatey Source: https://developers.freshcaller.com/docs/quick-start Install NVM on Windows via Chocolatey. Ensure you run PowerShell in admin mode. Verify Chocolatey installation before proceeding. ```powershell Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) choco install nvm ``` -------------------------------- ### Configuring Secure Parameters Source: https://developers.freshcaller.com/docs/installation-parameters This example shows how to mark an API key parameter as secure, ensuring sensitive data is protected. ```json { "apiKey": { "display_name": "Api Key", "type": "text", "required": true, "secure": true } } ``` -------------------------------- ### App Setup Event Payload Source: https://developers.freshcaller.com/docs/app-setup-events This snippet details the structure and attributes of the payload passed to the callback method when an app setup event occurs. ```APIDOC ## Payload Attributes When an app setup event occurs, a payload is passed to the callback method. ```json { "account_id" : "value", "domain" : "value", "event" : "value", "region" : "value", "timestamp" : "value", "iparams" : { "Param1" : "value", "Param2" : "value" } } ``` The payload is a JSON object with the following attributes: | Attribute | Type | Description | |---|---|---| | account_id | string | Identifier of the Freshcaller account, auto-generated when the account is configured for a business. | | domain | string | Domain name for the Freshcaller account. For example, **acn.freshcaller.com**. | | event | string | Identifier of the app setup event. **Possible values** : **onAppInstall** , **onAppUninstall**. | | region | string | Region where the Freshcaller account is deployed. **Possible values:**US** , **EU** , **EUC** , **AUS** , and **IND**. | | timestamp | number | Timestamp of when the app setup event occurs, specified in the epoch format. | | iparams | object | Installation parameters specified as a JSON object of : pairs. | **Sample payload** ```json { "timestamp": 1583839686, "account_id": "12345", "domain": "https://sample.freshcaller.com", "event": "onAppInstall", "region": "US" } ``` ``` -------------------------------- ### Register onAppInstall Event Source: https://developers.freshcaller.com/docs/app-setup-events Register the onAppInstall event in your manifest.json file to handle app installations. ```json 12345| "events": { "onAppInstall": { "handler": "onAppInstallCallback" } } ``` -------------------------------- ### Configure Events in manifest.json Source: https://developers.freshcaller.com/docs/app-setup-events This snippet shows how to register app setup events and their corresponding callback methods in the manifest.json file. ```APIDOC ## Configure Events in manifest.json To register an app setup event and the corresponding callback: 1. From your app’s root directory, navigate to the **manifest**.**json** file. 2. Include the events attribute, specifying the app setup event (possible events: onAppInstall, afterAppUpdate, and onAppUninstall) and the corresponding callback methods as follows: ```json "events": { "": { "handler": "" } } ``` **Note:** Include only one callback method for an event. ``` -------------------------------- ### Configure onAppInstall Event in manifest.json Source: https://developers.freshcaller.com/docs/external-events Define the handler for the onAppInstall event in your manifest.json file. This handler will be invoked when the app is installed. ```json 12345| "events": { "onAppInstall": { "handler": "onAppInstallHandler" } } ---|--- EXPAND ↓ ``` -------------------------------- ### Verify Freshworks CLI Installation Source: https://developers.freshcaller.com/docs/quick-start Run this command to check if the CLI is installed correctly and to verify the version. Ensure it is 9.0.0 or later. ```bash fdk version ``` -------------------------------- ### Link HTML Example Source: https://developers.freshcaller.com/docs/ui-style-guide Use standard 'a' tags for links. No specific class is needed. ```html First Opportunity ``` -------------------------------- ### Button HTML Examples Source: https://developers.freshcaller.com/docs/ui-style-guide Use 'button' tags with 'btn' and 'btn-primary' or 'btn-default' classes for primary and secondary actions. ```html ``` -------------------------------- ### Get Source: https://developers.freshcaller.com/docs/instance-method Fetch context information for all active instances. Useful for identifying instances to communicate with using the `send` method. ```APIDOC ## client.instance.get() ### Description Fetches context information for all currently active app instances. ### Method `get` ### Response #### Success Response - An array of objects, where each object contains: - **instanceId** (string) - The unique ID assigned to each instance. - **location** (string) - The location of the current instance. - **parentId** (string, optional) - The ID of the parent instance that triggered the modal. ``` -------------------------------- ### Define Callback Method in server.js Source: https://developers.freshcaller.com/docs/app-setup-events This snippet demonstrates how to define the callback function for app setup events in the server.js file. ```APIDOC ## Define Callback Method in server.js Navigate to the **server**.**js** file. In the exports block, enter the callback function definition as follows: ```javascript exports = { // args is a JSON block containing the payload information // args["iparam"] will contain the installation parameter values // eventCallbackMethod is the call-back function name specified in manifest.json eventCallbackMethod: function(args) { console.log("Logging arguments from the event: " + JSON.stringify(payload)); // If the setup is successful renderData(); // If there is an error during the setup renderData({message: "Error message"}); } }; ``` ``` -------------------------------- ### Run Freshcaller App Locally Source: https://developers.freshcaller.com/docs/overview Execute this command in your app's directory to start a local development server for testing. ```bash $ fdk run ``` -------------------------------- ### Definition List HTML Example Source: https://developers.freshcaller.com/docs/ui-style-guide Use 'dl', 'dt' with 'list-label' class, and 'dd' for definition lists. ```html
Coffee
Black hot drink
Milk
White cold drink
``` -------------------------------- ### Example: Encode iparam in Authorization Header Source: https://developers.freshcaller.com/docs/request-method Shows how to use the encode() function to securely pass an API key in the Authorization header. ```javascript "Authorization": "Bearer <%= encode(iparam.api_key) +':x'>" ``` -------------------------------- ### GET request without authentication Source: https://developers.freshcaller.com/docs/request-method Example of making a GET request to an external API without requiring authentication. ```APIDOC ## GET request without authentication ### Description This example shows how to make a simple GET request to an external API endpoint when no authentication is required. ### Method GET ### Endpoint https://httpbin.org/get?arg1=hello_world ### Request Example ```javascript var options = {}; var url = "https://httpbin.org/get?arg1=hello_world"; client.request.get(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); }); ``` ``` -------------------------------- ### GET request with authentication Source: https://developers.freshcaller.com/docs/request-method Example of making a GET request to an external API with authentication using the Authorization header. ```APIDOC ## GET request with authentication ### Description This example demonstrates how to make a GET request to an external API endpoint, including setting an Authorization header for authentication. ### Method GET ### Endpoint https://sample.crm.com/contacts/5.json ### Parameters #### Headers - **Authorization** (string) - Required - The authentication token, typically base64 encoded. ### Request Example ```javascript var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"}; var options = { headers: headers }; var url = "https://sample.crm.com/contacts/5.json"; client.request.get(url, options) .then ( function(data) { console.log(data); }, function(error) { console.log(error); }); ``` ### Response #### Success Response (200) Returns the data from the API. The structure depends on the API being called. #### Response Example ```json { "status" : 200, "headers": { "Content-Length": 20, "Content-Type": "application/json;charset=utf-8" }, "response": "{ \"Name\": \"Rachel\"}", "attempts": 1 } ``` #### Error Response (Platform Error) ```json { "status" : 502, "headers": { "Content-Type": "application/json;charset=utf-8" }, "response": "Error in establishing the connection.", "attempts": 1, "errorSource": "PLATFORM" } ``` #### Error Response (App Error) ```json { "status" : 400, "headers": { "Content-Type": "application/json;charset=utf-8" }, "response": "This domain has not been whitelisted.", "attempts": 2, "errorSource": "APP" } ``` ``` -------------------------------- ### Handling Scheduled Event in server.js Source: https://developers.freshcaller.com/docs/scheduled-events Define the callback function specified in manifest.json within your server.js file to process the payload received from a scheduled event. This example logs the payload and includes a conditional check. ```javascript 123456789| exports = { onScheduledEventHandler: function(payload) { console.log("Logging arguments from onScheduledEvent: " + JSON.stringify(payload)); if(payload.data.account_id = "3") { //your code to perform any actions } } }; ``` -------------------------------- ### Scheduled Event Payload Structure Source: https://developers.freshcaller.com/docs/scheduled-events This is the structure of the payload received by your serverless app when a scheduled event is triggered. It includes account details, event type, region, timestamp, domain, custom data, and installation parameters. ```json 123456789101112| { "account_id" : "value", "event" : "onScheduledEvent", "region" : "value", "timestamp" : "value", "domain" : "value", "data" : {}, "iparams" : { "Param1" : "value", "Param2" : "value" } } ``` ```json 123456789101112| { "account_id": "12345", "domain": "sample.freshcaller.com", "event": "onScheduledEvent", "timestamp": 1583839686, "region": "US", "data": { "sample_data1": "sample value1", "sample_data2": "sample value2", "sample_data3": 3 } } ``` -------------------------------- ### Run Development Server Source: https://developers.freshcaller.com/docs/quick-start Navigate to your app's directory and run this command to start the development server. Ensure you have a Freshcaller account and have configured your browser to allow insecure content from your account URL. ```bash fdk run ``` -------------------------------- ### Hide iparam Source: https://developers.freshcaller.com/docs/installation-parameters Control the visibility of an iparam on the installation page. This example hides the 'lastname' iparam when the 'firstname' iparam receives a value. ```javascript function firstnameChange(arg) { utils.set(‘lastname’, {visible: false}); } ``` -------------------------------- ### Sample requests.json Configuration Source: https://developers.freshcaller.com/docs/request-method A sample configuration file demonstrating multiple request definitions with various template substitutions for iparams, context, and headers. ```json { "getCalls": { "schema": { "method": "GET", "host": "<%= iparam.domain %>.freshcaller.com", "path": "/api/v1/calls", "headers": { "Authorization": "Bearer <%= iparam.apikey %>", "Content-Type": "application/json" }, "query": { "page": "<%= context.page %>", "per_page": "20" } }, "options": { "retryDelay": 1000 } }, "sendToExternalAPI": { "schema": { "method": "POST", "host": "<%= iparam.ext_domain %>.example.com", "path": "/api/", "headers": { "Authorization": "Bearer <%= iparam.ext_apikey %>", "Content-Type": "application/json" } } } ``` -------------------------------- ### Sample app.js for App Initialization and Activation Source: https://developers.freshcaller.com/docs/request-method This sample demonstrates the basic setup for initializing a Freshcaller app and handling the app.activated event. It includes a placeholder for additional app logic. ```javascript 123456789101112131415161718192021222324252627| // ------ // Setup // ------ document.onreadystatechange = function () { if (document.readyState === "interactive") { app.initialized() .then(function (client) { client.events.on("app.activated", function () { onAppActivate(client); }); }) .catch(handleErr); } }; // <-- additional app code --> // ------ // App Logic // ------ async function onAppActivate(client) { // Get Calls for page 2 await client.request.invokeTemplate("getCalls", { context: { page: 2, } }); } ``` -------------------------------- ### Example: iparam in Host and Header Source: https://developers.freshcaller.com/docs/request-method Demonstrates using a non-secure iparam in the host attribute and a secure iparam in the header attribute. Mismatched names will result in an error. ```json "schema": { "method": "GET", "host": "<%= iparam.domain %>.freshcaller.com", "path": "/api/v1/calls", "headers": { "Authorization": "Bearer <%= iparam.api_key %>", "Content-Type": "application/json" } } ``` -------------------------------- ### Run the app from a specific directory Source: https://developers.freshcaller.com/docs/freshworks-cli Deploys the app project from a specified directory to the local testing server. The output is similar to running in the current directory. Press Control + C to stop the server. ```bash $ fdk run --app-dir /Users/user/myfirstapp ``` -------------------------------- ### Error Response Example Source: https://developers.freshcaller.com/docs/request-method Example of an error response structure when a request fails. ```APIDOC ## Error Response Example ### Description This example shows the structure of an error response when a request fails, including status, headers, response message, and error source. ### Response Example ```json { "status": 401, "headers": { "Content-Type": "text/plain" }, "response": "Session expired or invalid", "errorSource": "APP/PLATFORM" } ``` ``` -------------------------------- ### Sample iparams.html for Custom Installation Source: https://developers.freshcaller.com/docs/custom-installation-page This HTML file includes dependencies for styling and functionality, script tags for appclient and external libraries like jQuery and Select2. It also contains inline styles and JavaScript functions for handling configuration, validation, and posting data. ```html

Contact Fields