Tutorials>Visualize Your Business Communications History

Learn how to build a Web app to access your company's call log database by using the RingCentral call-log API, process the data and display the company's communications history on Google graphs. Click the "Start Tutorial" button below to start.

Start Tutorial

Requirements

  • You must have a RingCentral developer account. If you don't have one, click here to create a free developer account.

  • You also have to create a RingCentral app with the "ReadCallLog" permission to retrieve the app Client Id and Client Secret for using with this tutorial.

Clone the project from GitHub

Run the commands shown on the right-hand side to clone the project from GitHub to your local machine.

Browse to the project folder on your local machine and install the dependency libraries.

Copy the dotenv to create the .env.

Set environment parameters and login credentials

Open the .env file and specify your app credentials, RingCentral sandbox account's username and password.

You are good to run the demo now:

$ node index.js

Open your browser at http://localhost:3002

Add the From and To date pickers

Now, let's create a web page and add 2 date pickers for taking the dates. The From Date and To Date will be used to specify the date range we want to read the call log data.

The call-log API also takes other query configurations, but they are less frequently needed in this tutorial so we hide them to save some space and make them visible when we click the Show Options button.

Add the Phone number and Extension number filters.

  • If the phoneNumber parameter is specified, the API returns call logs (of both incoming and outgoing calls) containing the mentioned phone number of a caller or callee.

  • If the extensionNumber is specified, the API returns call logs for that particular extension only.

See call-log API reference

Add the Direction and Type filters.

  • If the direction parameter is specified as Inbound or Outbound, the API returns call logs for the specified direction only. By default, the API returns call logs for both directions.

  • If the type parameter is specified as Voice or Fax, the API returns call logs for the specified type only. By default, the API returns call logs for both types.

See call-log API reference

Add the Transport and View filters.

  • If the transport parameter is specified as PSTN or VoIP, the API returns call logs for the specified transport only. By default, the API returns call logs for both transport modes.

  • The view parameter can be specified as Simple or Detailed, the API returns call logs with basic information or extended data (such as billing and leg type information), respectively. The default value is Simple.

See call-log API reference

Add the Read blocked and With recording

  • If the readBlocked flag is true, the API returns call logs for all calls within the date range, including calls from and to blocked numbers. The default value is true.

  • If the withRecoding flag is true, the API returns call logs for only calls with call recording. The default value is false.

See call-log API reference

Add the dropdown list to define the access level

We also control the access level by adding the control parameter to tell our server how to access the call log.

Note: This is not the call-log API's parameter! It will be passed to our server for defining the API's access level.

Create API query parameters - Client side

We detect specified parameters and make a POST request to send them to our server side.

Since the access level parameter is our own control, we pass the parameter to the POST query path.

var url = "readlogs?access=" + $('#access_level').val();

Instantiate the RingCentral Node JS SDK

First, we create the SDK instance rcsdk and initialize it with the app client Id and client Secret.

Then we call the rcsdk.platform() function to get the instance of the platform component. The platform instance will be used later to login and call RingCentral APIs.

Login to RingCentral account

To login RingCentral account, we call the platform.login() function with the account's username and password predefined in the .env file.

Call the call-log API

After logged in successfully, we call the readCallLogs() function and we detect if the request is made to access the account level or the extension level then we define the endpoint accordingly.

We receive the call-log API's query parameters from the client as a JSON object in the req.body. We just use the platform instance to call the call-log API as highlighted below:

platform.get(endpoint, req.body)

Retrieve call log records

Assumed that the API call was successful and we get the response from RingCentral server. We then extract the records array and send it to our client side.

If the call failed, we catch the error and respond to our client with an error message accordingly.

Parse call log data

Upon the arrival of the response from our server, we check the response to see if it is an error or not.

If the response is call log data, we create a CallLogsData object passing along the call log data. The CallLogsData object is a class which parses the call log data and process the information to make them ready for displaying on graphs.

Process call log data

In the CallLogsData class constructor, we iterate thru the call log records array, detect the call type then count voice calls and faxes separately for different directions.

We also check the record.result to identify if a call was resulted in a missed call or has a voicemail.

To display overall calls results and actions, we implement a function __addItemToExistingList() to parse and keep the information in the following arrays:

this.faxInboundActions = []
this.faxOutboundActions = []

this.voiceInboundActions = []
this.voiceOutboundActions = []

this.faxInboundResults = []
this.faxOutboundResults = []

this.voiceInboundResults = []
this.voiceOutboundResults = []

Process call location

To prepare for displaying call location on the Google map, we parse the location data and map the call location and count number in the following arrays:

this.inboundCallLocations = []
this.outboundCallLocations = []

Generate calls density data

To sketch calls density around the clock, we implement the __createCallsDensity() function to parse the startTime of each call, convert it to local time then map it to the 24-hour time scale.

this.timeSliceInbound = new Array(24)
this.timeSliceOutbound = new Array(24)
this.timeSliceMissedCalls = new Array(24)
this.timeSliceVoicemails = new Array(24)

Display information on charts

Finally, we implement the drawGraphs() function which will be called automatically after we read call log data from the server or whenever we select a new item from the Select Graphs dropdown list.

Within the drawGraphs() function, we call functions to collect relevant data and draw the chart accordingly.