How to analyze media files using the AI API

Last updated: 2024-02-08

Contributors

Most of RingCentral AI APIs such as the /speech-to-text and the /analyze-interaction endpoints take the input media content contentUri as a URI link to a media file resides at a remote server. These APIs all work in an asynchronous manner and follow this basic flow:

Developer calls an API endpoint passing a URI in the contentUri parameter
RingCentral responds with a 20x status code to acknowledge receipt of request
RingCentral downloads and processes media file
RingCentral posts a response back to the specified webhook URL in the API request

The URI link referenced by the contentUri parameter must be publicly accessible. If a media file access is protected in some way, then the file must be retrievable and accessible via a single URI (see the case of RingCentral call recording example below). Otherwise, RingCentral will fail the API request and post an error to the asynchronous response. The AI API does not currently allow developers to specify custom HTTP headers to be transmitted when fetching the media content from the contentUri URI.

How to analyze RingCentral call recordings and meeting recordings

RingCentral hosts all downloadable media content on a protected server, and requires developers to provide a valid access token in a request in order to access the content. RingCentral makes it possible to access protected media content, like RingCentral call recordings and RingCentral Video meeting recordings by appending the access token via the access_token query 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/.../ASaxDDkSZ5s42MA?view=Simple",
    "id": "ASaxDDkSZ5s42MA",
    "sessionId": "13916417004",
    "startTime": "2023-06-06T23:07:20.000Z",
    "duration": 55,
    "type": "Voice",
    "direction": "Inbound",
    "action": "Phone Call",
    "result": "Accepted",
    "to": {
        "phoneNumber": "+15625555772",
        "name": "SDK Engineer Candidate"
    },
    "from": {
        "phoneNumber": "+14155555900",
        "name": "SAN FRANCSCO CA",
        "location": "San Francisco (South), CA"
    },
    "recording": {
        "uri": "https://platform.ringcentral.com/restapi/.../recording/1662272004",
        "id": "1662272004",
        "type": "OnDemand",
        "contentUri": "https://media.ringcentral.com/restapi/.../recording/1662272004/content"
    }
}

Sample code to construct a content URI for accessing RingCentral call recording

The following example code shows how to obtain the access token using a RingCentral platform SDK and attach the access token to the media file's content URL.

Running the code

Edit the variables in ALL CAPS with your app and user credentials before running the code.

JavaScript

const fs = require ('fs')
const RC = require('@ringcentral/sdk').SDK

// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
    server: 'https://platform.ringcentral.com',
    clientId: 'RC_APP_CLIENT_ID',
    clientSecret: 'RC_APP_CLIENT_SECRET'
});
var platform = rcsdk.platform();

/* Authenticate a user using a personal JWT token */
platform.login({ jwt: 'RC_USER_JWT' })

platform.on(platform.events.loginSuccess, async () => {
  var tokens = await platform.auth().data()
  var contentUri = `https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token=${accessToken}`
  // ...
})

platform.on(platform.events.loginError, function(e){
  console.log("Unable to authenticate to platform. Check credentials.", e.message)
  process.exit(1)
});

Python

from ringcentral import SDK

# Authenticate a user using a personal JWT token
def login():
  try:
      platform.login( jwt= "PRODUCTION-JWT" )
      tokens = platform.auth().data()
      contentUri = f'https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token={tokens["access_token"]}';
      # ...
  except Exception as e:
      print ("Unable to authenticate to platform. Check credentials. " + str(e))

# Instantiate the SDK and get the platform instance
rcsdk = SDK("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com")
platform = rcsdk.platform()

login()

PHP

<?php
require('vendor/autoload.php');

// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( 'RC_APP_CLIENT_ID', 'RC_APP_CLIENT_SECRET', 'https://platform.ringcentral.com' );
$platform = $rcsdk->platform();

/* Authenticate a user using a personal JWT token */
$platform->login(["jwt" => 'RC_USER_JWT']);
$tokens = $platform->auth()->data()
$contentUri = "https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token=".$tokens'access_token'];
// ...
?>

Ruby

require 'ringcentral'

# Authenticate a user using a personal JWT token
def login()
  begin
    $platform.authorize( jwt: "RC_USER_JWT" )
    tokens = $platform.token
    contentUri = "https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token=" + tokens['access_token']
    # ...
  rescue StandardError => e
    puts ("Unable to authenticate to platform. Check credentials. " + e.to_s)
  end
end

# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" )

login()

using System;
using System.IO;
using System.Threading.Tasks;
using System.Collections.Generic;
using RingCentral;
using Newtonsoft.Json;

namespace ConvertSpeechToText {
  class Program {
    static RestClient restClient;
    static string NGROK_ADDRESS = "NGROK-TUNNEL-ADDRESS";
    static string WEBHOOK_URL = NGROK_ADDRESS + "/webhook";

    static async Task Main(string[] args){
      try
      {
        // Instantiate the SDK
        restClient = new RestClient("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");

        // Authenticate a user using a personal JWT token
        await restClient.Authorize("RC_USER_JWT");

        String accessToken = restClient.token.access_token;
        var contentUri = "https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token=" + accessToken;
        // ...
      }
      catch (Exception ex)
      {
        Console.WriteLine("Unable to authenticate to platform. Check credentials. " + ex.Message);
      }
    }
  }
}

Java

package ConvertSpeechToText;

import java.io.IOException;
import com.google.common.reflect.TypeToken;
import com.google.gson.Gson;

import com.ringcentral.*;
import com.ringcentral.definitions.*;

public class ConvertSpeechToText {
    static String NGROK_ADDRESS = "NGROK-TUNNEL-ADDRESS";
    static String WEBHOOK_URL = NGROK_ADDRESS + "/webhook";

    static RestClient restClient;

    public static void main(String[] args) {
      var obj = new ConvertSpeechToText();
      try {
        // Instantiate the SDK
        restClient = new RestClient("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");

        // Authenticate a user using a personal JWT token
        restClient.authorize("RC_USER_JWT");

        String accessToken = restClient.token.access_token;
        String contentUri = "https://media.ringcentral.com/restapi/.../recording/1662272004/content?access_token=" + accessToken;
        // ...
      } catch (RestException e) {
        System.out.println(e.getMessage());
      } catch (IOException e) {
        e.printStackTrace();
      }
    }
}

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 Log, Read Call Recording

For Video Meeting Recordings: AI, Video