RingCentral Line of Business Analytics APIs Quick Start

Last updated: 2022-05-13 Contributors Byrne Reese
Edit this page

In this quick start guide, we are going to access call performance data via using Java/C# or Node.JS based command line application.

Analytics API is in beta - please request access

To call the Analytics API your application needs to have 'Analytics' permission. If you are using an application that doesn't have that permission, you can reach out to our support team with your application's Client ID and request that the 'Analytics' permission be added.

Create App and Get Credentials

The first thing we need to do is create an app in the RingCentral Developer Console. This can be done quickly by clicking the "Create Call Performance Analytics App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create Analytics App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Select "REST API App" under "What type of app are you creating?" Click "Next."
  4. Under "Authentication" select "Password-based auth flow."
  5. Under "Security" add the following permissions:
    • Analytics
  6. Under "Security" select "This app is private and will only be callable using credentials from the same RingCentral account."

Download and edit a .env file

Follow the instructions found in our guide to running Developer Guide code samples. Or:

  1. Download our env-template and save it as a file named .env.
  2. Edit your newly downloaded .env file, setting its variables with the proper values for the app you created above.

Download your request template

The payload for an Analytics API request in non-trivial given the many filtering and reporting options available to developers. To assist you in making your first API call, we have provided you with two sample requests that the quick start sample code make use of by reading their contents off of the filesystem. Download these files to the same directory as your quick start script.

{
  "grouping": {
    "groupBy": "CompanyNumbers",
    "ids": []
  },
  "timeSettings": {
    "timeRange": {
      "timeFrom": "2022-03-01T05:52:17.745Z",
      "timeTo": "2022-05-01T05:52:17.745Z"
    },
    "advancedTimeSettings": {
      "timeZone": "Europe/Moscow",
      "includeDays": [
        "Sunday"
      ],
      "includeHours": [
        {
          "from": "00:00",
          "to": "23:59"
        }
      ]
    }
  },
  "additionalFilters": {
    "direction": "Inbound",
    "origin": "Internal",
    "callResponse": "Answered",
    "callResult": [
      "Completed"
    ],
    "callSegments": [
      {
        "callSegment": "Ringing",
        "callSegmentLength": {
          "minValueSeconds": 0,
          "maxValueSeconds": 200
        }
      }
    ],
    "callActions": [
      {
        "callAction": "HoldOff"
      }
    ],
    "companyHours": "BusinessHours",
    "callDuration": {
      "minValueSeconds": 0,
      "maxValueSeconds": 200
    },
    "timeSpent": {
      "minValueSeconds": 0,
      "maxValueSeconds": 200
    },
    "callerExtensionIds": [],
    "calledExtensionIds": [],
    "calledNumbers": []
  },
  "responseOptions": {
    "counters": {
      "allCalls": {
        "aggregationType": "Sum"
      },
      "callsByDirection": {
        "aggregationType": "Sum"
      },
      "callsByOrigin": {
        "aggregationType": "Sum"
      },
      "callsByResponse": {
        "aggregationType": "Sum"
      },
      "callsSegments": {
        "aggregationType": "Sum"
      },
      "callsByResult": {
        "aggregationType": "Sum"
      },
      "callsByCompanyHours": {
        "aggregationType": "Sum"
      },
      "callsByActions": {
        "aggregationType": "Sum"
      },
      "callsByType": {
        "aggregationType": "Sum"
      }
    },
    "timers": {
      "allCallsDuration": {
        "aggregationType": "Sum"
      },
      "callsDurationByDirection": {
        "aggregationType": "Sum"
      },
      "callsDurationByOrigin": {
        "aggregationType": "Sum"
      },
      "callsDurationByResponse": {
        "aggregationType": "Sum"
      },
      "callsSegmentsDuration": {
        "aggregationType": "Sum"
      },
      "callsDurationByResult": {
        "aggregationType": "Sum"
      },
      "callsDurationByCompanyHours": {
        "aggregationType": "Sum"
      },
      "callsDurationByType": {
        "aggregationType": "Sum"
      }
    }
  }
}
{
  "grouping": {
    "groupBy": "Users",
    "ids": []
  },
  "timeSettings": {
    "timeRange": {
      "timeFrom": "2022-03-01T00:00:00.877Z",
      "timeTo": "2022-05-01T04:01:33.877Z"
    },
    "advancedTimeSettings": {
      "timeZone": "Europe/Moscow",
      "includeDays": [
        "Sunday"
      ],
      "includeHours": [
        {
          "from": "00:00",
          "to": "23:59"
        }
      ]
    }
  },
  "additionalFilters": {
    "direction": "Inbound",
    "origin": "Internal",
    "callResponse": "Answered",
    "callResult": [
      "Completed"
    ],
    "callSegments": [
      {
        "callSegment": "Ringing",
        "callSegmentLength": {
          "minValueSeconds": 0,
          "maxValueSeconds": 200
        }
      }
    ],
    "callActions": [
      {
        "callAction": "HoldOff"
      }
    ],
    "companyHours": "BusinessHours",
    "callDuration": {
      "minValueSeconds": 0,
      "maxValueSeconds": 200
    },
    "timeSpent": {
      "minValueSeconds": 0,
      "maxValueSeconds": 200
    },
    "callerExtensionIds": [],
    "calledExtensionIds": [],
    "calledNumbers": [],
    "callType": [
      "Direct"
    ]
  },
  "responseOptions": {
    "counters": {
      "allCalls": true,
      "callsByDirection": true,
      "callsByOrigin": true,
      "callsByResponse": true,
      "callsSegments": true,
      "callsByResult": true,
      "callsByCompanyHours": true,
      "callsByActions": true,
      "callsByType": true
    },
    "timers": {
      "allCallsDuration": true,
      "callsDurationByDirection": true,
      "callsDurationByOrigin": true,
      "callsDurationByResponse": true,
      "callsSegmentsDuration": true,
      "callsDurationByResult": true,
      "callsDurationByCompanyHours": true,
      "callsDurationByType": true
    }
  }
} 

Call the Analytics API

Create a Node.JS project

$ npm init

Install RingCentral Node.JS SDK & DOTENV Module

$ npm install @ringcentral/sdk dotenv

Create and edit 'index.js' file

Create a file called index.js. Be sure the values in your .env file have been set properly as that is where your credentials will be loaded.

const RC_SDK = require('@ringcentral/sdk').SDK
require('dotenv').config();
const fs = require("fs");

RINGCENTRAL_CLIENTID = process.env.RC_CLIENT_ID;
RINGCENTRAL_CLIENTSECRET = process.env.RC_CLIENT_SECRET;
RINGCENTRAL_SERVER = RC_SDK.server.sandbox;

RINGCENTRAL_USERNAME = process.env.RC_USERNAME;
RINGCENTRAL_PASSWORD = process.env.RC_PASSWORD;
RINGCENTRAL_EXTENSION = process.env.RC_EXTENSION;

let rcsdk = new RC_SDK({
  server: RINGCENTRAL_SERVER,
  clientId: RINGCENTRAL_CLIENTID,
  clientSecret: RINGCENTRAL_CLIENTSECRET
});

let platform = rcsdk.platform();

platform.login({
  username: RINGCENTRAL_USERNAME,
  password: RINGCENTRAL_PASSWORD,
  extension: RINGCENTRAL_EXTENSION
  }).then(async function(){
    try {
      let aggregateJSONString = fs.readFileSync("aggregate-request-body.json");
      let aggregateJSONBody = JSON.parse(aggregateJSONString);
      let aggregateResult = await platform.post("/analytics/phone/performance/v1/accounts/~/calls/aggregate", aggregateJSONBody);
      let response = await aggregateResult.json();
      console.log("-----AGGREGATE DATA------");
      console.log(response.data[0]);
    }
    catch (e) {
      console.log(e.message);
    }
  }).then(async function(){
  try {
      let timelineJSONString = fs.readFileSync("timeline-request-body.json");
      let timelineJSONBody = JSON.parse(timelineJSONString);
      let timelineResult = await platform.post("/analytics/phone/performance/v1/accounts/~/calls/timeline?interval=Week", timelineJSONBody);
      let response = await timelineResult.json();
      console.log("-----TIMELINE DATA------");
      console.log(response.data[0]);
    }
    catch (e) {
      console.log(e.message);
    }
  }); 

Run your code

You are almost done. Now run your script.

$ node index.js

Create a C# project

  • Choose Console Application .Net or .Net Core
  • Select Target Framework Version
  • Enter project name "WebAPIClient"
  • Add NuGet package RingCentral.Net SDK version 5.9.0 or newer
  • Create a JSON file "aggregate-request-body.json" that can be referenced in "JSON Request Body"
  • Create a JSON file "timeline-request-body.json" that can be referenced in "JSON Request Body"

Edit the file 'Program.cs'

Be sure to edit the variables in ALL CAPS with your app and user credentials.

using System;
using System.IO;

using RingCentral;
using Newtonsoft.Json.Linq;

namespace WebAPIClient {
  class Program {

    private static string RINGCENTRAL_CLIENTID = "";
    private static string RINGCENTRAL_CLIENTSECRET = "";
    // Set this boolean value to true if you wish to use Production Credentials
    private static bool RINGCENTRAL_PRODUCTION = false;
    private static string RINGCENTRAL_USERNAME = "";
    private static string RINGCENTRAL_PASSWORD = "";
    private static string RINGCENTRAL_EXTENSION = "";

    static RingCentral.RestClient rcClient;

    static void Main(string[] args){
      rcClient = new RingCentral.RestClient(RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_PRODUCTION);
      rcClient.Authorize(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD).Wait();
      getAggregateData(rcClient);
      getTimelineData(rcClient);
    }   
    private static async void getAggregateData(RingCentral.RestClient restClient) {
      var jsonRequestObject = loadJson("aggregate-data-request.json");
      var response = await rcClient.Post("/analytics/phone/performance/v1/accounts/~/calls/aggregate", jsonRequestObject);
      Console.WriteLine("---- Aggregate Data ----");
      Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
    private static async void getTimelineData(RingCentral.RestClient rcClient) {     
      var jsonRequestObject = loadJson("timeline-data-request.json");
      var response = await rcClient.Post("/analytics/phone/performance/v1/accounts/~/calls/timeline?interval=Day", jsonRequestObject);
      Console.WriteLine("---- TimeLine Data ----");
      Console.WriteLine(await response.Content.ReadAsStringAsync());
    }

    // Helper function to load the JSON file, make sure to edit this based on your requirements
    private static JObject loadJson(string filePath) {
      string result = string.Empty;
      using (StreamReader r = new StreamReader(filePath)) {
        var jsonString = r.ReadToEnd();
        JObject jsonObject = JObject.Parse(jsonString);
        return jsonObject;
      }
    }
  }
}

Run Your Code

You are almost done. Now run your app by typing in the command line

$ cd WebAPIClient
$ dotnet run

Create a Java Gradle/Maven project

  • Make sure you have JDK 11 or newer installed in our machine
  • Install RC Java SDK 2.2.0 or latest from GitHub or Maven Central
  • Create a new Java Class called "App.java"
  • Create a JSON file in the following path inside your project "src/main/resources/aggregate-request-body.json" that can be referenced in "JSON Request Body"
  • Create a JSON file in the following path inside your project "src/main/resources/timeline-request-body.json" that can be referenced in "JSON Request Body"

Edit the file 'App.java'

Be sure to edit the variables in ALL CAPS with your app and user credentials.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Paths;

import com.ringcentral.RestClient;
import com.ringcentral.definitions.TokenInfo;

public class App {

  static String RINGCENTRAL_CLIENT_ID = "";
  static String RINGCENTRAL_CLIENT_SECRET = "";
  static String RINGCENTRAL_USERNAME = "";
  static String RINGCENTRAL_PASSWORD = "";
  static String RINGCENTRAL_EXTENSION = "";

  private static final String AGGREGATE_API_PATH = "/analytics/phone/performance/v1/accounts/~/calls/aggregate";
  private static final String TIMELINE_API_PATH = "/analytics/phone/performance/v1/accounts/~/calls/timeline?interval=Week";
  // Update the URL based on if you're running using RingCentral Sandbox or Production Credentials. Currently set for sandbox
  private static String RINGCENTRAL_SERVER_URL = "https://platform.devtest.ringcentral.com";

  public static void main(String[] args) throws Exception {

    RestClient rc = new RestClient(RINGCENTRAL_CLIENT_ID, RINGCENTRAL_CLIENT_SECRET, RINGCENTRAL_SERVER_URL);
    TokenInfo token = rc.authorize(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD);
    String accessToken = token.access_token;

    String aggregate_json_file_path = "src/main/resources/aggregate-request-body.json";
    String timeline_json_file_path = "src/main/resources/timeline-request-body.json";
    String aggregateJsonStr = App.readFileAsString(aggregate_json_file_path);
    String timelineJsonStr = App.readFileAsString(timeline_json_file_path);

    try {
      HttpResponse<String> aggreageteHttpResponse = getData(aggregateJsonStr, AGGREGATE_API_PATH, accessToken);
      System.out.println("---AGGREGATE API RESPONSE---");
      System.out.println(aggreageteHttpResponse.statusCode());
      System.out.println(aggreageteHttpResponse.body());
      HttpResponse<String> timelineHttpResponse = getData(timelineJsonStr, TIMELINE_API_PATH, accessToken);
      System.out.println("---TIMELINE API RESPONSE---");
      System.out.println(timelineHttpResponse.statusCode());
      System.out.println(timelineHttpResponse.body());
    }
    catch (Exception e) {
      e.printStackTrace();
    }
  }

  static HttpResponse<String> getData(String jsonStr, String endpoint, String accessToken) throws Exception {
    HttpClient httpClient = HttpClient.newHttpClient();
    HttpRequest httpRequest = HttpRequest.newBuilder()
      .header("Content-Type", "application/json")
      .header("Authorization", "Bearer " + accessToken)
      .uri(URI.create(RINGCENTRAL_SERVER_URL + endpoint))
      .POST(HttpRequest.BodyPublishers.ofString(jsonStr))
      .build();

    HttpResponse<String> httpResponse = httpClient.send(httpRequest, HttpResponse.BodyHandlers.ofString());
    return httpResponse;
  }

  static String readFileAsString(String file) throws Exception {
    return new String(Files.readAllBytes(Paths.get(file)));
  }
} 

Build & Run Your Code

You are almost done. Now run your app by typing in the command line

$ javac App.java
$ java App

Sample Applications on GitHub

You can reference the following sample applications from GitHub in case you're looking for a completed project or run into any errors: