Request method is a secure mechanism to send HTTP requests from an app to a third-party domain, without exposing any sensitive information that is part of the request. Through browsers, app users may intercept sensitive information such as API keys or user credentials. Request method safeguards against such exposure. Typically, HTTP requests are routed through proxy servers. In such cases, sending the HTTP requests through the request method helps identify the origin in scenarios where the third-party domain has enabled Cross Origin Resource Sharing (CORS) support.

1. As part of the app configuration, configure request templates.
2. In manifest.json, declare the template(s) that the app code uses.
3. From the app logic, invoke the configured template(s), and make HTTP requests to third-party domains.

Notes:
1. The default request timeout is five seconds. For the local testing of apps that use the request method, you can specify an appropriate timeout. For information on local testing with REQUEST_TIMEOUT, see Test apps that use request method.
2. The rate limit for requests is 50 requests per minute per app per account.

Configure request templates

Request templates are snapshots of all the HTTP requests that an app is expected to make.

• From the app’s root directory, navigate to the config folder and create a requests.json file (if requests.json does not exist).
• In requests.json, use the following syntax to configure all request templates that the app is expected to use, as JSON objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
      "<requestTemplateName>": {
        "schema": {
          // ... request schema
        },
        "options": {
          // ... request options
        }
      },
      "<requestTemplateName1>": {
        "schema": {
          // ... request schema
        },
        "options": {
          // ... request options
        }
      }
    }

1
2
3
4
5
6
7
8
9
"schema": {
  "method": "GET",
  "host": "northstar.myfreshworks.com",
  "path": "/crm/sales/api/contacts/view/[:view_id]",
  "headers": {
  "Authorization": "Bearer <%=iparam.apikey %>",
  "Content-Type": "application/json"
  }
}

1
2
3
"query": {
      "page": "<%= context.page %>"
    }

1
2
3
"options": {
      "retryDelay": 1000
    }

1
2
3
"headers": {
      "Authorization": "Bearer <%= access_token %>"
      }

Template substitutions

• Installation parameter (iparam) values
• Contextual data
• Stored access tokens

Variables can be used only in the following <requestTemplateName>.schema attributes. Also, the type of data that can populate the variables varies depending on the attribute in which the variables are used.

Use the following syntax to declare a template variable that is populated with iparam values at runtime.

1
<%= iparam.validIparamName %>

1
2
3
4
5
6
7
8
"schema": {
        "method": "GET",
        "host": "<%= iparam.domain %>.myfreshworks.com",
        "path": "/crm/sales/api/contacts/view/[:view_id]",  
        "headers": {
          "Authorization": "Bearer <%= iparam.api_key %>",
          "Content-Type": "application/json"
        }}

encode()
This function enables encoding secure iparams that are passed as part of the request.
Syntax: <%= encode(iparam.validIparamName) %>
Example: "Authorization": "Bearer <%= encode(iparam.api_key) + ':x' %>"

Use the following syntax to declare a template variable that is populated with contextual data, passed through the runtime API that invokes the request template.

1
<%= context.variableName %>

1
2
3
4
5
6
7
8
9
10
11
"schema": {
        "method": "GET",
        "host": "<%= iparam.domain %>.myfreshworks.com",
        "path": "/crm/sales/api/contacts/view/[:view_id]",
        "headers": {
          "Authorization": "Bearer <%= iparam.api_key %>",
          "Content-Type": "application/json"
        }}
        "query": {
          "page": "<%= context.page %>"
    }

1
<%= access_token %>

1
2
3
4
5
6
7
8
9
10
11
12
"schema": {
        "method": "GET",
        "host": "app.asana.com",
        "path": "/api/1.0/workspaces",
        "headers": {
          "Authorization": "bearer <%= access_token %>",
          "Content-Type": "application/json"
        }
      },
    "options": {
      "isOAuth": true
    }

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
{
      "getContacts": {
        "schema": {
          "method": "GET",
          "host": "<%= iparam.domain %>.myfreshworks.com",
          "path": "/crm/sales/api/contacts/view/[:view_id]",    
          "headers": {
            "Authorization": "Bearer <%= iparam.apikey %>",
            "Content-Type": "application/json"
          },
          "query": {
            "page": "<%= context.page %>"
          }
        },
        "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"
          }
        }
      }
    }

Declare templates

1. From the app’s root directory, navigate to the manifest.json file.
2. Under product.<productName>, use the following syntax and create a requests attribute. Copied Copy

   1
   2
   3
   4
   5
   "requests": {
         "<requestTemplateName>":{},
         "<requestTemplateName1>": {}
       …
     }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "platform-version": "2.3",
    "product": {
      "freshworks_crm": {
      "events": {
          "onContactCreate": {
          "handler": "onContactCreateHandler"
          }
      },
      "requests": {
        "createContact": {},
        "getContacts": {}
      }
      }
    },
    "engines": {
      "node": "18.12.1",
      "fdk": "9.0.0"
    }
  }

Invoke templates

General syntax of invokeTemplate()

1. In the front-end HTML files (such as iparams.html), include the client JS resource as follows: Copied Copy

   1
   <script src="{{{appclient}}}"></script>

   Note: If your existing app uses Request method with domain whitelisting and if you are migrating your app to use the templated request method, in the front-end HTML files (such as iparams.html), replace the existing client JS resource (<script src="https://static.freshdev.io/fdk/2.0/assets/fresh_client.js"> </script>) with <script src="{{{appclient}}}"></script>

2. Navigate to the app.js file and include the invokeTemplate() method using the following syntax. Copied Copy

   1
   2
   3
   4
   client.request.invokeTemplate(requestTemplateName, {
       context: {}, 
       body: JSON.stringify(body),
     });

1
2
3
4
$request.invokeTemplate(requestTemplateName, {
    context: {}, 
    body: JSON.stringify(body),
  });

invokeTemplate() arguments

• requestTemplateName (MANDATORY, string): Identifier of the request template in config/requests.json and the request in manifest.json. The requestTemplateName must be the same in the app code, configuration (config/requests.json), and declaration (manifest.json).
• An object with the following optional attributes:
  • context (object): All contextual data that the template requires, specified as key-value pairs of <variableName>:<variableValue>.<variableName> must be the same as that used in config/requests.json to receive contextual data.
  
  
  • body (string): Request body.
    
    Response caching: Requests made through the request method are governed by rate limits. To prevent repetitive calls from breaching the rate limits, the request method comes with an opt-in response caching feature, for front-end apps. The cache and ttl options available as part of the invokeTemplate() method, enable browsers to cache the responses that are retrieved from third-party calls. The responses are cached in the Browser’s local storage. For requests that haven’t changed since the last call, the response is retrieved from the cache. This conserves the app’s rate limits as the number of requests made to the third-party are conserved.
  
  
  • cache (boolean): This option is valid only for front-end apps and can be used only with client.request.invokeTemplate(). cache specifies whether a successful response to the HTTP request is cached in the browser’s local storage. The cached response persists in the local storage for a time specified by the ttl value. If no ttl is specified, the response is cached for the default ttl value of 60000 milliseconds.
    Possible values: true, false
  
  
  • ttl (number): This option is valid only for front-end apps, when cache is true, and can be used only with client.request.invokeTemplate(). If cache is true, ttl (time to live) is the duration (specified in milliseconds) for which the response is stored in the cache.
    Default value: 60000

Response

1
2
3
4
5
6
7
8
9
{
    "status" : 200,
    "headers":
    {
      "Content-Length": 20,
      "Content-Type": "application/json;charset=utf-8"
    },
    "response": ‘{ "content": "Test message"}’
  }

1
2
3
4
5
6
7
8
9
{
    "status" : 502,
    "headers":
    {
      "Content-Type": "application/json;charset=utf-8"
    },
    "response": "Error in establishing the connection.",
    "errorSource": "PLATFORM"
  }

Sample app.js

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
// ------
  // 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 messages for page 2
    await client.request.invokeTemplate("getContacts", {
      context: {
        page: 2,
      },
    });
  }

Sample app.js for caching responses

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
// ------
  // 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 contacts for page 2
    await client.request.invokeTemplate("getContacts", {
      context: {page: 2},
      cache: true,
      ttl: 70000
  });
  }

Sample server.js

1
2
3
4
5
6
7
8
exports = {
    async onMessageCreateHandler(args) {
      // Send a copy of the newly created message to the external API
      await $request.invokeTemplate("sendToExternalAPI", {
        body: JSON.stringify(args.data),
      });
    },
  };

Test apps that use request method

In the local testing of apps that use the Request Method to make third-party HTTP requests, you can specify a value for the request timeout.

• Use the REQUEST_TIMEOUT parameter along with the fdk run command as follows:
  Syntax REQUEST_TIMEOUT=<timeout in milliseconds> fdk run Example: REQUEST_TIMEOUT=10000 fdk run
• Navigate to the .env file and add the following:
  export REQUEST_TIMEOUT=<timeout in milliseconds> Example: export REQUEST_TIMEOUT=10000

For information on how to test an app that uses the Request API feature, see Test your App.

Request method with domain whitelisting

In this request method, the hosts to which the apps are expected to make request calls are whitelisted in manifest.json. The other attributes such as methods, paths, query parameters, header parameters, options, and request body are dynamically generated during runtime.

Usage

The Request method should be defined in the app.js file by using the following syntax.

1
2
3
4
5
6
7
8
9
10
client.request.get("URL", options)
    .then(
      function(data) {
        //handle "data"
        //"data" is a json string with status, headers, and response.
      },
      function(error) {
        //handle failure
      }
    );

The Request method should be defined in the server.js file by using the following syntax.

1
2
3
4
5
6
7
8
9
10
$request.get("URL", options)
    .then(
      function(data) {
        //handle "data"
        //"data" is a json string with status, headers, and response.
      },
      function(error) {
        //handle failure
      }
    );

The following table lists the parameters and their description.

Using Iparams

Iparams can be used in requests as part of the following:

• Header
• URL Copied Copy

  1
  https://passport-office.com/user?id=<%= iparam.passport %>

• Body Copied Copy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  client.request.post("https://helloworld.myfreshworks.com/api/contacts", {
        headers: {
          Authorization: "Basic <%= encode(iparam.username + ':' + iparam.password) %>"
        },
        body: JSON.stringify({
          status: 2,
          priority: 1,
          description: "Test",
          subject: "<%= iparam.subjectPrefix %> Hello there",
          email: "tom@outerspace.com"
        })
       });

  EXPAND ↓

Note:
Secure iparams can only be used in the request header. If secure iparams are present in the request body or URL, the fdk run command displays an error message Secure iparam cannot be used in request body or URL.

Sample requests

Request method should be defined in the app.js file, you can use the following sample requests for reference.

1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Token token=<%= iparam.api_key %>"};
  var options = { headers: headers };
  var url = "https://sample.myfreshworks.com/itil/requesters/5.json";
  client.request.get(url, options)
  .then (
  function(data) {
    console.log(data);
  },
  function(error) {
    console.log(error);
  });

If the request is successful, data is returned in the following format. In case a network or 429/5xx HTTP error occurs, the app will retry the request a number of times to obtain the response. Here, attempts is the number of attempts after which the request has returned a response.

1
2
3
4
5
6
7
8
9
10
{
    status : 200,
    headers:
    {
      "Content-Length": 20,
      "Content-Type": "application/json;charset=utf-8"
    },
    response: "{ "Name": "Rachel"}",
    "attempts": 1
}

If the request fails, an error response is returned in the following format.

1
2
3
4
5
6
7
8
9
{
    status : 401,
    headers: {
      "Content-Type": "application/json;charset=utf-8"
   },
   response: [{"message": "Session expired or invalid",
   "attempts": 1,
  "errorCode": "INVALID_SESSION_ID"}]
}

If the request fails due to an error from the app, the error response is returned in the following format.

1
2
3
4
5
6
7
8
9
10
{
    "status" : 400,
    "headers":
    {
      "Content-Type": "application/json;charset=utf-8"
    },
    "response": "This domain has not been whitelisted.",
    "attempts": 2,
    "errorSource": "APP"
  }

1
2
3
4
5
6
7
8
9
10
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);
  });

1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Token token=<%= iparam.api_key %>"};
  var options = { headers: headers, body: "Hello world"};
  var url = "https://sample.myfreshworks.com/api/contacts";
  client.request.post(url, options)
  .then (
  function(data) {
    console.log(data);
  },
  function(error) {
    console.log(error);
  });

For information on how to make an OAuth request, see Usage in the OAuth section.

Testing

IP Ranges

Here is the list of IPs you must whitelist when using Request APIs if IP whitelisting is enabled on the Freshdesk support portal or you wish to whitelist requests from your app.

Errors

In case of request failure, a status code is displayed along with a message to help troubleshoot the issue.

An example of a status code and message is as follows.

1
2
3
4
5
6
7
8
9
10
11
{
  "status": 401,
  "headers": {
    "Content-Type": "text/plain"
  },
  "response": [{
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID"
  }]

}

The following table lists all the supported status code.