How to analyze media files using the AI API

Last updated: 2023-04-12

Contributors

A number of Artificial Intelligence API endpoints operate by processing a media files that reside at a publicly accessible URL. These APIs all work in an asynchronous manner and follow this basic flow:

Developer calls API passing a URL in the contentUri parameter
RingCentral responds with a 20x status code to acknowledge receipt of request
RingCentral downloads and processes media file
RingCentral posts response back to developer at the webhookUrl they specify

The URLs referenced by the contentUri parameter must be public accessible to RingCentral servers. If the media files referenced are protected in some way, then the file must be retrievable and accessible via a single URL. The AI API does not currently allow developers to specify custom HTTP headers to be transmitted when fetching the contentUri URL.

How to analyze RingCentral call recordings and RingCentral meeting recordings

RingCentral hosts all downloadable media content on a protected server, and requires developers to transmit a valid access key (or auth token) with their request in order to access the corresponding content. RingCentral makes it possible to access protected media content, like RingCentral call recordings and RingCentral Video meeting recordings by appending the access key via the access_token querystring parameter. For example, let's look at how one would construct a URL that would allow the AI API to access a RingCentral call recording.

Sample call log entry

Here is an excerpt from a call to the Call Log API and shows an entry that contains a reference to a recording of a phone call.

{
    "uri": "https://platform.ringcentral.com/restapi/..snip../ASaxDDkSZ5s42MA?view=Simple",
    "id": "ASaxDDkSZ5s42MA",
    "sessionId": "13916417004",
    "startTime": "2016-06-06T23:07:20.000Z",
    "duration": 55,
    "type": "Voice",
    "direction": "Inbound",
    "action": "Phone Call",
    "result": "Accepted",
    "to": {
        "phoneNumber": "+15625555778",
        "name": "SDK Engineer Candidate"
    },
    "from": {
        "phoneNumber": "+14155555908",
        "name": "SAN FRANCSCO CA",
        "location": "San Francisco (South), CA"
    },
    "recording": {
        "uri": "https://platform.ringcentral.com/restapi/..snip../recording/1662272004",
        "id": "1662272004",
        "type": "OnDemand",
        "contentUri": "https://media.ringcentral.com:443/restapi/..snip../recording/1662272004/content"
    }
}

Obtaining an access key or token

To access a protected media file, you will first need to obtain an access key. Luckily the access key you will use is the same used to call the RingCentral API. You can obtain the access key easily via each of our SDKs.

Javascript

/* You get the environment parameters from your 
   application dashbord in your developer account 
   https://developers.ringcentral.com */

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();
var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })
platform.on(platform.events.loginSuccess, function(e){
    print_access_key()
});
async function print_access_key() {
    var authData = await rcsdk.platform().auth().data();
    console.log('Access key: ' + authData['access_token'])
}

Python

#!/usr/bin/env python
from ringcentral import SDK
import os,sys
from dotenv import load_dotenv
load_dotenv()

RECIPIENT = os.environ.get('RINGOUT_RECIPIENT')

rcsdk = SDK( os.environ.get('RC_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

auth = platform.auth()
print('Access key: {auth.access_token()}')

PHP

<?php
require('vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();
$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
                                  $_ENV['RC_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_JWT'] ] );
print_r("Access key: " . $platform->auth()->data()['access_token']);
?>

Ruby

require 'ringcentral'
require 'dotenv/load'
$rc = RingCentral.new(ENV['RC_CLIENT_ID'],
                      ENV['RC_CLIENRT_SECRET'],
                      ENV['RC_SERVER_URL'])
$rc.authorize(jwt: ENV['RC_JWT'])
puts "Access key: " + $rc.token['access_token']

Appending the access key to the media file URL

Now, pass the access key to the media file's content URL in the following manner:

https://media.ringcentral.com/restapi/..snip../recording/1662272004/content?access_token=<ACCESS KEY>

Important

To retrieve the recording and use the AI API to process the recording, you need to have the following app permissions:

For Call Recordings: AI, Read Call Recording

For Video Meeting Recordings: AI, Video Internal