How can I retrieve a RingCentral call recording from a monitored incoming call?

Question

I'm monitoring incoming calls on RingCentral by listening for the Call Session Notifications (CSN) telephony/sessions event filter:

/restapi/v1.0/account/~/extension/~/telephony/sessions

From this, I will receive events like the following. The recordings property will appear to indicate a recording is available. How can I retrieve this recording?

{
  "uuid":"12345678901234567890",
  "event":"/restapi/v1.0/account/11111111/extension/22222222/telephony/sessions",
  "timestamp":"2019-03-08T22:30:40.059Z",
  "subscriptionId":"11112222-3333-4444-5555-666677778888",
  "ownerId":"33333333",
  "body":{
    "sequence":7,
    "sessionId":"1234567890",
    "telephonySessionId":"1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
    "serverId":"10.11.12.13.TAM",
    "eventTime":"2019-03-08T22:30:39.938Z",
    "parties":[
      {
        "accountId":"11111111",
        "extensionId":"22222222",
        "id":"cs12345678901234567890-2",
        "direction":"Inbound",
        "to":{
          "phoneNumber":"+16505550100",
          "name":"Jane Doe",
          "extensionId":"22222222"
        },
        "from":{
          "phoneNumber":"+14155550100",
          "name":"John Smith"
        },
        "recordings":[
          {
            "id":"44444444",
            "active":false
          }
        ],
        "status":{
          "code":"Answered",
          "rcc":false
        },
        "missedCall":false,
        "standAlone":false,
        "muted":false
      }
    ],
    "origin":{
      "type":"Call"
    }
  }
}

Answer 1

There are two ways to retrieve the recording using information in the Call Session Notification (CSN) event, specifically the recordings[0].id property and the sessionID property.

1. retrieving a full media URL by calling the call-log endpoint with the sessionId property
2. manually creating recording media URL using the recordings[0].id property.

Note 1: While the call is ongoing, the recording will not be available for retrieval, even when the recording id is present in the Call Session Notification event. The recording will be available to be retrieved shortly after the call concludes.

Note 2: Call recordings can be in MP3 or WAV format determined by the company. To distinguish check the response Content-Type header for the MIME type when retrieving the recording media file.

1) Retrieving Full Medial URL via Call Log API

Making an intermediate API call to the call-log API has the dual benefits of being the official approach for receiving a media URL an providing more metadata for the call. In this approach, the recording.id in the call-log record will match the recordings[0].id property in the Call Session Notification event.

Both the company account and user extension call-log APIs can be called with the sessionId parameter from the event as shown:

GET /restapi/v1.0/account/~/call-log?sessionId={sessionId}
GET /restapi/v1.0/account/~/extension/~/call-log?sessionId={sessionId}

In this example, the sessionId is 1234567890 so you would have a Company Call Log API URL as follows

GET /restapi/v1.0/account/~/call-log?sessionId=1234567890

The response object will have a recording property that provides hypermedia links to get the media file. The file can be WAV or MP3 format which is communicated in the response Content-Type header.

{
  "uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/call-log?view=Simple&sessionId=1234567890&page=1&perPage=100",
  "records": [
    {
      "uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/call-log/1234567890ABCDEFGabcdefgh?view=Simple",
      "id": "1234567890ABCDEFGabcdefgh",
      "sessionId": "1234567890",
      "startTime": "2019-03-08T22:30:29.505Z",
      "duration": 35,
      "type": "Voice",
      "direction": "Inbound",
      "action": "Phone Call",
      "result": "Accepted",
      "to": {
        "phoneNumber": "+16505550100",
        "name": "Jane Doe"
      },
      "from": {
        "phoneNumber": "+14155550100",
        "name": "John Smith",
        "location": "San Francisco, CA"
      },
      "recording": {
        "uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/recording/44444444",
        "id": "44444444",
        "type": "OnDemand",
        "contentUri": "https://media.ringcentral.com/restapi/v1.0/account/111111111/recording/44444444/content"
      },
      "extension": {
        "uri": "https://platform.ringcentral.com/restapi/v1.0/account/111111111/extension/22222222",
        "id": 22222222
      },
      "reason": "Accepted",
      "reasonDescription": "The call connected to and was accepted by this number."
    }
  ],
  "paging": {
    "page": 1,
    "perPage": 100,
    "pageStart": 0,
    "pageEnd": 0
  },
  "navigation": {
    "firstPage": {
      "uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/call-log?view=Simple&sessionId=1234567890&page=1&perPage=100"
    },
    "lastPage": {
      "uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/call-log?view=Simple&sessionId=1234567890&page=1&perPage=100"
    }
  }
}

2) Manually Creating Media URL

You can call the Recording API endpoint and retrieve the media directly by manually constructing the recording URL as follows:

https://media.ringcentral.com/restapi/v1.0/account/{accountId}/recording/{recordingId}/content

In this example, the accountId is 11111111 and the recordingId is 44444444 for the following:

https://media.ringcentral.com/restapi/v1.0/account/11111111/recording/44444444/content

The accountId in the URL path can be set to the currently authorized user's account using ~ . Alternately, it can be set explicitly by extracting the accountId from the event property or using the accountId property in the relevant party object. Using ~ is the recommended way to set accountId .

Note: This this approach can be quick, it may be error prone as RingCentral has changed the media hostname once in the past. While there are no anticipated, future changes, calling the call-log API and retrieving the full media URL from the response is the safer and recommended approach. See below for this approach. This is only included as some people will try this and potentially run into issues later.

3) Hybrid Approach

The first approach of calling the call-log end point is the recommended approach, however, it involves an extra API call and most of the time the second approach should work fine.

A hybrid approach is to construct the URL as in approach 2 and then fall back to approach 1 if approach 2 returns a 404 or other error.