Artificial Intelligence API Quick Start Guide

Last updated: 2023-02-09

Contributors

RingCentral Artificial Intelligence API is in beta

The RingCentral's Artificial Intelligence API is currently in beta. Developers should be aware of the following:

Their feature sets are not reflective of the full scope currently planned.
Backwards compatibility is not guaranteed from one release to the next during the beta period. Changes can be introduced at any time that may impact your applications with little notice.

Welcome to the RingCentral Platform. RingCentral is the leading unified communications platform. From one system developers can integrate with, or build products around all the ways people communicate today: SMS, voice, fax, chat and meetings. In this Quick Start, we are going to help you create your first "Speech to Text" application on the RingCentral platform in just a few minutes. Let's get started.

Create an App

The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create AI App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create AI App Show detailed instructions

Login or create an account if you have not done so already.
Go to Console/Apps and click 'Create App' button.
Select "API App for RingCentral Office" under "What type of app are you creating?"
Select "Other Non-UI" under "Where will you be calling the API from?"
Select "Only members of my organization/company" under "Who will be authorized to access your app?"
Under "Auth" select "JWT auth flow". Make sure to create JWT Credentials afterwards.

Request help from support

Access to the RingCentral Artificial API currently requires help from support in order to grant the "AI" application scope to your application, and graduate it to production.

Request app graduation

Download and edit a `.env` file

Follow the instructions found in our guide to running Developer Guide code samples. Or:

Download our env-template and save it as a file named .env.
Edit your newly downloaded .env file, setting its variables with the proper values for the app you created above.

Setup a server to process the response asynchronously

The Artificial Intelligence APIs provide responses in an asynchronous manner by posting responses to a URL specified by the developer when the request is made. Our first step therefore is setting up a simple web server to display the response we will receive from RingCentral. The server below is written in Javascript and uses ngrok to proxy requests from RingCentral to your local development machine. To keep your first application simple, this server does nothing more than acknowledge receipt and echo the payload of anything it receives to the console.

Start ngrok

Download and install ngrok if you have not already. Then start your ngrok server and make note of its https URL. You will enter that URL in the server you create in the next step.

$ ngrok http 5000
  Forwarding https://xxx-yyy-zzz.ngrok.io -> https://localhost:5000

Create and start your server

Create a file called server.js using the contents below. Edit server.js to properly reference the NGROK_URL generated in the previous step.

const http = require('http');
const PORT = 5000;

// Create a server to receive callback from RingCentral
const server = http.createServer( function(req, res) {
    if (req.method == 'POST' && req.url == "/webhook") {
        console.log("Response received from RingCentral...");
        if (req.headers.hasOwnProperty("validation-token")) {
            res.setHeader('Content-type', 'application/json');
            res.setHeader('Validation-Token', req.headers['validation-token']);
        } 
        let body = []
        req.on('data', function(chunk) {
            body.push(chunk);
        }).on('end', function() {
            body = Buffer.concat(body).toString();
            console.log(JSON.stringify(JSON.parse(body),null,4));
            res.statusCode = 200;
            res.end();
        });
    } else {
        console.log("Unknown HTTP content received")
    }
});

// Start the server
try {
    server.listen(PORT);
} catch (e) {
    console.log("There was a problem starting the server: " + e)
}
console.log("Artificial Intelligence response server running at: https://localhost:" + PORT)

Finally, start your server.

$ node server.js

Convert speech to text

Javascript

Setup your project

$ npm install @ringcentral/sdk
$ npm install dotenv

Finally, add your .env file you created earlier to your project directory.

Create and edit `index.js`

Copy and paste the code from below in index.js. Be sure the values in your .env file have been set properly, including the RC_MEDIA_URL variable.

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

// Read instructions on running code samples to include all required variables
// https://developers.ringcentral.com/guide/basics/code-samples
NGROK       = "<INSERT NGROK URL>"
WEBHOOK_URL = NGROK + "/webhook";
CONTENT_URI = process.env.RC_MEDIA_URL;

// Initialize the RingCentral SDK and Platform
const rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});

const platform = rcsdk.platform();
platform.login({'jwt':  process.env.RC_JWT})

platform.on(platform.events.loginSuccess, () => {
    speechToText();
})

async function speechToText() {
    try {
        console.log("Calling RingCentral Speech To Text API");
        let resp = await platform.post("/ai/audio/v1/async/speech-to-text?webhook=" + WEBHOOK_URL, {
            "contentUri":               CONTENT_URI,
            "encoding":                 "Wav",
            "languageCode":             "en-US",
            "source":                   "RingCentral",
            "audioType":                "Meeting",
            "enablePunctuation":        true,
            "enableSpeakerDiarization": false
        });
        console.log("Speech To Text Job " + resp.statusText + " with HTTP status code " + resp.status);
        if (resp.status == 202) {
            console.log("Ready to receive response at: " + WEBHOOK_URL);
        } else {
            console.log("An error occurred posting the request.");
        }
    } 
    catch (e) {
        console.log("An error occurred : " + e.message);
    }
}

```

#### Run your code

You are almost done. Now run your script above to send the request to RingCentral and recive the response.

```bash
$ node index.js
```

Python

Setup your project

$ pip install ringcentral
$ pip install python-dotenv

Finally, add your .env file you created earlier to your project directory.

Create and edit `index.py`

Copy and paste the code from below in index.py. Be sure the values in your .env file have been set properly, including the RC_MEDIA_URL variable.

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

# Read instructions on running code samples to include all required variables
# https://developers.ringcentral.com/guide/basics/code-samples
NGROK       = "<INSERT NGROK URL>"
WEBHOOK_URL = NGROK + "/webhook"
CONTENT_URI = os.environ.get('RC_MEDIA_URL')

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))

resp = platform.post("/ai/audio/v1/async/speech-to-text?webhook=" + urllib.parse.quote(WEBHOOK_URL), {
  "contentUri":               CONTENT_URI,
  "encoding":                 "Wav",
  "languageCode":             "en-US",
  "source":                   "RingCentral",
  "audioType":                "Meeting",
  "enablePunctuation":        True,
  "enableSpeakerDiarization": False
})

print(f'Speech To Text job {resp.response().reason} with HTTP status code {resp.response().status_code}');

if resp.response().status_code == 202:
  print(f'Ready to receive response at: {WEBHOOK_URL}');
else:
  print(f'An error occurred posting the request.');

Run your code

You are almost done. Now run your script above to send the request to RingCentral and recive the response.

$ python index.py

PHP

Install RingCentral PHP SDK

$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar require ringcentral/ringcentral-php vlucas/phpdotenv

Create and edit index.php

Create a file called index.php. Be sure the values in your .env file have been set properly, including the RC_MEDIA_URL variable.

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

require('vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

$RECIPIENT    = $_ENV['SMS_RECIPIENT'];

$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
                                  $_ENV['RC_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );

$platform = $rcsdk->platform();
$platform->login( $_ENV['RC_USERNAME'],
                  $_ENV['RC_EXTENSION'],
                  $_ENV['RC_PASSWORD'] );

read_extension_phone_number();

function read_extension_phone_number(){
  global $platform;
  $resp = $platform->get("/restapi/v1.0/account/~/extension/~/phone-number");
  $jsonObj = $resp->json();
  foreach ($resp->json()->records as $record){
    foreach ($record->features as $feature){
      if ($feature == "SmsSender"){
        return send_sms($record->phoneNumber);
      }
    }
    exit("No phone number found with 'SmsSender' feature enabled.");
  }
}

function send_sms($fromNumber){
  global $platform,$RECIPIENT;
  try {
    $resp = $platform->post('/account/~/extension/~/sms',
        array(
           'from' => array ('phoneNumber' => $fromNumber),
           'to' => array(
                    array('phoneNumber' => $RECIPIENT)
                  ),
           'text' => 'Hello World!'
         ));
    print("SMS sent. Message status: " . $resp->json()->messageStatus . PHP_EOL);
  } catch (\RingCentral\SDK\Http\ApiException $e) {
    exit("Message: " . $e->message . PHP_EOL);
  }
}
?>

Run your code

You are almost done. Now run your script.

$ php index.php

Await receipt of a response from RingCentral

In time, when RingCentral has fully processed the request, a response will be posted to the server you created previously. The response should look similar to the following.

{
    "status":"Success",
    "response":{
        "transcript":"Thunderstorms could produce large, hail isolated tornadoes and heavy rain.",
        "confidence":0.87,
        "words":[
            {
                "word":"thunderstorms",
                "start":1.74,
                "end":2.46,
                "confidence":0.819
            },
            {
                "word":"could",
                "start":2.46,
                "end":2.7,
                "confidence":0.967
            },
            {
                "word":"produce",
                "start":2.7,
                "end":3.1,
                "confidence":0.982
            },
            {
                "word":"large",
                "start":3.1,
                "end":3.42,
                "confidence":0.826
            },
            {
                "word":"hail",
                "start":3.58,
                "end":3.9,
                "confidence":0.888
            },
            {
                "word":"isolated",
                "start":4.14,
                "end":4.46,
                "confidence":0.827
            },
            {
                "word":"tornadoes",
                "start":4.54,
                "end":5.18,
                "confidence":0.844
            },
            {
                "word":"and",
                "start":5.18,
                "end":5.34,
                "confidence":0.99
            },
            {
                "word":"heavy",
                "start":5.42,
                "end":5.74,
                "confidence":0.87
            },
            {
                "word":"rain",
                "start":5.82,
                "end":5.9,
                "confidence":0.902
            }
        ],
        "audio_duration":7.096599
    }
}

Artificial Intelligence API Quick Start Guide

Create an App

Request help from support

Download and edit a .env file

Setup a server to process the response asynchronously

Start ngrok

Create and start your server

Convert speech to text

Setup your project

Create and edit index.js

Setup your project

Create and edit index.py

Run your code

Install RingCentral PHP SDK

Create and edit index.php

Run your code

Await receipt of a response from RingCentral

Download and edit a `.env` file

Create and edit `index.js`

Create and edit `index.py`