You should use the Request method to avoid exposing sensitive information, such as API keys or user credentials, when you make HTTP requests to third-party domains as agents will be able to inspect these values in a browser and access them. The other benefit is Cross-Origin Resource Sharing (CORS) support as requests are routed through a proxy.

Note:
1. All apps that make requests to third-party domains must use the Request method or they will not be published in Freshworks Marketplace.
2. The timeout for requests is six seconds.
3. There is a rate limit of 50 requests per minute per app per account.
4. In the response of a request call made using the Request API, the Content-Type header attribute specifies the response format. The accepted response formats are:
- application/json
- application/jsonp
- application/vnd.api+json
- application/xml
- text/plain
- text/html
- text/xml
- text/javascript

Take a look at the Request Freshdesk sample app for a demonstration of this feature. The same functionality is available in Freshteam.

Usage

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
  $request.post("https://api.freshteam.com/agents", {
    headers: {
      Authorization: "Bearer <%= encode(iparam.freshteamApiToken) %>"
    },
    body: JSON.stringify({
      <valid JSON object>
  });

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

For API requests that require authentication, you may need to encode the auth header in base64 format.

1
2
3
4
5
6
7
8
9
10
11
var headers = {"Authorization": "Basic <%= encode(iparam.api_key) %>"};
  var options = { headers: headers };
  var url = "https://sample.crm.com/contacts/5.json";
  $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 times 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 due to an error from the platform, an error response is returned in the following format.

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

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";
  $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": "Basic <%= encode(iparam.api_key) %>"};
  var options = { headers: headers, body: "Hello world"};
  var url = "https://sample.crm.com/contacts.json";
  $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

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 the App.

IP Ranges

Here is the list of IPs you must whitelist when using the Request method if IP whitelisting is enabled on the Freshteam Account or you wish to whitelist requests from your app.

Errors

In case of failure when making requests, 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
{
  "status": 401,
  "headers": {
    "Content-Type": "text/plain"
  },
  "response": "Session expired or invalid",
  "errorSource": "APP/PLATFORM"
}

The following table lists all the supported status code.