Handling asynchronous responses from the Artificial Intelligence API

The Artificial Intelligence API operates in an asynchronous manner. Meaning the results of its operations are not returned in the HTTP response associated with the HTTP request performing the operation. Instead, developers specify a URL in their request, and when the operation completes, the response payload will be posted to the specified URL.

Th asynchronous nature of the Artificial Intelligence API requires developers to setup a simple web server in order to process results and run sample code found in this Developer Guide. Below, you will find simple web servers in a variety of languages to help you in this process.

Passing the webhook parameter in your requests

Many endpoints in the Artificial Intelligence API take as input a query parameter called webhook. When you pass a URL to the API via this query parameter, the server will then transmit the results of the corresponding operation to the provided URL when the operation completes. This will allow the server to process the operation in the background without tying up resources in the process.

Correlating requests and responses

When processing files asynchronously, it is important to correlate every request with the proper response, as there is no guarantee in which order a response will be received. To help with this, a jobId is returned in the response body of every request, like so:

{"jobId":"a919924e-ce4e-11ed-xxxx-0050568c48bc"}

You should parse this response, and store the jobId associated with the media file being processed so that you can reliably associate the response that will be delivered in a webhook later to the file for which it pertains.

Check on the status of your AI API job request

Upon submitting your AI API job request, a jobId is sent in the response as mentioned above. With this jobId, you can check on the progress of your AI API job request as follows:

GET /ai/status/v1/jobs/{jobId}

This will return a JSON response to show some details on your AI API job request:

{
    "jobId": "a919924e-ce4e-11ed-xxxx-0050568c48bc",
    "creationTime": "2023-04-04T21:20:20.246Z",
    "expirationTime": "2023-04-11T21:20:20.246Z",
    "status": "InProgress"
}

Once the AI API job request is completed, using this API command will return the results of your AI API request.

Working with asynchronous responses in development

Install and setup ngrok

If you are doing development on your local laptop, or on a machine that is not publicly accessible on the Internet, then we recommend you download and install ngrok if you have not already. Once installed, start your ngrok server and make note of its https URL. You will need to use this URL later when specifying the webhook in Artificial Intelligence API requests.

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

Create and start a simple web server

Let's create a simple web server on your local machine to receive webhook notifications when your Artificial Intelligence API file is processed and ready to be recevied.

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

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

$ node server.js

import os,sys
import logging
import requests
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

# Server config. Set this to your local server and port
HOSTNAME = "localhost"
PORT     = 8080

# Handle Incoming HTTP requests
class S(BaseHTTPRequestHandler):
    def _set_response(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/html')
        self.end_headers()

    def do_POST(self):
        content_length = int(self.headers['Content-Length']) 
        post_data = self.rfile.read(content_length) 
        print( json.dumps(json.loads(post_data), indent=2, sort_keys=True))
        self._set_response()

def run(server_class=HTTPServer, handler_class=S, hostName='localhost', port=8080):
    logging.basicConfig(level=logging.INFO)
    server_address = (HOSTNAME, port)
    httpd = server_class(server_address, handler_class)
    logging.info('Artificial Intelligence response server running at: https://%s:%s\n', hostName, port)
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        pass
    httpd.server_close()
    logging.info('Artificial Intelligence response server stopping...\n')

try:
    run( hostName = HOSTNAME, port=PORT )
except Exception as e:
    print(e)

$ python server.py

With your web server up and running, and a way to route requests to it via ngrok, you are now ready to run code samples.