Oracle Intelligent Bots Tech Exchange20. Open your Oracle Intelligent Bots instance in the public...

Oracle Intelligent Bots – TechExchange

1

Oracle Intelligent Bots

TechExchange

Article.

Oracle Bots Node.js SDK: Building Webhook Clients for Oracle

Intelligent Bots* Made Easy

Frank Nimphius, September 2018

A webhook is a programming interfaces implemented by a system on the web for other programs

subscribe and to receive automated notification in case anything of interest happens. One such system

is chatbot. Users "register" for a chatbot through a messenger client and by sending messages to the

bot. The bot then resolves the request, processes it and returns a response that the original sender

receives. Webhook clients are like adapters that dispatch and manage conversation between a user and

a remote system.

In Oracle Intelligent Bots, channels allow bot designers to expose the bot functionality to a specific type

messenger client. Underneath channels are webhooks. Channels, like Facebook, Web, iOS, Android and

more that are in development, are referred to as "native channels" Native channels are webhook

implementations that exist and that you, as the bot designer, don't have to code for.

For integrating messengers that Oracle Intelligent Bots doesn't have a native channel for, you use the

generic Webhook channel. The Webhook channel in Oracle Intelligent Bots opens up the Oracle bots

platform for any messengers client. All you need to do is to write the webhook implementation.

In this article, I explain the basic steps of creating a webhook client using the Oracle Bots Node.js SDK

available on GitHub and npmjs. In future articles I will use this article as a starting point for explaining

how to integrate Oracle Intelligent Bots with Messenger services like Alexa and Google Hangouts.

*Oracle Intelligent Bots evolves into Oracle Autonomous Digital Assistant, the next generation of chatbots. All

descriptions in the article apply for Oracle Intelligent Bots and Autonomous Digital Assistant. For simplicity reasons,

I use the term Oracle Intelligent Bots for both.

Oracle Intelligent Bots - TechExchange 2

Table of Contents

CREATING YOUR FIRST WEBHOOK CLIENT ....................................................................................................... 3

EXPOSING YOUR WEBHOOK CLIENT TO THE PUBLIC CLOUD ........................................................................ 8

CONFIGURING ACCESS TO ORACLE INTELLIGENT BOTS................................................................................ 9

GETTING READY FOR TESTING........................................................................................................................... 11

HOW-TO DEBUG YOUR WEBHOOK CLIENT....................................................................................................... 14

DEPLOYMENT ......................................................................................................................................................... 17

CONCLUSION ......................................................................................................................................................... 18


Creating Your First Webhook Client

The Oracle Bots Node.js SDK makes building and testing webhook clients easy for any Node container. You can

obtain the SDK from GitHub (https://github.com/oracle/bots-node-sdk) and npmjs (https://www.npmjs.com/package/

@oracle/bots-node-sdk). You install the Oracle Node.js SDK through the npm command in a terminal window as a

starting point for your webhook client* and custom components projects.

*Note: With webhook client I refer to the software that dispatches and routes conversations between a messenger

and the bot. The webhook client uses the webhook API to access Oracle Intelligent Bots and either a webhook or

web sockets to communicate with the remote messaging service, or the messaging app directly. In the latter case,

when the webhook client talks directly to the messenger app, the webhook client needs to also provide message

server capabilities to queue incoming messages from multiple users and to route the bot responses to the user that

sent a request.

1. You start the webhook client development project with an empty folder that you name after the project. In

this article, the folder name is "MyFirstWebHook".

2. Next, navigate to the Oracle Node.js Bots SDK on GitHub (https://github.com/oracle/bots-node-sdk)

3. As shown in the image below, select the Clone or download select button and download the project as a

ZIP file.

https://github.com/oracle/bots-node-sdk

https://www.npmjs.com/package/%20@oracle/bots-node-sdk

https://www.npmjs.com/package/%20@oracle/bots-node-sdk

https://github.com/oracle/bots-node-sdk


4. Extract the downloaded ZIP file and navigate to the bots-node-sdk-master/examples/webhook/starter

folder.

5. Copy all files in the starter folder and paste them into your webhook project folder (MyFirstWebHook in this

article)

6. Open a terminal window and navigate to the webhook client folder (MyFirstWebHook in this article)

7. Ensure you have Node and Node Project Manager (npm) installed (https://www.npmjs.com/get-npm)

8. In the terminal window, issue the following command: npm install

9. The outcome of above command should look like in the image shown below. If you see errors, ensure that

you have a working Internet connection. If your laptop is behind a firewall you may have to set the proxy first

before you can issue the command.

https://www.npmjs.com/get-npm


10. The previous command installed the Node.js dependencies for the webhook starter project. Next, you will

install the Oracle Node.js SDK into the same project

11. In the same terminal window and location, issue the following command:

npm install --save @oracle/bots-node-sdk


12. If both previously mentioned commands finish successfully, then you have a working webhook client project

created. The file and folder structure in your webhook client project should look as shown in the e image

below

13. Open the file index.js. The file contains the Node server and also, in line 7, initiates the Oracle Node.js SDK.

The default port is set to 3000, which you can change in the file or in an environment variable. For now, leave

it at post 3000!

14. Next, open the service.js file, which contains the webhook client implementation.

a. Line 25: This is where you would add the code to pass bot responses back to the messenger (e.g.

like Alexa or Google Hangouts)

b. Line 31: This line registers the URI /bot/message with the setup of the SDK webhook listener. You

change this line if you want to change the web URI for the bot calling the webhook.

c. Line 34: This line registers a POST method call to the /test/message URI. This method is called to

pass a user request – coming from the messenger client – to the bot


15. If you are curious if the webhook works, start it from the terminal window by issuing: node index.js

Then, in a browser URL, type localhost:3000. You will see a note that GET is not implemented for the

webhook application. This did not do anything, but proved that the server works ;-)


Exposing Your Webhook Client to the Public Cloud

So far, you created a Node application as a webhook client. Next you need to expose the application to the public

Internet. Also, for this article I ask you to change the registered URI of the POST methods to be more meaningful

16. Change line 31 to /bot/receivemessage and line 34 to /bot/sendmessage to make it more obvious what they

do

17. If you are like me, then your development machine is not exposed as a server to the Internet. To test your

webhook client, you can use NGROK (no subscription required) to temporarily expose your machine to the

Internet (https://ngrok.com/download)

18. To expose a port 3000, which is the webhook client port, to the Internet, issue the following command from

where you installed ngrok

ngrok http 3000

Note: By experience, sometimes and especially on Windows machines, ngrok may not work. In this case

you can look for alternative solutions like local tunnel (https://github.com/localtunnel/localtunnel)

https://ngrok.com/download


Note: If you don't use a named account for ngrok, then the https URL changes each time you start the tunnel.

This means that you need to update the bot webhook configuration explained on pages 10 and 11 after each

restart. Same is true for other tunnels like "local tunnel"

19. The Node server you started on port 3000 should still be up and running. So, in a browser, replace

localhost:3000 with the https URL you get from the tunneling software. The result, shown in the image below,

should be the same that GET is not implemented on the server.

Note: If you cannot use ngrok or any other tunnel, then deploy your Node project to an Internet facing server

like Oracle Application Container Cloud Service (ACCS).

Configuring Access to Oracle Intelligent Bots

Okay, so you have the webhook client running on port 3000 (or a different port if using ACCS) and exposed to the

Internet. Next, you register the webhook client in your Oracle Intelligent Bots chatbot. For this article, I continue my

explanation using the ngrok URL.

20. Open your Oracle Intelligent Bots instance in the public cloud

21. In your Oracle Intelligent Bots dashboard, open your bot and click the settings menu item (left hand side)

22. Select the Channel tab (link on top)

23. Click the + Channel button

24. Edit the Create Channel dialog as shown in the image below


• Name – The display name of the channel

• Channel Type – Select "Webhook"

• Platform Version – Select 1.1 for the conversational model. Version 1.0 should only be used for

clients that don't understand rich UI elements like card layouts and is merely for backward

compatibility

• Outgoing Webhook URI – Add the Webhook Client root URL (ngrok during development in this

article) and append the /bot/receivemessage URI (see page 8 for why this is)

• Session Expiration – Define when an inactive chat session should expire. You can configure an

expiry time of max. 60 minutes.

• Channel Enabled – Ensure the channel is enabled as shown in the image above. Otherwise, the

configuration would be valid, but the channel is not accessible from external.

25. Notice the Secret Key and the Webhook URL in the dialog shown in the image below (of course, the values

will be different for your channel configuration).


Getting Ready for Testing

At this point, you have a webhook client created and exposed to the Internet, and an Oracle Intelligent Bots bot

webhook channel created and configured for it. Next is that you need to be able to test the webhook client, which is

an important step before you can build the implementation code between the webhook client and the messaging

service or client.

26. Add an app.get function as shown below. You can copy the code that I provide below the next image and

paste it to your service.js file as shown in the image below (line 34).

//TESTER

app.get('/bot/tester', (req, res) => {

const { user, text } = {user: "Frank", text: req.query.text};

// construct message to bot from the client message format

const MessageModel = webhook.MessageModel();

const message = {


userId: user,

messagePayload: MessageModel.textConversationMessage(text)

};

// send to bot webhook channel

webhook.send(message)

.then(() => res.send('ok'), e => res.status(400).end(e.message));

});

Note: I this article I like you to test the webhook from a browser Window. As you already learned that support for a GET method is not provided by the webhook client, you added it. This GET method should be removed from any production deployment! Also note the "text" query parameter that allows you to pass information into the webhook. Important: The user property in const { user, text } = {user: "Frank", text:

req.query.text} should be a string (other than 'Frank') that uniquely identifies the user sending

the request. The string is passed back as the "userId" from the bot along with the response, allowing you to route the response to the user and messenger client that sends a request.

27. Also in the service.js file, on top, you find the definition of the webhook constant. This constant needs to get

the bot webhook and webhook secret key information (explained on pages 10 and 11). You can copy and

paste the Webhook URL and the Secret Key as a value, or better use environment variables.

Note: When you deploy the webhook client to a public Node server like Oracle Application Container Cloud

Service (ACCS), then you set BOT_WEBHOOK_URL and BOT_WEBHOOK_SECRET as an environment

variable. Hardcoding secret keys and webhook URLs is considered bad coding practices,

28. To use environment variables, first stop the running webhook client server by pressing ctrl+c in the terminal

window that runs the Node server

29. Use exports commands as shown below to define the environment variables: BOT_WEBHOOK_URL and

BOT_WEBHOOK_SECRET

30. Start the server again by issuing: node index.js

31. When the server is up and running, you can now open a browser and type the following into the URL field


<ngrok root url>/bot/tester?text=<message>

The sample bot I used for writing this article was a weather bot (your bot will be a different one and as such

the messages you send to start and have the conversation are different) . In my case, the bot conversation

gets initiated with a simple "hi".

<ngrok url>/bot/tester?text=hi

The bot replied to the message, introducing itself and asking for a city name. So the next URL I typed and

submitted was

<ngrok url>/bot/tester?text=London

You can see the printed bot responses in the terminal window that started the webhook client Node server

32. Next, my example bit wants to know about the country the city is in (I agree, it's not the smartest bot that

I've written for a test)


Note: As you see in the printed message (image above), it says "cards: [[Object]]". This is okay for a printed

output as my weather response is displayed on a card layout. The Oracle Node.js SDK provides an option

to translate those objects to a text message if the message client doesn't support cards (e.g. Alexa).

What you did: If you followed the instructions in this article, the by now you have a webhook client created and

started on your local machine. You configured it to talk to one of your chatbots on the Oracle public cloud and tested

if from a browser. If all worked well, then, like for me, you could interact with the chatbot from the browser.

What is next: The next step is to create an implementation in the service.js file to return bot responses to the

messenger service or client (like Alexa or Google Hangout) → (see page 6, point 14 a). The implementation of a

messenger service or client is not covered in this article but will become subject of a separate article. The goal of this

article was to explain the basic setup instructions that get you started-

How-to Debug your Webhook Client

Debugging software is a developer's bread and butter. Until here, the Webhook client only contains the basic

elements and does not yet connect to a messenger client or service. So there is some work left to do, for which being

able to debug the Webhook client is inevitable. To understand Node.js debugging, please refer to

https://nodejs.org/en/docs/guides/debugging-getting-started/.

33. To start the webhook client in debugging mode, first stop the running server, which you do with issuing ctrl+c

on the terminal window.

34. Then, start the server with the --inspect option

35. node --inspect index.js (notice the two dashes "--")

36. To debug the running webhook client, you need an IDE that supports Node debugging. A free IDE for this is

Microsoft Visual Studio Code (https://code.visualstudio.com/

37. Note: I am not advocating MS Visual Studio Code as the best IDE for it. There are others that could do this

as good, and some are even more intuitive to use. However, for this article, I explain the setup for MS Visual

Studio Code.

https://nodejs.org/en/docs/guides/debugging-getting-started/

https://code.visualstudio.com/


38. In MS Visual Studio Code, select the debug icon (left hand side)

39. In the DEBUG select list, choose the Add Configuration option as shown in the image below

40. In the opened launch.json file, select the Node.js: Attach option

41. Change the name property to something related to your project. In the example for this article I chose "Debug

MyFirstWebhook"


42. Save the file and close it 43. Open service.js and set a break point as shown in the image below

44. The webhook client was started in debug mode before, so now attach the IDE to it. For this, in the DEBUG

select list, choose the debugger setting you created step 40 and 41 (In my example, the name of the

configuration is "Debug MyFirstWebhook")

45. Go back to the browser URL and start communicating with your chatbot

46. If you setup debugging correctly, then you should see the bot communication to stop at the breakpoint, which

is right after the bot replied to the user request. As shown in the image below, you can look at objects by

hovering over variables in the code editor or watch them in the debug console.


Note: For security reasons, please don't forget to remove the app.get('bot/tester', …) function in the service.js file before deploying the webhook client to a production system. Note: Make sure you stop any tunnelling software you used. Tunneling is a development help but should not be used any longer than that. It's better to restart when needed than to leave it up and running.

Deployment

I mentioned it earlier but want to make sure this is understood. The webhook client is a node application that needs

to be deployed to a node server of a cloud service supporting node deployments. In Oracle public cloud, such a

service is Oracle Application Container Cloud Service (ACCS).

In any way, you package the webhook client for deployment by zipping all files and folders within the webhook client

project (MyFirstWebHook folder in this article).

For deployment to ACCS, you need to add a file, manifest.json, to the webhook client project folder before creating

the ZIP file for deployment. The content of this file should look like this

{

"runtime":{

"majorVersion":"8"

},

"command": "node index.js",

"mode": "rolling"


}

Conclusion

The webhook channel in Oracle Intelligent Bots allows you to create custom webhook clients that connect a chatbot

with any messenger service or messenger client. It’s a silver-bullet-solution that allows you to use Oracle Intelligent

Bots with any messenger that Oracle does not yet provide native support for.

In this article I explained how to setup a starter project for developing a webhook client for Oracle Intelligent Bots

using the Oracle Node.js SDK available on npmjs and GitHub. I also explained how to test the webhook client and

configure it for debugging in an IDE.

The aim of this article was to get you ready for building the messenger interaction between Oracle Intelligent Bots

and the messenger service or messenger client. An example of how to create the messenger implementation (e.g.

for Alexa or Google Hangouts) is planned for a later article.

Oracle Intelligent Bots Tech Exchange20. Open your Oracle Intelligent Bots instance in the public...

Documents

Transcript of Oracle Intelligent Bots Tech Exchange20. Open your Oracle Intelligent Bots instance in the public...