Call Log Access Control

Last updated: 2024-01-31Contributors
Edit this page

Like every other RingCentral API resource, the Call Log API resource has specific limitiations in place for accessing Call Log data via our API.

Developers can easily determine the permissions available for an access token by viewing the scope property while requesting an access_token from RingCentral OAuth endpoints (this works for either the password flow or auth code flow). The scope property will be a string which can be split on whitespace " ". The following example shows how to use the RingCentral JS SDK to inspect for the required API Permissions prior to executing these requests (on an ROPC Server-Only NO UI Platform Type application).:

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_APP_CLIENT_ID,
    'clientSecret': process.env.RC_APP_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_USER_JWT })

var permissions = []

platform.on(platform.events.loginSuccess, async function(response) {
  var responseJson = response.json();
  // Sanity check
  if (responseJson.hasOwnProperty('scope')) {
    permissions = responseJson.scope.split(" ");
    if (permissions.indexOf('ReadCallLog' >= 0)) {
      try {
        var resp = await platform.get('/restapi/v1.0/account/~/call-log')
        var jsonObj = await resp.json()
        console.log('Account level call log data');
        console.log(jsonObj);
      } catch (e) {
        console.log(e.message)
      }
    }
  }
})

API Permissions

There are two main API permissions developers will need to access Call Log data, ReadCallLog and ReadCallRecording.

You may need to configure your application in the RingCentral Developer Console to enable your app/integration to use the Call Log API resources. Always refer to the RingCentral API Reference for the most up-to-date information on accessing the Call Log API resource.

The following table provides a quick outline about what API permissions the API Keys your application/integration must have associated in order to access each major category of data which Call Log provides.

Category Method Requires ReadCallLog Requires ReadCallRecording Route
Active Calls GET YES NO /v1.0/account/{accountId}/extension/{extensionId]/active-calls
Account List of Call Logs GET YES NO /v1.0/account/{accountId}/call-log
Extension List of Call Logs GET YES NO /v1.0/account/{accountId}/extension/{extensionId}/call-log
Call Recording Meta Data GET YES YES /v1.0/account/{accountId}/recording/{recordingId}
Call Recording Content Data GET NO YES /v1.0/account/{accountId}/recording/{recordingId}/content

Common Permission Errors

If you do not have ReadCallLog API Permission set on an application which is submitting request which require this permission, you will receive the following HTTP 403 error response:

{
    "errorCode": "InsufficientPermissions",
    "message": "In order to call this API endpoint, application needs to have [ReadCallLog] permission",
    "errors": [
        {
            "errorCode": "CMN-401",
            "message": "In order to call this API endpoint, application needs to have [ReadCallLog] permission",
            "permissionName": "ReadCallLog"
        }
    ],
    "permissionName": "ReadCallLog"
}

If you do not have ReadCallRecording API Permission set on an application which is submitting a request which require this permission, you will receive the following HTTP 403 error response

{
    "errorCode": "InsufficientPermissions",
    "message": "In order to call this API endpoint, application needs to have [ReadCallRecording] permission",
    "errors": [
        {
            "errorCode": "CMN-401",
            "message": "In order to call this API endpoint, application needs to have [ReadCallRecording] permission",
            "permissionName": "ReadCallRecording"
        }
    ],
    "permissionName": "ReadCallRecording"
}