Handling asynchronous responses from the Artificial Intelligence API

Last updated: 2023-02-09

Contributors

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 specific 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 setp a simple web server in order to process results and run sample code 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

It is recommended that when composing a webhook URL to receive a response, you generate and include a request ID and include in the URL you generate. Doing so will allow you to correlate an incoming webhook with the request that originated it. For example, you may create a server that accepts webhooks from RingCentral at a URL like the following:

https://my.server.com/conversations/webhooks

You could then generate a request ID and append it to the URL as follows:

https://my.server.com/conversations/webhooks/1234567890

Then you will pass that URL to RingCentral via the webhook parameter as follows:

https://platform.ringcentral.com/ai/audio/v1/async/speech-to-text?
     webhook=https%3A%2F%2Fmy.server.com%2Fconversations%2Fwebhooks%2F1234567890

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 5000
  Forwarding https://xxx-yyy-zzz.ngrok.io -> https://localhost:5000

Create and start a simple web 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.

Javascript

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

Python

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

PORT = 5000

# 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']) # <--- Gets the size of data
        post_data = self.rfile.read(content_length) # <--- Gets the data itself
        if self.path == '/webhook':
            print(post_data)
        self._set_response()

def run(server_class=HTTPServer, handler_class=S, port=8080):
    logging.basicConfig(level=logging.INFO)
    server_address = ('', port)
    httpd = server_class(server_address, handler_class)
    logging.info('Starting httpd...\n')
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        pass
    httpd.server_close()
    logging.info('Stopping httpd...\n')

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