Oracle Digital Assistant – TechExchange

1

Oracle Digital Assistant

TechExchange

Article.

Exposing Oracle Digital Assistant on Twilio Voice

Asaf Lev, April 2020

Twilio’s voice API extends applications with flexible call center features, soft phones, call tracking,

interactive voice response (IVR) menus and more. This article explains how you can use Twilio voice

APIs to expose Oracle Digital Assistant to telephony.

Oracle Digital Assistant - TechExchange 2

TWILIO VOICE WEBHOOK ...................................................................................................................................... 3

PRE-REQUISITES........................................................................................................................................................ 3 IMPLEMENTATION OVERVIEW ...................................................................................................................................... 3

OPTIONAL STEP: ORACLE CLOUD INFRASTRUCTURE API GATEWAY SET UP ............................................ 8

TWILIO CONFIGURATION ..................................................................................................................................... 15

FINAL STEPS .......................................................................................................................................................... 15

ORACLE DIGITAL ASSISTANT TO TWILLIO (SERVERNAME:PORT/BOT/MESSAGES) ......................................................... 16

Oracle Digital Assistant - TechExchange 3

Twilio Voice Webhook To integrate Oracle Digital Assistant with Twilio Voice, you need to build a webhook channel to dispatch between the

Twilio APIs and your digital assistant or skill. The webhook used in this article can be downloaded as a sample from

here.

Pre-requisites To integrate Oracle Digital Assistant with Twilio Voice API and to be able to test and run it, you need the following

• An Oracle Digital Assistant skill to "talk to"

• A webhook channel. For step-by-step instructions of creating a webhook channel, please see:

https://docs.oracle.com/en/cloud/paas/digital-assistant/use-chatbot/webhooks.html#GUID-96CCA06D-

0432-4F20-8CDD-E60161F46680

• A Twilio account / Trial account with a voice supported Twilio Number. For more information about

provisioning Twilio Trial account & activating a number, please see

https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account

• A compute instance or similar server for hosting the Webhook code: You can use the Oracle "always free

tier" from https://www.oracle.com/uk/cloud/free/ . The Oracle free tier includes

o Database - Your choice of Autonomous Transaction Processing or Autonomous Data Warehouse.

2 databases total, each with 1 OCPU and 20 GB storage

o Compute - 2 virtual machines with 1/8 OCPU and 1 GB memory each.

o Storage - 2 Block Volumes, 100 GB total. 10 GB Object Storage. 10 GB Archive Storage.

o Additional Services - Load Balancer: 1 instance, 10 Mbps bandwidth. Monitoring: 500 million

ingestion datapoints, 1 billion retrieval datapoints. Notifications: 1 million sent through https per

month, 1,000 sent through email per month. Outbound Data Transfer: 10 TB per month.

• NodeJS installed on the compute instance

• SSL + Domain or use of the Oracle API Gateway (APIGW) to expose the endpoints. APIGW provides an

OOTB domain + SSL, as demonstrated in the article

Implementation overview

After downloading the Twilio webhook sample for this article, extract the zip file and then from within the root folder

of the extracted content, open a command line and type.

npm install

Make sure you have access to the Internet when running the before mentioned command as it needs to download

dependent Node modules like express and logger4js. The dependent files are required by the webhook as shown in

the code sample below

Oracle Digital Assistant - TechExchange 4

const express = require('express');

const OracleBot = require('@oracle/bots-node-sdk');

const { MessageModel} = require('@oracle/bots-node-sdk/lib');

const Config = require('./config/Config');

const log4js = require('log4js');

const bodyParser = require('body-parser');

let logger = log4js.getLogger('Server');

logger.level = 'debug';

const app = express();

app.use(bodyParser.urlencoded({ extended: false }));

OracleBot.init(app, { logger: logger,});

// implement webhook

const {

WebhookClient,

WebhookEvent

} = OracleBot.Middleware;

To configure the webhook to access Oracle Digital Assistant, you need to provide information from the webhook

channel you created in Oracle Digital Assistant. In particular, you need the webhook URL and the secret key.

Below images show the sequence of a webhook channel creation. The last image shows the URL and the secret

you need to configure on the webhook. Note that the URL and the secret will look different for your Oracle Digital

Assistant instance than what is shown in the images.

Oracle Digital Assistant - TechExchange 5

Oracle Digital Assistant - TechExchange 6

const channel = {

url: Config.ODA_WEBHOOK_URL,

secret: Config.ODA_WEBHOOK_SECRET

};

const webhook = new WebhookClient({

channel: channel

});

// log receive errors

webhook.on(WebhookEvent.ERROR, console.error);

The Config.ODA_WEBHOOK_URL and Config.ODA_WEBHOOK_ SECRET are stored in the Config.js file

located in the <extracted_dir>/config/ sample folder. You need to edit this file with the Webhook URL and secret of

your webhook channel.

from ODA Webhook Channel>';

module.exports.ODA_WEBHOOK_SECRET = process.env.BOT_WEBHOOK_SECRET || '<Copy secret from ODA Webhook

Channel>';

// General Details

exports.PROXY = process.env.PROXY || process.env.http_proxy;

exports.PORT = process.env.PORT || 8773;

Also if you like to change the server port from 8773 to a different port, this is the right location to amend it.

Now all you will need to do is:

• Run the webhook as a service

• Point your domain with SSL or use API Gateway for that matter to expose the endpoints

• Update ODA & Twilio webhook URLs to the webhook exposed domain with SSL (HTTPS)

To run the webhook as a service (in the backgound), you can use one of the two following commands

• Option 1

o nohup node <webhook>.js &

o disown

Oracle Digital Assistant - TechExchange 7

• Option 2 (npm install pm2)

o ./node_modules/pm2/bin/pm2 start <webhook>.js

Oracle Digital Assistant - TechExchange 8

Optional Step: Oracle Cloud Infrastructure API Gateway Set up This step is optional, if you already have a domain with SSL enabled you can skip this step and just update the

webhook URLs in ODA and Twilio to your SSL enabled domain pointing to your code.

The API Gateway service enables you to publish APIs with private endpoints that are accessible from within your network, and which you can expose with public IP addresses if you want them to accept internet traffic. The endpoints support API validation, request and response transformation, CORS, authentication and authorization, and request limiting. For more information on API Gateway, check out the following link https://www.oracle.com/cloud/cloud-native/api-gateway/

If you need a domain + SSL you can use Oracle API Gateway that will point to your compute IP:PORT, API

Gateway will provide domain+SSL OOTB to the exposed webhook and here is the detailed step-by-step to

configure it.

To setup the Oracle API Gateway:

• Open the OCI tenancy administration console

• Navigate to the Developer Services -> API Gateway menu item

• Create a new Gateway

Oracle Digital Assistant - TechExchange 9

Oracle Digital Assistant - TechExchange 10

• Take a copy of the hostname that points to your http server:port. This will become your your SSL hostname

• Next, create the required deployments

Oracle Digital Assistant - TechExchange 11

Oracle Digital Assistant - TechExchange 12

Oracle Digital Assistant - TechExchange 13

Oracle Digital Assistant - TechExchange 14

Oracle Digital Assistant - TechExchange 15

Twilio Configuration The webhook URL needs to be configured in the Twilio number management page for Twilio to be able to call back

into the webhook.

On your Twilio account, navigate to Phone Numbers > Manage Numbers and click onto the active number.

(https://www.twilio.com/console/phone-numbers/incoming)

Under Voice&Fax, set the "A CALL COMES IN" webhook to <your webhookURL>/user/message

Final Steps The final steps for you to do is to go back to the Oracle Digital Assistant channel and Twilio Active number to set

the Webhook URL as follows:

In Oracle Digital Assistant webhook channel, set the Webhook URL to

https://<APIGW_HOSTNAME>/twilio/bot/message / https://<YOUR_DOMAIN>/twilio/bot/message

On Twilio, set it to

https://<APIGW_HOSTNAME>/twilio/user/message / https://<YOUR_DOMAIN>/twilio/user/message

Oracle Digital Assistant - TechExchange 16

Webhook Implementation – Under the hood

Oracle Digital Assistant to Twillio (servername:port/bot/messages)

Oracle Digital Assistant outgoing messages need to be transformed into a format understood by Twilio, which is

TwiML (Twilio Voice protocol)

https://www.twilio.com/docs/voice/twiml

The code below removes special characters from the Oracle Digital Assistant message and sends it back to the

Twilio user session that initiated the bot conversation. The user session is stored in the resArray variable.

// receive bot messages

app.post('/bot/message', webhook.receiver()); // receive bot messages

webhook.on(WebhookEvent.MESSAGE_RECEIVED, message => {

logger.info('Received a message from ODA, processing message before sending to Twilio.',message);

var str = message.messagePayload.text;

str = str.replace(/<[^>]*>/g, '');

str = str.replace(/\t/g, '');

str = str.replace(/\n/g, '');

str = str.replace(/\\n/g, '');

logger.info('Received a message from ODA, processing message before sending to Twilio.',str);

// Parse the incoming ODA message into TwilML

var response = '<Response> <Gather input="speech dtmf" timeout="3" numDigits="1"> <Say>'+str+'.</Say> </Gather>

</Response>';

var found = false;

for (var idx = 0; idx < resArr.length && !found; idx++)

if (resArr[idx].userId == message.userId)

{

found = true;

resArr[idx].response.send(response);

}

});

Oracle Digital Assistant - TechExchange 17

The next lines of code expose an endpoint for incoming messages from TwilioVoice.

app.post('/user/message', function(req, res) {

var userId = req.body.Caller

logger.info('Received a message from twilio, processing message before sending to ODA.',req.body);

// Initiate greeting if this is the first interction

var message = "Hi";

// set Twilio speech output as the message

if (req.body.SpeechResult)

message = req.body.SpeechResult;

// set Twilio entered digits as the message

if (req.body.Digits)

message = req.body.Digits;

// Set ODA message payload

let messagePayload = {

userId: userId,

"userProfile": {

"firstName": userId,

},

messagePayload: MessageModel.textConversationMessage(message),

metadata: {

webhookChannel: "twilio"

}

};

var found = false;

for (var idx = 0; idx < resArr.length && !found; idx++)

if (resArr[idx].userId == userId)

{

found = true;

resArr.splice(idx,1);

Oracle Digital Assistant - TechExchange 18

}

// Store user session (response object)

resArr[resArr.length] = { "userId": userId, "response": res, "insTime": new Date().getTime() };;

webhook.send(messagePayload);

logger.info('Message Sent successfully to ODA.', messagePayload);

});

When a call is received, then the webhook sends an initial message "hi" to start the conversation. This message is

what you would need to change to something that your skill or digital assistant responds to. The req.body.Caller

property passed from the incoming request contains the calling number and therefore is used as a userId.

Following interactions will have a digit (req.body.Digits) pressed or a NLP Speech-To-Text (req.body.SpeechResult)

result sent. The message received from Twilio is a text message that the webhook wraps into a format understood

by Oracle Digital Assistant.

The user session is then stored into the global array for the bot response to be redirected to the calling user.

If the user remains idle for more than 2 minutes, then the web hook assume the communication has ended and

cleans up the array from the user session.