How to find the callerStatus and calleeStatus for RingCentral calls?

How do I get call status for past calls?

I want to get the callerStatus and calleeStatus status which I see in the RingOut Status API response but I'm not sure what to use for the ringOutId in the URL path:

https://developer.ringcentral.com/api-reference#RingOut-getRingOutCallStatus

Request

GET /restapi/v1.0/account/400162076008/extension/400162076009/ring-out/Y3MxNzE4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM

Response

HTTP 200 OK

{
    "uri" : "https://platform.ringcentral.com/restapi/v1.0/account/400162076008/extension/400162076009/ring-out/2",
    "id" : "Y3MxNzE4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
    "status" : {
      "callStatus" : "Success",
      "callerStatus" : "Success",
      "calleeStatus" : "Success"
    }
}

When making a RingOut Status call without a ringOutId, I was hoping to get a list of calls, but I get the following error instead:

Resource for parameter [ringOutId] is not found

What do I use for ringOutId? How can I get the callerStatus and calleeStatus for calls?

Solution

RingOut Active Call Status

The RingOut Status API is only used when making phone calls via RingOut. The ringOutId is returned in the response for the Make RingOut API. It also only returns status while the call is in progress and a short time later, after which, it will return a 404.

API Ref: https://developer.ringcentral.com/api-reference#RingOut-makeRingOutCall

RingOut Historical Call Status

To get call status for historical calls, use the Call Log API. By default, the service will return status for the overall call in the result property. To get status on individual parties on the call, known as legs, use the Detailed Call Log API. The following URLs are available:

Company Call Log (all users)

GET /restapi/v1.0/account/~/call-log?view=Detailed

https://developer.ringcentral.com/api-reference#Call-Log-loadCompanyCallLog

User Extension Call Log

GET /restapi/v1.0/account/~/extension/~/call-log?view=Detailed

https://developer.ringcentral.com/api-reference#Call-Log-loadUserCallLog

With the detailed view, you will receive a response with the legs property, which is an array of call log records also known as a Call Detail Records (CDR). An example record is shown below. Each call in the legs array has a result property. result is used instead of status because the call log only lists completed calls. Each leg has a legType property that can be used to identify the caller and callee.

For example, legType can be set to:

RingOutClientToCaller
RingOutClientToSubscriber

RingOutClientToSubscriber can be used for the calleeStatus. This gives us:

callerStatus = leg.result where leg.legType == 'RingOutClientToCaller'
calleeStatus = leg.result where leg.legType == 'RingOutClientToSubscriber'

Note: It's possible for a CDR to only have one leg. This can happen if the result is Busy. In RingOut, if one party is busy, it can be an optimization to not call the other party. Many times, our customers will use RingOut to call their employee first, and if the employee picks up, then call the customer. If the employee isn't there, there's no reason to call the customer and have them listen to a busy tone.

Here's a response call log record example:

{
  "uri": "https://platform.ringcentral.com/restapi/v1.0/account/727097016/extension/727097016/call-log/L6HbCN6tB1nyDUA?view=Detailed",
  "id": "L6HbCN6tB1nyDUA",
  "sessionId": "575838550017",
  "startTime": "2018-11-22T08:42:05.500Z",
  "duration": 19,
  "type": "Voice",
  "direction": "Outbound",
  "action": "RingOut PC",
  "result": "Call connected",
  "to": {
    "phoneNumber": "+12125550111",
    "name": "Daenerys Targaryen",
  },
  "from": {
    "phoneNumber": "+16505550101",
    "name": "John Snow"
  },
  "extension": {
    "uri": "https://platform.ringcentral.com/restapi/v1.0/account/727097016/extension/727097016",
    "id": 727097016
  },
  "transport": "PSTN",
  "lastModifiedTime": "2018-11-22T08:42:30.007Z",
  "billing": {
    "costIncluded": 0.0,
    "costPurchased": 0.0
  },
  "legs": [
    {
      "startTime": "2018-11-22T08:42:05.257Z",
      "duration": 20,
      "type": "Voice",
      "direction": "Outbound",
      "action": "RingOut PC",
      "result": "Call connected",
      "to": {
        "phoneNumber": "+16505550101",
        "name": "John Snow"
      },
      "from": {
        "phoneNumber": "+12125550111",
        "name": "Daenerys Targaryen",
      },
      "extension": {
        "uri": "https://platform.ringcentral.com/restapi/v1.0/account/727097016/extension/727097016",
        "id": 727097016
      },
      "transport": "PSTN",
      "billing": {
        "costIncluded": 0.0,
        "costPurchased": 0.0
      },
      "legType": "RingOutClientToSubscriber"
    },
    {
      "startTime": "2018-11-22T08:42:05.500Z",
      "duration": 19,
      "type": "Voice",
      "direction": "Outbound",
      "action": "RingOut PC",
      "result": "Call connected",
      "to": {
        "phoneNumber": "+12125550111",
        "name": "Daenerys Targaryen",
      },
      "from": {
        "phoneNumber": "+16505550101",
        "name": "John Snow"
      },
      "extension": {
        "uri": "https://platform.ringcentral.com/restapi/v1.0/account/727097016/extension/727097016",
        "id": 727097016
      },
      "transport": "PSTN",
      "legType": "RingOutClientToCaller",
      "master": true
    }
  ]
},

Note: In the detailed call log example, the to and from for the RingOutClientToCaller leg coincide with the to and from for the overall call, while they are reversed for the RingOutClientToSubscriber leg to the callee. This is because the callee will be connect with the caller, whose number is in the to property from their perspective.