RingCentral Call Performance API Quick Start

Last updated: 2021-08-24 Contributors Byrne Reese
Edit this page

In this quick start guide, we are going to access call performance data via the command line using CURL utility in just a few minutes. Let's get started.

Create an App if you don't have one already

The first thing we need to do is create an app in the RingCentral Developer Portal. 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:
    • None
  6. Under "Security" select "This app is private and will only be callable using credentials from the same RingCentral account."

Get production credentials (not Sandbox Credentials)

In the RingCentral Developer Dashboard, navigate to your App -> Dashboard -> Credential and note down the following:

  • App Server URL which should be https://platform.ringcentral.com . This is the URL for RingCentral Production Environment and we will be doing our development in Production Environment for this API.

Please contact us to get your application graduated to production so you can access production credentials if you don't have them already. You need to provide us the following so we can move your application to production enviornment:

  • Client ID
  • Client Secret

These will be used when making API calls either via Command Line (CURL), POSTMAN or in your application codebase.

Add Authentication if you don't have RingCentral authentication in place

There are multiple ways to provide authentication support for your application for RingCentral users. This will depend on the type of authentication mechanism you chose when you created your application. For more information about how to use OAuth 2.0 with your application please refer to this guide

Make the API Call C# or using CommandLine

Select your preferred language below.

Create a Visual Studio project

  • Choose Console Application .Net or .Net Core
  • Select Target Framework Version
  • Enter project name "AnalyicsAPIClient"
  • Add NuGet package RingCentral.Net --version 5.5.0 to use it for setting up authentication
  • Add RestSharp package to use it for HTTP Request

Note: You need to implement authentication (OAuth, Basic Auth etc) based on how you configured your application when creating it in the RingCentral Dev Portal.

Edit the file 'Program.cs'

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

using System;
using RestSharp;
using RestSharp.Authenticators;

namespace AnalyticsAPIClient {
  class Program {
    static void Main(string[] args) {
      var client = new RestClient("https://platform.ringcentral.com/restapi/v1.0/account/~/analytics/performance/calls/aggregate");
      client.Timeout = -1;
      var request = new RestRequest(Method.POST);
      request.AddHeader("Content-Type", "application/json");
      request.AddHeader("Accept", "application/json");
      request.AddHeader("Authorization", "YOUR BEARER TOKEN GOES HERE");
      var body= @"{" + "\n" +
                @"  ""grouping"": {" + "\n" +
                @"    ""groupBy"": ""Queues""," + "\n" +
                @"    ""ids"": [" + "\n" +
                @"      " + "\n" +
                @"    ]" + "\n" +
                @"  }," + "\n" +
                @"  ""timeRange"": {" + "\n" +
                @"    ""timeFrom"": ""2021-08-14T19:06:59.029Z""," + "\n" +
                @"    ""timeTo"": ""2021-08-18T19:06:59.029Z""" + "\n" +
                @"  }," + "\n" +
                @"  ""additionalFilters"": {" + "\n" +
                @"    ""direction"": ""Inbound""," + "\n" +
                @"    ""origin"": ""Internal""," + "\n" +
                @"    ""callResponse"": ""Answered""," + "\n" +
                @"    ""callResponseType"": [" + "\n" +
                @"      ""InboundDirect""" + "\n" +
                @"    ]," + "\n" +
                @"    ""callResult"": [" + "\n" +
                @"      ""Completed""" + "\n" +
                @"    ]," + "\n" +
                @"    ""callSegments"": [" + "\n" +
                @"      {" + "\n" +
                @"        ""callSegment"": ""Ringing""" + "\n" +
                @"      }" + "\n" +
                @"    ]," + "\n" +
                @"    ""callActions"": [" + "\n" +
                @"      {" + "\n" +
                @"        ""callAction"": ""HoldOff""" + "\n" +
                @"      }" + "\n" +
                @"    ]," + "\n" +
                @"    ""companyHours"": ""BusinessHours""," + "\n" +
                @"    ""callDuration"": {" + "\n" +
                @"      ""minValueSeconds"": 0," + "\n" +
                @"      ""maxValueSeconds"": 100" + "\n" +
                @"    }," + "\n" +
                @"    ""timeSpent"": {" + "\n" +
                @"      ""minValueSeconds"": 0," + "\n" +
                @"      ""maxValueSeconds"": 100" + "\n" +
                @"    }," + "\n" +
                @"    ""queueSla"": ""InSla""" + "\n" +
                @"  }," + "\n" +
                @"  ""responseOptions"": {" + "\n" +
                @"    ""counters"": {" + "\n" +
                @"      ""allCalls"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByDirection"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByOrigin"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByResponse"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByResponseType"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsBySegment"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByResult"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByActions"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByCompanyHours"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsByQueueSla"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }" + "\n" +
                @"    }," + "\n" +
                @"    ""timers"": {" + "\n" +
                @"      ""totalCallLength"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""timeSpentByCallSegments"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callLengthByDirection"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callLengthByOrigin"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callLengthByResponse"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callLengthByResponseType"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callLengthByResult"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsLengthByCompanyHours"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }," + "\n" +
                @"      ""callsLengthByQueueSla"": {" + "\n" +
                @"        ""aggregationType"": ""Sum""" + "\n" +
                @"      }" + "\n" +
                @"    }" + "\n" +
                @"  }" + "\n" +
                @"}";
      request.AddParameter("application/json", body,  ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      Console.WriteLine(response.Content);       
    }
  }
}

Run Your Code

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

dotnet run

Obtain Access Token using RingCentral supported Authentication

In this example, we are making an API request to the RingCentral platform using Password Flow Authentication. Once the command is executed, copy the 'access_token' string from the response body.

curl --location -g --request POST 'https://platform.ringcentral.com/restapi/oauth/token' \
     --header 'Authorization: {{basic_auth_header}}' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
     --data-urlencode 'grant_type=password' \
     --data-urlencode 'username={{RC_USERNAME}}' \
     --data-urlencode 'password={{RC_PASSWORD}}' \
     --data-urlencode 'extension={{RC_EXTENSION}}'

Make a HTTP POST Request to get 'call performance data'

In this example, we are making the API request and sending the JSON describing our requirements. To understand what the various JSON properties please refer to the API Reference. In this step, please make sure to update the "header" information with your 'access_token' string obtained in the previous step.

curl --location --request POST 'https://platform.ringcentral.com/restapi/v1.0/account/~/analytics/performance/calls/aggregate' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header '{Your Access Token goes here}' \
    --data-raw '{
                  "grouping": {
                    "groupBy": "Queues",
                    "ids": [
                    ]
                  },
                  "timeRange": {
                    "timeFrom": "2021-08-14T19:06:59.029Z",
                    "timeTo": "2021-08-18T19:06:59.029Z"
                  },
                  "additionalFilters": {
                    "direction": "Inbound",
                    "origin": "Internal",
                    "callResponse": "Answered",
                    "callResponseType": [
                      "InboundDirect"
                    ],
                    "callResult": [
                      "Completed"
                    ],
                    "callSegments": [
                      {
                        "callSegment": "Ringing"
                      }
                    ],
                    "callActions": [
                      {
                        "callAction": "HoldOff"
                      }
                    ],
                    "companyHours": "BusinessHours",
                    "callDuration": {
                      "minValueSeconds": 0,
                      "maxValueSeconds": 100
                    },
                    "timeSpent": {
                      "minValueSeconds": 0,
                      "maxValueSeconds": 100
                    },
                    "queueSla": "InSla"
                  },
                  "responseOptions": {
                    "counters": {
                      "allCalls": {
                        "aggregationType": "Sum"
                      },
                      "callsByDirection": {
                        "aggregationType": "Sum"
                      },
                      "callsByOrigin": {
                        "aggregationType": "Sum"
                      },
                      "callsByResponse": {
                        "aggregationType": "Sum"
                      },
                      "callsByResponseType": {
                        "aggregationType": "Sum"
                      },
                      "callsBySegment": {
                        "aggregationType": "Sum"
                      },
                      "callsByResult": {
                        "aggregationType": "Sum"
                      },
                      "callsByActions": {
                        "aggregationType": "Sum"
                      },
                      "callsByCompanyHours": {
                        "aggregationType": "Sum"
                      },
                      "callsByQueueSla": {
                        "aggregationType": "Sum"
                      }
                    },
                    "timers": {
                      "totalCallLength": {
                        "aggregationType": "Sum"
                      },
                      "timeSpentByCallSegments": {
                        "aggregationType": "Sum"
                      },
                      "callLengthByDirection": {
                        "aggregationType": "Sum"
                      },
                      "callLengthByOrigin": {
                        "aggregationType": "Sum"
                      },
                      "callLengthByResponse": {
                        "aggregationType": "Sum"
                      },
                      "callLengthByResponseType": {
                        "aggregationType": "Sum"
                      },
                      "callLengthByResult": {
                        "aggregationType": "Sum"
                      },
                      "callsLengthByCompanyHours": {
                        "aggregationType": "Sum"
                      },
                      "callsLengthByQueueSla": {
                        "aggregationType": "Sum"
                      }
                    }
                  }
                }'

Using Postman

If you prefer to see the API request and response in GUI, you can use Postman Tool or our API Explorer. Click the button below to import the settings for Postman and run it there.

Run in Postman

Watch a demo of using Postman to call the Analytics API

What's Next?

When you have successfully made your first API call, it is time to take your next step towards building a more robust RingCentral application. You can reference our Sample C# Application or build an application from scratch.

Take your next step »